Agent tasks API
An agent’s task list: add, read, update and stop tasks.
Endpoints
/api/v1/agentTasks/addAdd 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
agentId | stringrequired | The agent id |
goal | stringrequired | |
doneWhen | string | How anyone can tell the task is done, in plain words. |
startsBySelf | string | 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: |
startAt | stringnull | 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"
}'/api/v1/agentTasks/listOne 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
agentId | stringrequired | |
status | string | A filter. Allowed values: |
limit | integer |
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": {}
}'/api/v1/agentTasks/getOne 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
taskId | stringrequired |
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"
}'/api/v1/agentTasks/updateChange 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
taskId | stringrequired | |
goal | string | |
doneWhen | string | How anyone can tell the task is done, in plain words. |
status | string | Allowed values: |
startsBySelf | string | Allowed values: |
startAt | stringnull |
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"
}'/api/v1/agentTasks/stopStop 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
taskId | stringrequired | |
reason | stringrequired |
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"
}'