API reference
The key-authenticated endpoints used by the Takibi CLI and integrations. One contract, available as OpenAPI.
Authentication
Use a Profile key as a Bearer token. Every key in a Profile shares its document grants. Required capabilities and task ownership rules still apply.
Authorization: Bearer <publicId>.<secret>Base URL: https://app.takibibase.com. This reference covers the key-authenticated collection, retrieval, task, and note operations. Human administration and billing use separate authenticated app routes.
Ask a question
GET /v1/askRequires ask capability. Returns verbatim passages and citations; may abstain. Jev failures can fall back to deterministic extraction.
| Parameter | Description |
|---|---|
qRequired · query | Question to answer from source evidence. |
projectIdOptional · query | Project UUID. May be omitted only when the key resolves to a single project. |
folderIdOptional · query | Narrow retrieval to a granted folder. |
kOptional · query | Candidate count, clamped to 1–12. |
Responses and error codes
{
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AskAnswer"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing, invalid, paused or revoked key, or human-only route.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Capability or access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Daily budget spent (error.code DAILY_BUDGET_EXCEEDED) or minute throttle (RATE_LIMITED).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}Ask with a JSON body
POST /v1/askSame extractive answer contract as GET. Requires ask capability.
Request body schema
{
"type": "object",
"properties": {
"q": {
"type": "string"
},
"projectId": {
"type": "string",
"format": "uuid"
},
"folderId": {
"type": "string",
"format": "uuid"
},
"k": {
"type": "integer",
"minimum": 1,
"maximum": 12,
"default": 10
}
},
"required": [
"q"
]
}Responses and error codes
{
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/AskAnswer"
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing, invalid, paused or revoked key, or human-only route.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Capability or access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Daily budget spent (error.code DAILY_BUDGET_EXCEEDED) or minute throttle (RATE_LIMITED).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}Search source snippets
GET /v1/searchRequires search capability. Returns ranked snippets, not full document text.
| Parameter | Description |
|---|---|
qRequired · query | Search query. |
projectIdOptional · query | Project UUID. May be omitted only when the key resolves to a single project. |
folderIdOptional · query | Narrow retrieval to a granted folder. |
kOptional · query | Maximum results, 1–20. |
Responses and error codes
{
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"results": {
"type": "array",
"items": {
"$ref": "#/components/schemas/SearchHit"
}
}
},
"required": [
"results"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing, invalid, paused or revoked key, or human-only route.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Capability or access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Daily budget spent (error.code DAILY_BUDGET_EXCEEDED) or minute throttle (RATE_LIMITED).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}List accessible documents
GET /v1/documentsProfile keys see only indexed documents within their grants.
| Parameter | Description |
|---|---|
projectIdOptional · query | Project UUID. May be omitted only when the key resolves to a single project. |
folderIdOptional · query | Narrow retrieval to a granted folder. |
Responses and error codes
{
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"documents": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Document"
}
}
},
"required": [
"documents"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing, invalid, paused or revoked key, or human-only route.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Capability or access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate or daily budget limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}File a document
POST /v1/documentsRequires documents:ingest capability. JSON callers send exactly one of text or contentBase64; multipart callers attach file=. Keys file one document per call and spend a daily ask. Refusals (duplicate, empty, oversize, unparseable) return 201 with a refused entry, never an error.
Request body schema
{
"type": "object",
"properties": {
"name": {
"type": "string",
"maxLength": 255
},
"text": {
"type": "string",
"maxLength": 500000
},
"contentBase64": {
"type": "string",
"description": "File bytes as base64. Exactly one of text or contentBase64."
},
"projectId": {
"type": "string",
"format": "uuid"
},
"folderId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"name"
]
}Responses and error codes
{
"201": {
"description": "Stored documents plus refused entries.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"documents": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Document"
}
},
"refused": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"reason": {
"type": "string"
},
"code": {
"type": "string",
"description": "Machine-readable refusal code (IngestError code, or DUPLICATE). Additive: reason text is unchanged."
},
"reasonCode": {
"type": "string",
"description": "Skip sub-reason (the quality-gate reason, e.g. wrong-language). Present on SKIP_UNRECOVERABLE refusals only."
},
"existingId": {
"type": "string",
"format": "uuid"
}
}
}
}
},
"required": [
"documents",
"refused"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing, invalid, paused or revoked key, or human-only route.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Capability or access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Daily budget spent (error.code DAILY_BUDGET_EXCEEDED) or minute throttle (RATE_LIMITED).",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}Get document metadata
GET /v1/documents/{id}Returns metadata for an accessible indexed document.
| Parameter | Description |
|---|---|
idRequired · path | Resource UUID. |
projectIdOptional · query | Project UUID. May be omitted only when the key resolves to a single project. |
Responses and error codes
{
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"document": {
"$ref": "#/components/schemas/Document"
}
},
"required": [
"document"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing, invalid, paused or revoked key, or human-only route.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Capability or access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate or daily budget limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}Read converted text
GET /v1/documents/{id}/textReturns the converted text within the Profile document grants. Large responses may be truncated.
| Parameter | Description |
|---|---|
idRequired · path | Resource UUID. |
projectIdOptional · query | Project UUID. May be omitted only when the key resolves to a single project. |
Responses and error codes
{
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"text": {
"type": "string"
},
"truncated": {
"type": "boolean"
}
},
"required": [
"text",
"truncated"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing, invalid, paused or revoked key, or human-only route.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Capability or access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate or daily budget limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}List accessible collections
GET /v1/projectsAny authenticated key. Returns the collections (projects) the key's grants cover, for scoping other calls. Key callers also get their profile identity for labeling the connection.
Responses and error codes
{
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"projects": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Project"
}
},
"profile": {
"type": "object",
"description": "Present for profile-key callers only; identifies whose grants scoped the list.",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
]
}
},
"required": [
"projects"
]
}
}
}
},
"401": {
"description": "Missing, invalid, paused or revoked key, or human-only route.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Capability or access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate or daily budget limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}Append a lesson note
POST /v1/notesRequires notes:append capability. Appends a lesson to the key's own profile. The template is validated and secret-blocked; repeated identical calls return the existing note (idempotent on run id and body hash).
Request body schema
{
"type": "object",
"properties": {
"projectTag": {
"type": "string"
},
"template": {
"type": "object",
"properties": {
"problem": {
"type": "string"
},
"tried": {
"type": "string"
},
"worked": {
"type": "string"
},
"failed": {
"type": "string"
},
"next_time": {
"type": "string"
}
},
"required": [
"problem"
]
}
},
"required": [
"template"
]
}Responses and error codes
{
"201": {
"description": "Note appended.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"note": {
"$ref": "#/components/schemas/Note"
},
"duplicate": {
"type": "boolean"
}
},
"required": [
"note"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing, invalid, paused or revoked key, or human-only route.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Capability or access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Template secret blocked.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate or daily budget limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}List the project task board
GET /v1/tasksRequires tasks capability and a whole-collection grant on the project. Folder-only or tag-only keys get 403 on every task route.
| Parameter | Description |
|---|---|
projectIdOptional · query | Project UUID. May be omitted only when the key resolves to a single project. |
includeArchivedOptional · query | Set to 1 to include archived tasks. |
orderOptional · query | Sort by creation time: asc (default, oldest first) or desc (newest first, for polling). |
createdAfterOptional · query | ISO timestamp cursor: matches that card again plus anything newer. Inclusive on purpose; pollers dedupe by id. The page still applies. |
limitOptional · query | Max cards on the project branch, clamped to 1-100. Omit for the uncapped default. The org-wide union branch always caps (default 20, max 100). |
Responses and error codes
{
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"tasks": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Task"
}
}
},
"required": [
"tasks"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing, invalid, paused or revoked key, or human-only route.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Capability or access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate or daily budget limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}Create a task card
POST /v1/tasksRequires task:create capability and a whole-collection grant on the project. Assigning another profile needs task:assign. Title and body are secret-scanned; instruction-shaped lines are neutralized for key callers.
Request body schema
{
"type": "object",
"properties": {
"projectId": {
"type": "string",
"format": "uuid"
},
"title": {
"type": "string",
"maxLength": 300
},
"body": {
"type": "string",
"maxLength": 20000
},
"assigneeProfileId": {
"type": "string",
"format": "uuid"
},
"dueAt": {
"type": "string",
"format": "date-time"
}
},
"required": [
"title"
]
}Responses and error codes
{
"201": {
"description": "Card created.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"task": {
"$ref": "#/components/schemas/Task"
}
},
"required": [
"task"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing, invalid, paused or revoked key, or human-only route.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Capability or access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Secret blocked or assignee ineligible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate or daily budget limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}List eligible task assignees
GET /v1/tasks/assigneesRequires tasks capability and a whole-collection grant on the project. Returns the profiles a card on this board can be assigned or handed to, by id and name.
| Parameter | Description |
|---|---|
projectIdOptional · query | Project UUID. May be omitted only when the key resolves to a single project. |
Responses and error codes
{
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"assignees": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
}
},
"required": [
"id",
"name"
]
}
}
},
"required": [
"assignees"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing, invalid, paused or revoked key, or human-only route.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Capability or access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate or daily budget limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}Claim an available task
POST /v1/tasks/{id}/claimRequires a Profile key with tasks capability. Claims an unassigned todo task for that Profile. Repeating your own successful claim is safe.
| Parameter | Description |
|---|---|
idRequired · path | Resource UUID. |
projectIdOptional · query | Project UUID. May be omitted only when the key resolves to a single project. |
Responses and error codes
{
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"task": {
"$ref": "#/components/schemas/Task"
}
},
"required": [
"task"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing, invalid, paused or revoked key, or human-only route.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Capability or access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Task state or ownership conflict.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}Spin a follow-up off a task
POST /v1/tasks/{id}/follow-upsRequires task:create and tasks capabilities plus a whole-collection grant on the source card's project. Creates a fresh todo card in the source card's project linked back to it; the source card is never modified. No blocked, escalation, review-note, or artifact state carries over. The link is set once at creation and cannot be edited.
| Parameter | Description |
|---|---|
idRequired · path | Source task UUID. |
Request body schema
{
"type": "object",
"properties": {
"title": {
"type": "string",
"maxLength": 300
},
"body": {
"type": "string",
"maxLength": 20000
},
"assigneeProfileId": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"dueAt": {
"type": [
"string",
"null"
]
}
},
"required": [
"title"
]
}Responses and error codes
{
"201": {
"description": "Follow-up created.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"task": {
"$ref": "#/components/schemas/Task"
}
},
"required": [
"task"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing, invalid, paused or revoked key, or human-only route.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Capability or access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Secret blocked or unprocessable state.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate or daily budget limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}Escalate a task to the Founder
POST /v1/tasks/{id}/escalateRequires tasks capability. Own cards on tasks, any card with task:assign. The card must have a current assignee; reason required (max 500 chars). Raising never unassigns the holder. Archived, done, and already-flagged cards refuse; the flag auto-clears on done, archive, and assignee change.
| Parameter | Description |
|---|---|
idRequired · path | Resource UUID. |
projectIdOptional · query | Project UUID. May be omitted only when the key resolves to a single project. |
Request body schema
{
"type": "object",
"properties": {
"reason": {
"type": "string",
"maxLength": 500
}
},
"required": [
"reason"
]
}Responses and error codes
{
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"task": {
"$ref": "#/components/schemas/Task"
}
},
"required": [
"task"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing, invalid, paused or revoked key, or human-only route.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Capability or access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Task state or ownership conflict.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Secret blocked or unprocessable state.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}Clear a task escalation
DELETE /v1/tasks/{id}/escalationRequires tasks capability. The Founder, the profile that raised the flag, or any task:assign holder may clear. Clearing a card that is not flagged 404s.
| Parameter | Description |
|---|---|
idRequired · path | Resource UUID. |
projectIdOptional · query | Project UUID. May be omitted only when the key resolves to a single project. |
Responses and error codes
{
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"task": {
"$ref": "#/components/schemas/Task"
}
},
"required": [
"task"
]
}
}
}
},
"401": {
"description": "Missing, invalid, paused or revoked key, or human-only route.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Capability or access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}Accept a task in review
POST /v1/tasks/{id}/acceptRequires tasks capability. Records the accept verdict on a review card without closing it — the card stays in review until placed (Done to close, To do to continue; the holder may place it, verdict stays). Review-only; blocked cards 422, decided cards 409. Perms mirror review→done: orchestrators and the account owner only, no self-accept for plain workers. Audits task.accepted (ids only); no webhook — the card did not move.
| Parameter | Description |
|---|---|
idRequired · path | Resource UUID. |
projectIdOptional · query | Project UUID. May be omitted only when the key resolves to a single project. |
Responses and error codes
{
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"task": {
"$ref": "#/components/schemas/Task"
}
},
"required": [
"task"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing, invalid, paused or revoked key, or human-only route.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Capability or access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Task state or ownership conflict.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Secret blocked or unprocessable state.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}Send a review task back
POST /v1/tasks/{id}/send-backRequires tasks capability. Sends a review card back to todo (default) or in_progress with the note attached as a server-titled 'Founder feedback' markdown artifact (placeholder when omitted). The verdict lands rejected and the handoff archives. Review-only; accepted cards 409. Same decider perms as accept. Audits task.rejected (ids only) plus the standard task.status_changed audit and webhook.
| Parameter | Description |
|---|---|
idRequired · path | Resource UUID. |
projectIdOptional · query | Project UUID. May be omitted only when the key resolves to a single project. |
Request body schema
{
"type": "object",
"properties": {
"note": {
"type": "string",
"maxLength": 50000
},
"to": {
"type": "string",
"enum": [
"todo",
"in_progress"
]
}
}
}Responses and error codes
{
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"task": {
"$ref": "#/components/schemas/Task"
}
},
"required": [
"task"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing, invalid, paused or revoked key, or human-only route.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Capability or access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Task state or ownership conflict.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Secret blocked or unprocessable state.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}Update a task
PATCH /v1/tasks/{id}Requires tasks capability. Own-task gates apply. The holder of a live card may hand it to another eligible profile (assigneeProfileId, optionally with status review and reviewNote in the same call); releasing to nobody, reassigning other cards, archive, and accepting reviewed work require task:assign or a human session.
| Parameter | Description |
|---|---|
idRequired · path | Resource UUID. |
projectIdOptional · query | Project UUID. May be omitted only when the key resolves to a single project. |
Request body schema
{
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1,
"maxLength": 300
},
"body": {
"type": "string",
"maxLength": 1000000
},
"status": {
"type": "string",
"enum": [
"todo",
"in_progress",
"review",
"done"
]
},
"assigneeProfileId": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"blocked": {
"type": "boolean"
},
"blockedReason": {
"type": [
"string",
"null"
],
"maxLength": 500
},
"reviewNote": {
"type": [
"string",
"null"
],
"maxLength": 1000
},
"dueAt": {
"type": [
"string",
"null"
]
},
"archived": {
"type": "boolean"
}
}
}Responses and error codes
{
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"task": {
"$ref": "#/components/schemas/Task"
}
},
"required": [
"task"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing, invalid, paused or revoked key, or human-only route.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Capability or access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"409": {
"description": "Task state or ownership conflict.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"422": {
"description": "Invalid assignment or operation.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}List task version history
GET /v1/tasks/{id}/versionsAccount-only. Returns the card's edit snapshots (overwritten title/body) and handoff snapshots (discarded review notes), newest first. Archived cards read normally.
| Parameter | Description |
|---|---|
idRequired · path | Resource UUID. |
Responses and error codes
{
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"versions": {
"type": "array",
"items": {
"$ref": "#/components/schemas/TaskVersion"
}
}
},
"required": [
"versions"
]
}
}
}
},
"401": {
"description": "Missing, invalid, paused or revoked key, or human-only route.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Capability or access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate or daily budget limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}Read one task artifact
GET /v1/tasks/{id}/artifacts/{artifactId}Requires tasks capability and full collection access on the card's board. Returns the artifact including its stored markdown content (task payloads carry list entries only — content stays behind this read).
| Parameter | Description |
|---|---|
idRequired · path | Resource UUID. |
artifactIdRequired · path | Resource UUID. |
Responses and error codes
{
"200": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"artifact": {
"$ref": "#/components/schemas/ArtifactDetail"
}
},
"required": [
"artifact"
]
}
}
}
},
"401": {
"description": "Missing, invalid, paused or revoked key, or human-only route.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Capability or access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"429": {
"description": "Rate or daily budget limit.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}Attach an output link or markdown note
POST /v1/tasks/{id}/artifactsRequires tasks capability and own-task access, or task:assign. Links ({url}) accept only HTTP(S) URLs; markdown notes ({kind: "markdown", content}) store up to 50,000 chars server-side. This does not upload files.
| Parameter | Description |
|---|---|
idRequired · path | Resource UUID. |
projectIdOptional · query | Project UUID. May be omitted only when the key resolves to a single project. |
Request body schema
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"link",
"markdown"
],
"description": "Defaults to link. Markdown notes require content and reject assertedSize/assertedHash."
},
"url": {
"type": "string",
"format": "uri",
"maxLength": 2000,
"description": "Required for links; link-only."
},
"title": {
"type": [
"string",
"null"
],
"maxLength": 140,
"description": "Markdown-only display title; null reads as untitled."
},
"content": {
"type": "string",
"maxLength": 50000,
"description": "Required non-blank markdown for kind markdown; markdown-only."
},
"note": {
"type": "string",
"maxLength": 1000
},
"assertedSize": {
"type": [
"integer",
"null"
],
"minimum": 0,
"description": "Link-only fetch proof."
},
"assertedHash": {
"type": [
"string",
"null"
],
"maxLength": 256,
"description": "Link-only fetch proof."
}
}
}Responses and error codes
{
"201": {
"description": "Successful response.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"artifact": {
"$ref": "#/components/schemas/Artifact"
}
},
"required": [
"artifact"
]
}
}
}
},
"400": {
"description": "Invalid request.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"401": {
"description": "Missing, invalid, paused or revoked key, or human-only route.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"403": {
"description": "Capability or access denied.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
},
"404": {
"description": "Resource not found or not visible.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Error"
}
}
}
}
}Response schemas
Span
{
"type": "object",
"properties": {
"text": {
"type": "string"
},
"documentName": {
"type": "string"
},
"title": {
"type": "string"
},
"documentId": {
"type": "string",
"format": "uuid"
},
"chunkId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"text",
"documentName",
"title",
"documentId",
"chunkId"
]
}Citation
{
"type": "object",
"properties": {
"documentName": {
"type": "string"
},
"title": {
"type": "string"
},
"documentId": {
"type": "string",
"format": "uuid"
},
"chunkId": {
"type": "string",
"format": "uuid"
}
},
"required": [
"documentId",
"documentName",
"chunkId",
"title"
]
}AskAnswer
{
"type": "object",
"properties": {
"spans": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Span"
}
},
"citations": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Citation"
}
},
"support": {
"type": "number",
"minimum": 0,
"maximum": 1,
"description": "Versioned evidence support; not confidence."
},
"supportVersion": {
"type": "string"
},
"abstained": {
"type": "boolean"
},
"candidateCount": {
"type": "integer"
},
"answerability": {
"type": "string",
"enum": [
"answerable",
"partial",
"unanswerable",
"unknown"
]
},
"conflict": {
"type": "boolean"
}
},
"required": [
"spans",
"citations",
"support",
"supportVersion",
"abstained",
"candidateCount",
"answerability",
"conflict"
]
}Error
{
"type": "object",
"properties": {
"error": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
},
"required": [
"code",
"message"
]
}
},
"required": [
"error"
]
}SearchHit
{
"type": "object",
"properties": {
"chunkId": {
"type": "string",
"format": "uuid"
},
"documentId": {
"type": "string",
"format": "uuid"
},
"documentName": {
"type": "string"
},
"title": {
"type": "string"
},
"snippet": {
"type": "string"
},
"rank": {
"type": "number"
},
"documentCreatedAt": {
"type": "string"
},
"ttlDays": {
"type": "integer"
}
}
}Artifact
{
"type": "object",
"description": "List entry as carried on task payloads: kind plus the link URL or markdown title, never the stored content (read one artifact to fetch it).",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"link",
"markdown"
]
},
"url": {
"type": [
"string",
"null"
],
"description": "Link target; null on markdown notes."
},
"title": {
"type": [
"string",
"null"
],
"description": "Markdown display title as stored; null on links and untitled notes."
},
"note": {
"type": [
"string",
"null"
]
},
"assertedSize": {
"type": [
"integer",
"null"
]
},
"assertedHash": {
"type": [
"string",
"null"
]
},
"createdByProfileId": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": "string"
}
}
}ArtifactDetail
{
"type": "object",
"description": "Single-artifact read: the list entry plus the stored markdown content (null on links).",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"link",
"markdown"
]
},
"url": {
"type": [
"string",
"null"
]
},
"title": {
"type": [
"string",
"null"
]
},
"content": {
"type": [
"string",
"null"
]
},
"note": {
"type": [
"string",
"null"
]
},
"assertedSize": {
"type": [
"integer",
"null"
]
},
"assertedHash": {
"type": [
"string",
"null"
]
},
"createdByProfileId": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": "string"
}
}
}Task
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"projectId": {
"type": "string",
"format": "uuid"
},
"title": {
"type": "string"
},
"body": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"todo",
"in_progress",
"review",
"done"
]
},
"blocked": {
"type": "boolean"
},
"blockedReason": {
"type": [
"string",
"null"
]
},
"reviewNote": {
"type": [
"string",
"null"
]
},
"previousReviewNote": {
"type": [
"string",
"null"
]
},
"followsUpOnId": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"followsUpOn": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"title": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"todo",
"in_progress",
"review",
"done"
]
},
"archivedAt": {
"type": [
"string",
"null"
]
}
}
},
"followups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"title": {
"type": "string"
},
"status": {
"type": "string",
"enum": [
"todo",
"in_progress",
"review",
"done"
]
},
"archivedAt": {
"type": [
"string",
"null"
]
},
"assigneeProfileId": {
"type": [
"string",
"null"
]
},
"assigneeName": {
"type": [
"string",
"null"
]
}
}
}
},
"escalationReason": {
"type": [
"string",
"null"
]
},
"escalationRaisedAt": {
"type": [
"string",
"null"
]
},
"escalationRaisedByProfileId": {
"type": [
"string",
"null"
]
},
"reviewEnteredByProfileId": {
"type": [
"string",
"null"
]
},
"reviewVerdict": {
"type": [
"string",
"null"
],
"enum": [
"accepted",
"rejected",
null
]
},
"reviewVerdictAt": {
"type": [
"string",
"null"
]
},
"lastFeedbackArtifactId": {
"type": [
"string",
"null"
],
"format": "uuid"
},
"assigneeProfileId": {
"type": [
"string",
"null"
]
},
"assigneeName": {
"type": [
"string",
"null"
]
},
"dueAt": {
"type": [
"string",
"null"
]
},
"archivedAt": {
"type": [
"string",
"null"
]
},
"createdByProfileId": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": "string"
},
"updatedAt": {
"type": "string"
},
"artifacts": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Artifact"
}
}
}
}TaskVersion
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"kind": {
"type": "string",
"enum": [
"edit",
"handoff"
]
},
"title": {
"type": "string"
},
"body": {
"type": "string"
},
"note": {
"type": [
"string",
"null"
]
},
"fields": {
"type": "array",
"items": {
"type": "string"
}
},
"actorKind": {
"type": "string",
"enum": [
"user",
"profile"
]
},
"actorProfileId": {
"type": [
"string",
"null"
]
},
"actorUserId": {
"type": [
"string",
"null"
]
},
"actorName": {
"type": [
"string",
"null"
]
},
"handoffByProfileId": {
"type": [
"string",
"null"
]
},
"handoffByName": {
"type": [
"string",
"null"
]
},
"seq": {
"type": "integer"
},
"createdAt": {
"type": "string"
}
}
}Document
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"folderId": {
"type": [
"string",
"null"
]
},
"name": {
"type": "string"
},
"mime": {
"type": "string"
},
"bytes": {
"type": "integer"
},
"status": {
"type": "string"
},
"createdAt": {
"type": "string"
},
"ttlDays": {
"type": "integer"
},
"stale": {
"type": "boolean"
}
}
}Project
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"name": {
"type": "string"
},
"createdAt": {
"type": "string"
}
}
}Note
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"status": {
"type": "string"
},
"template": {
"type": "object"
},
"projectTag": {
"type": [
"string",
"null"
]
},
"createdAt": {
"type": "string"
}
}
}