> 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.

# Update a task

PATCH https://api.athenaintel.com/api/v0/tasks/{asset_id}
Content-Type: application/json

Change a task: a field left out is kept, and an explicit null clears it (title and status cannot be cleared). Needs edit access, and the task must not be in the trash. Labels and links are replaced whole; links already on it that the caller cannot open are kept. Marking it done records who and when.

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

## Authentication

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

## Request

### Path parameters

- `asset_id` (string, required) — The task's asset id.

### Body (application/json)

This endpoint expects an UpdateTaskRequestIn.

- `assignee_ref` (string, optional, nullable) — user_…, agent_asset_… or me; null assigns it to nobody. The assignee must already be able to open the task.
- `description` (string, optional, nullable) — New details (markdown); null clears them.
- `due_date` (string, optional, nullable) — YYYY-MM-DD; null clears the due date and its time.
- `due_time` (string, optional, nullable) — HH:MM (24-hour); null clears the time and keeps the date.
- `due_time_zone` (string, optional, nullable) — The IANA time zone of due_time.
- `labels` (list of TaskLabelIn, optional, nullable) — The full new set of labels; null removes them all.
- `links` (list of TaskLinkIn, optional, nullable) — The full new set of links; null removes them all. Links already on the task that the caller cannot open are kept.
- `priority` (enum, optional, nullable) — How much it matters; null is none.
  - Allowed values: `none`, `low`, `medium`, `high`
- `status` (enum, optional, nullable) — open or done (it cannot be cleared).
  - Allowed values: `open`, `done`
- `title` (string, optional, nullable) — A new title (it cannot be cleared).

## Response

### 200

The task as changed, read as the caller.

- `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)

## Errors

### 400 Bad Request Error

A field cannot be a task's.

- `any`

### 401 Unauthorized Error

The API key or token is missing or not valid.

- `any`

### 403 Forbidden Error

The caller can open the task but may not change it: no edit access, the task is in the trash, or an assignee or link they may not give it.

- `any`

### 404 Not Found Error

No task the caller can open has this id: no asset has it, it is not a task, or the caller may not open it. All are answered alike.

- `any`

### 422 Unprocessable Entity Error

Validation Error

- `detail` (list of ValidationError, optional)

### 503 Service Unavailable Error

Tasks are not ready on this deployment yet (its database update has not run).

- `any`

## Types

### TaskLabelIn

A label to put on a task.

- `name` (string, required) — The label's name (at most 64 characters, matched case-insensitively).
- `color` (string, optional, nullable) — #RRGGBB. Left out, a label the task already has keeps its color.

### TaskLinkIn

A record a task is about: an asset, an ontology object or a web page.

- `referenced` (enum, required) — asset, ontology_object or external_url.
  - Allowed values: `asset`, `ontology_object`, `external_url`
- `anchor` (map from string to any, optional, nullable) — A place inside the asset (a cell range, a page), when one is meant.
- `id` (string, optional, nullable) — The asset or ontology object id (asset and ontology_object).
- `url` (string, optional, nullable) — The web page's URL (external_url).

### 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.

### ValidationError

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

### ValidationErrorLocItems

- string
- integer

### ValidationErrorCtx

## Examples

**Request**

```json
{
  "priority": "medium"
}
```

**Response**

```json
{
  "assignee": {
    "display_name": "Ada Lovelace",
    "kind": "person",
    "ref": "user_123"
  },
  "can_edit": true,
  "completed_at": "2024-01-15T09:30:00Z",
  "completed_by_ref": "string",
  "created_at": "2026-11-11T15:00:00+00:00",
  "created_by": "user_123",
  "description": "string",
  "due_date": "2026-11-13",
  "due_time": "15:00",
  "due_time_zone": "America/New_York",
  "id": "asset_7c1e5b2a-4f3d-4e8a-9b6c-1d2e3f4a5b6c",
  "is_archived": false,
  "labels": [
    {
      "applied_at": "2026-11-11T15:00:00+00:00",
      "applied_by_ref": "user_123",
      "color": "string",
      "name": "Investor"
    }
  ],
  "links": [
    {
      "detail": "string",
      "id": "string",
      "readable": true,
      "referenced": "external_url",
      "title": "example.com",
      "url": "https://example.com"
    }
  ],
  "priority": "high",
  "status": "open",
  "title": "Send the deck to Mayfield",
  "updated_at": "2026-11-11T15:00:00+00:00",
  "workspace_id": "ws_abc123-def456"
}
```

**SDK Code**

```python
import requests

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

payload = { "priority": "medium" }
headers = {
    "X-API-KEY": "<apiKey>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.athenaintel.com/api/v0/tasks/asset_id';
const options = {
  method: 'PATCH',
  headers: {'X-API-KEY': '<apiKey>', 'Content-Type': 'application/json'},
  body: '{"priority":"medium"}'
};

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"
	"strings"
	"net/http"
	"io"
)

func main() {

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

	payload := strings.NewReader("{\n  \"priority\": \"medium\"\n}")

	req, _ := http.NewRequest("PATCH", url, payload)

	req.Header.Add("X-API-KEY", "<apiKey>")
	req.Header.Add("Content-Type", "application/json")

	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/asset_id")

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

request = Net::HTTP::Patch.new(url)
request["X-API-KEY"] = '<apiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"priority\": \"medium\"\n}"

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.patch("https://api.athenaintel.com/api/v0/tasks/asset_id")
  .header("X-API-KEY", "<apiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"priority\": \"medium\"\n}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('PATCH', 'https://api.athenaintel.com/api/v0/tasks/asset_id', [
  'body' => '{
  "priority": "medium"
}',
  'headers' => [
    'Content-Type' => 'application/json',
    'X-API-KEY' => '<apiKey>',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://api.athenaintel.com/api/v0/tasks/asset_id");
var request = new RestRequest(Method.PATCH);
request.AddHeader("X-API-KEY", "<apiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"priority\": \"medium\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "X-API-KEY": "<apiKey>",
  "Content-Type": "application/json"
]
let parameters = ["priority": "medium"] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.athenaintel.com/api/v0/tasks/asset_id")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "PATCH"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

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()
```