> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.athenaintel.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.athenaintel.com/_mcp/server.

# List tasks

GET https://api.athenaintel.com/api/v0/tasks

The tasks of a workspace the caller belongs to that they can open, soonest due first (tasks with no due date last, newest first). Open tasks unless status says otherwise. Filter by assignee (me for the caller's own), due dates (calendar days, inclusive), a label's name or a record the task links. A listed task carries no links and a null can_edit: read one task for them.

Reference: https://docs.athenaintel.com/api-reference/tasks/list

## Authentication

- `X-API-KEY` header (required) — API Key authentication via header

## Request

### Query parameters

- `workspace_id` (string, required) — The workspace to list; the caller must be a member.
- `assignee_ref` (string, optional, nullable) — Only tasks assigned to this user_… or agent_asset_…, or me.
- `status` (enum, optional, default: open) — open (the default), done or all.
  - Allowed values: `open`, `done`, `all`
- `due_on_or_before` (string, optional, nullable) — YYYY-MM-DD: only tasks due on or before this day.
- `due_on_or_after` (string, optional, nullable) — YYYY-MM-DD: only tasks due on or after this day.
- `label` (string, optional, nullable) — Only tasks with a label of exactly this name.
- `linked_id` (string, optional, nullable) — Only tasks that link this asset or ontology object id.
- `limit` (integer, optional, default: 200) — At most this many tasks.

## Response

### 200

The tasks.

- `items` (list of TaskOut, required) — At most `limit` tasks; each carries no links and a null can_edit.

## Errors

### 400 Bad Request Error

A filter cannot be read (a bad date or assignee).

- `any`

### 401 Unauthorized Error

The API key or token is missing or not valid.

- `any`

### 403 Forbidden Error

The caller is not a member of the workspace named, or (on create) may not give the task that assignee, link or folder.

- `any`

### 422 Unprocessable Entity Error

Validation Error

- `detail` (list of ValidationError, optional)

## Types

### TaskOut

An assignable to-do: due on a calendar day, at a time in due_time_zone.

- `assignee` (TaskAssigneeOut, required, nullable) — Who it is for, or null for nobody.
- `can_edit` (boolean, required, nullable) — Whether the caller may change it; null in a list.
- `completed_at` (datetime, required, nullable) — When it was marked done.
- `completed_by_ref` (string, required, nullable) — Who marked it done.
- `created_at` (datetime, required, nullable)
- `created_by` (string, required, nullable) — The user who created it.
- `description` (string, required, nullable) — Markdown.
- `due_date` (string, required, nullable) — YYYY-MM-DD, or null.
- `due_time` (string, required, nullable) — HH:MM (24-hour), or null.
- `due_time_zone` (string, required, nullable) — The IANA time zone of due_time.
- `id` (string, required) — The task's asset id.
- `is_archived` (boolean, required) — Whether it is in the trash.
- `labels` (list of TaskLabelOut, required)
- `links` (list of TaskLinkOut, required) — The records it is about, read as the caller. Always empty in a list.
- `priority` (enum, required)
  - Allowed values: `none`, `low`, `medium`, `high`
- `status` (enum, required)
  - Allowed values: `open`, `done`
- `title` (string, required)
- `updated_at` (datetime, required, nullable)
- `workspace_id` (string, required)

### ValidationError

- `loc` (list of ValidationErrorLocItems, required)
- `msg` (string, required)
- `type` (string, required)
- `ctx` (ValidationErrorCtx, optional)
- `input` (any, optional)

### TaskAssigneeOut

Who a task is assigned to: a person or an agent.

- `display_name` (string, required, nullable) — Their name, when the caller may see it (an agent's only when they can open it).
- `kind` (enum, required) — person or agent.
  - Allowed values: `person`, `agent`
- `ref` (string, required) — user_… for a person, agent_asset_… for an agent.

### TaskLabelOut

A label on a task: its name, color and who applied it.

- `applied_at` (string, required) — When it was applied (ISO 8601).
- `applied_by_ref` (string, required) — Principal ref of who applied it.
- `color` (string, required, nullable) — #RRGGBB, or null.
- `name` (string, required)

### TaskLinkOut

A record a task is about, read as the caller.

- `detail` (string, required, nullable) — Its asset or object type, read as the caller.
- `id` (string, required, nullable) — The asset or object id; null when unreadable.
- `readable` (boolean, required) — Whether the caller can open it. One they can't shows its kind only: no id, URL or title.
- `referenced` (string, required) — asset, ontology_object or external_url.
- `title` (string, required, nullable) — Its title, read as the caller.
- `url` (string, required, nullable) — The web page's URL; null when unreadable.

### ValidationErrorLocItems

- string
- integer

### ValidationErrorCtx

## Examples

**Response**

```json
{
  "items": [
    {
      "assignee": {
        "display_name": "string",
        "kind": "person",
        "ref": "string"
      },
      "can_edit": true,
      "completed_at": "2024-01-15T09:30:00Z",
      "completed_by_ref": "string",
      "created_at": "2024-01-15T09:30:00Z",
      "created_by": "string",
      "description": "string",
      "due_date": "string",
      "due_time": "string",
      "due_time_zone": "string",
      "id": "string",
      "is_archived": true,
      "labels": [
        {
          "applied_at": "string",
          "applied_by_ref": "string",
          "color": "string",
          "name": "string"
        }
      ],
      "links": [
        {
          "detail": "string",
          "id": "string",
          "readable": true,
          "referenced": "string",
          "title": "string",
          "url": "string"
        }
      ],
      "priority": "none",
      "status": "open",
      "title": "string",
      "updated_at": "2024-01-15T09:30:00Z",
      "workspace_id": "string"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://api.athenaintel.com/api/v0/tasks"

querystring = {"workspace_id":"workspace_id"}

headers = {"X-API-KEY": "<apiKey>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript
const url = 'https://api.athenaintel.com/api/v0/tasks?workspace_id=workspace_id';
const options = {method: 'GET', headers: {'X-API-KEY': '<apiKey>'}};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.athenaintel.com/api/v0/tasks?workspace_id=workspace_id"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-KEY", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.athenaintel.com/api/v0/tasks?workspace_id=workspace_id")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-KEY"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.athenaintel.com/api/v0/tasks?workspace_id=workspace_id")
  .header("X-API-KEY", "<apiKey>")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.athenaintel.com/api/v0/tasks?workspace_id=workspace_id', [
  'headers' => [
    'X-API-KEY' => '<apiKey>',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.athenaintel.com/api/v0/tasks?workspace_id=workspace_id");
var request = new RestRequest(Method.GET);
request.AddHeader("X-API-KEY", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = ["X-API-KEY": "<apiKey>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.athenaintel.com/api/v0/tasks?workspace_id=workspace_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```