Back to API Overview

Agent tasks API

An agent’s task list: add, read, update and stop tasks.

5 endpoints

Endpoints

POST
/api/v1/agentTasks/add

Add a task to one agent's task list (it outlives runs, like a to-do list the agent works through). Params: agentId (aiAgent_listSpecialists), goal (one line, at most 300 characters), doneWhen? (how anyone can tell it is done, in plain words), startsBySelf?, startAt?. When the agent works through its to-do (or startsBySelf "yes"), it starts by itself when the agent is free, one at a time, within its limits; a limit leaves it Planned with the reason. A start of the agent with no task text takes its oldest Planned task (every start is one task), is told the goal and "Done when", and keeps the status itself. Returns { id }. From the AI, switching on what starts an agent by itself waits for the person's OK (the approval card); switching off is at once. A task that starts by itself (yes or startAt) is one of those.

Parameters

agentIdstringrequired

The agent id

goalstringrequired
doneWhenstring

How anyone can tell the task is done, in plain words.

startsBySelfstring

Starts by itself? agent = the agent's "Work through its to-do" setting (default); yes = as soon as the agent is free; no = waits for its schedule or Run a task.

Allowed values: agent, yes, no

startAtstringnull

When it starts by itself (ISO date-time from now on; a past time is refused). Busy then: it goes next.

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/agentTasks/add \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "agentId": "example",
  "goal": "example",
  "doneWhen": "example"
}'
POST
/api/v1/agentTasks/list

One agent's tasks, newest first; a Lead's adds its group members'. Params: agentId, status? (planned, working, waiting_on_you, done or stopped), limit?. Each task: id, agentId, goal, doneWhen, status, reason (why it is stopped or waiting on you), startsBySelf, startAt, runId, threadId, costCredits, source (where it came from), parentTaskId (the task that started it), createdAt, updatedAt.

Parameters

agentIdstringrequired
statusstring

A filter.

Allowed values: planned, working, waiting_on_you, done, stopped

limitinteger

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/agentTasks/list \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "agentId": "example",
  "status": "example",
  "limit": {}
}'
POST
/api/v1/agentTasks/get

One task by taskId: id, agentId, goal, doneWhen, status, reason, startsBySelf, startAt, runId, threadId, costCredits, source (where it came from), parentTaskId (the task that started it), handedByAgentId, children (tasks it started: id, agentId, source, status, result), createdAt, updatedAt.

Parameters

taskIdstringrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/agentTasks/get \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "taskId": "example"
}'
POST
/api/v1/agentTasks/update

Change one task. Params: taskId, goal? (one line), doneWhen?, status? ("planned" puts a waiting or stopped task back on the list, for a start with no task text to take; "done" closes it).

Parameters

taskIdstringrequired
goalstring
doneWhenstring

How anyone can tell the task is done, in plain words.

statusstring

Allowed values: planned, done

startsBySelfstring

Allowed values: agent, yes, no

startAtstringnull

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/agentTasks/update \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "taskId": "example",
  "goal": "example",
  "doneWhen": "example"
}'
POST
/api/v1/agentTasks/stop

Stop a task (not done) so no run takes it; stops its run (params: taskId, reason: why, in plain words). Reopen: agentTasks_update status "planned".

Parameters

taskIdstringrequired
reasonstringrequired

Example Request

curl -X POST https://app.serenitiesai.com/api/v1/agentTasks/stop \
  -H "Authorization: Bearer mk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
  "taskId": "example",
  "reason": "example"
}'