Takibi

Search the docs

↑↓ Navigate↵ Open guideTakibi

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.

Download the OpenAPI contract · Use the CLI instead

Ask a question

GET /v1/ask

Requires ask capability. Returns verbatim passages and citations; may abstain. Jev failures can fall back to deterministic extraction.

Parameters for Ask a question
ParameterDescription
q
Required · query		Question to answer from source evidence.
projectId
Optional · query		Project UUID. May be omitted only when the key resolves to a single project.
folderId
Optional · query		Narrow retrieval to a granted folder.
k
Optional · 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/ask

Same 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"
        }
      }
    }
  }
}

List accessible documents

GET /v1/documents

Profile keys see only indexed documents within their grants.

Parameters for List accessible documents
ParameterDescription
projectId
Optional · query		Project UUID. May be omitted only when the key resolves to a single project.
folderId
Optional · 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/documents

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

Parameters for Get document metadata
ParameterDescription
id
Required · path		Resource UUID.
projectId
Optional · 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}/text

Returns the converted text within the Profile document grants. Large responses may be truncated. With offset, returns that piece of the text, plus offset (where the piece really starts), totalChars and name.

Parameters for Read converted text
ParameterDescription
id
Required · path		Resource UUID.
projectId
Optional · query		Project UUID. May be omitted only when the key resolves to a single project.
offset
Optional · query		Character position to read from, for reading a long document in pieces.
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/projects

Any 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/notes

Requires notes:append capability. Appends a lesson to the key's own profile. A note is a reusable lesson or tool quirk, not a status update (status goes on the task): problem is a short plain-text title (max 140 chars) and at least one of tried, worked, failed, next_time must be non-empty. 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",
          "minLength": 1,
          "maxLength": 140,
          "pattern": "\\S",
          "description": "Short plain-text title of the lesson (Unicode code points)."
        },
        "tried": {
          "type": "string",
          "maxLength": 5000,
          "description": "What was tried (Markdown)."
        },
        "worked": {
          "type": "string",
          "maxLength": 5000,
          "description": "What worked (Markdown)."
        },
        "failed": {
          "type": "string",
          "maxLength": 5000,
          "description": "What failed (Markdown)."
        },
        "next_time": {
          "type": "string",
          "maxLength": 5000,
          "description": "What to do next time (Markdown)."
        }
      },
      "required": [
        "problem"
      ],
      "anyOf": [
        {
          "required": [
            "tried"
          ],
          "properties": {
            "tried": {
              "type": "string",
              "minLength": 1,
              "pattern": "\\S"
            }
          }
        },
        {
          "required": [
            "worked"
          ],
          "properties": {
            "worked": {
              "type": "string",
              "minLength": 1,
              "pattern": "\\S"
            }
          }
        },
        {
          "required": [
            "failed"
          ],
          "properties": {
            "failed": {
              "type": "string",
              "minLength": 1,
              "pattern": "\\S"
            }
          }
        },
        {
          "required": [
            "next_time"
          ],
          "properties": {
            "next_time": {
              "type": "string",
              "minLength": 1,
              "pattern": "\\S"
            }
          }
        }
      ],
      "description": "At least one of tried, worked, failed, next_time must carry content: a character other than whitespace, control, or format characters (Unicode Z, Cc, Cf). The patterns approximate this with \\S; the server is authoritative. Lengths count Unicode code points; the whole template caps at 20000."
    }
  },
  "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: blank or over-140-char problem, a body field over 5000 chars, no body field with content (tried, worked, failed, next_time), a template over 20000 chars in total, an unpaired surrogate in any field, or a malformed body. The message names the field. A secret in the note text answers 422 before the lesson-shape checks.",
    "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/tasks

Requires tasks capability and a whole-collection grant on the project. Folder-only or tag-only keys get 403 on every task route.

Parameters for List the project task board
ParameterDescription
projectId
Optional · query		Project UUID. When omitted, sealed Chat manager keys and user sessions read across the organization. Other keys must resolve to a single project.
status
Optional · query		Filter by task status before applying the limit.
blocked
Optional · query		Filter blocked or unblocked tasks before applying the limit. Independent of status.
includeArchived
Optional · query		Set to 1 to include archived tasks.
order
Optional · query		Sort by creation time: asc (default, oldest first) or desc (newest first, for polling).
createdAfter
Optional · query		ISO timestamp cursor: matches that card again plus anything newer. Inclusive on purpose; pollers dedupe by id. The page still applies.
limit
Optional · 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": {
            "truncated": {
              "type": "boolean",
              "description": "True when more matching tasks exist beyond this page."
            },
            "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/tasks

Requires 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/assignees

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

Parameters for List eligible task assignees
ParameterDescription
projectId
Optional · 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}/claim

Requires a Profile key with tasks capability. Claims an unassigned todo task for that Profile. Repeating your own successful claim is safe.

Parameters for Claim an available task
ParameterDescription
id
Required · path		Resource UUID.
projectId
Optional · 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-ups

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

Parameters for Spin a follow-up off a task
ParameterDescription
id
Required · 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}/escalate

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

Parameters for Escalate a task to the Founder
ParameterDescription
id
Required · path		Resource UUID.
projectId
Optional · 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}/escalation

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

Parameters for Clear a task escalation
ParameterDescription
id
Required · path		Resource UUID.
projectId
Optional · 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}/accept

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

Parameters for Accept a task in review
ParameterDescription
id
Required · path		Resource UUID.
projectId
Optional · 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-back

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

Parameters for Send a review task back
ParameterDescription
id
Required · path		Resource UUID.
projectId
Optional · 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. Send expectedStatus to make the whole write conditional: a task no longer in that status gets no write and the call returns 409 STATUS_CONFLICT with error.currentStatus (e.g. expectedStatus in_progress when moving finished work to review). The guard compares status only, and the accept and send-back routes take no expectedStatus (they already refuse cards outside review). To guard against any concurrent edit, send expectedVersion with the task's version from your read: if the card changed since, no write happens and the call returns 409 VERSION_CONFLICT with the current card in task. expectedAssigneeId (null = expect unassigned) guards reassignment the same way and returns 409 ASSIGNEE_CONFLICT. All guards are optional and combine; each is compared under the row lock.

Parameters for Update a task
ParameterDescription
id
Required · path		Resource UUID.
projectId
Optional · 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"
    },
    "wakeAt": {
      "type": [
        "string",
        "null"
      ],
      "format": "date-time",
      "description": "Wake me later: an ISO 8601 instant with an explicit offset or Z (2026-11-16T09:00+01:00); a bare date, a zone-less time, or an impossible calendar date (2027-02-30) is 400. Must be in the future and at most a year out. Setting it requires wakeReason, blocks the card with that reason (blockedReason), never escalates, and starts a new wakeEpoch. When it passes, Takibi sends the task.wake_due webhook once per epoch; the card stays blocked and held. null clears the wait and keeps the block. Unblock, reassign/release, archive and done clear the wait too; title, body and notes do not. Same gate as blocked."
    },
    "wakeReason": {
      "type": "string",
      "maxLength": 500,
      "description": "What the card waits for. Required with a wakeAt instant, refused without one. Secret-scanned like blockedReason."
    },
    "wakeTimeZone": {
      "type": "string",
      "maxLength": 64,
      "description": "Optional IANA zone (Europe/Copenhagen) the wait is shown in. Without it the offset inside wakeAt is kept (+01:00, or UTC for Z). Unknown zones are 400. Rides with a wakeAt instant only."
    },
    "expectedStatus": {
      "type": "string",
      "enum": [
        "todo",
        "in_progress",
        "review",
        "done"
      ],
      "description": "Optimistic-concurrency guard for the whole PATCH: the task must be in this status at write time (compared under the row lock), or no task write happens (no field, edit snapshot, audit, or webhook) and the call 409s STATUS_CONFLICT. Compares status only: a concurrent edit that leaves the column unchanged (title, note, assignee) does not trip it; use expectedVersion for that. Exact value, no trimming. Omit for last-writer-wins."
    },
    "expectedVersion": {
      "type": "string",
      "pattern": "^(0|[1-9][0-9]{0,18})$",
      "description": "Optimistic-concurrency guard for the whole PATCH: the task's version from the read you decided on, sent back exactly as read: a canonical decimal up to 9223372036854775807 (a padded, reformatted or larger value is 400). Compare it as a string, never as a float. Every write to the card moves the version: field edits on any route, claims, escalations, and attaching, editing or removing an artifact or claim note. A mismatch means the card changed since your read: no task write happens and the call 409s VERSION_CONFLICT with the current card in task. A PATCH that changes nothing writes nothing and keeps the version. Opaque: compare it, never compute with it. Omit for last-writer-wins."
    },
    "expectedAssigneeId": {
      "type": [
        "string",
        "null"
      ],
      "format": "uuid",
      "description": "Reassignment guard for the whole PATCH: the holder the task must have at write time, null meaning it must be unassigned. A mismatch writes nothing and 409s ASSIGNEE_CONFLICT with error.currentAssigneeId and the current card in task."
    }
  }
}
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; no task write happened. STATUS_CONFLICT: the task is not in expectedStatus. VERSION_CONFLICT: the task changed since expectedVersion (the current card is in task). ASSIGNEE_CONFLICT: the holder is not expectedAssigneeId (the current card is in task).",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/StatusConflictError"
        }
      }
    }
  },
  "422": {
    "description": "Invalid assignment or operation.",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/Error"
        }
      }
    }
  }
}

List task version history

GET /v1/tasks/{id}/versions

Account-only. Returns the card's edit snapshots (overwritten title/body) and handoff snapshots (discarded review notes), newest first. Archived cards read normally.

Parameters for List task version history
ParameterDescription
id
Required · 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).

Parameters for Read one task artifact
ParameterDescription
id
Required · path		Resource UUID.
artifactId
Required · 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}/artifacts

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

Parameters for Attach an output link or markdown note
ParameterDescription
id
Required · path		Resource UUID.
projectId
Optional · 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"
  ]
}
StatusConflictError
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "code": {
          "type": "string",
          "description": "STATUS_CONFLICT for an expectedStatus miss, VERSION_CONFLICT for an expectedVersion miss, ASSIGNEE_CONFLICT for an expectedAssigneeId miss; other task-state conflicts use CONFLICT or ALREADY_ACCEPTED."
        },
        "message": {
          "type": "string"
        },
        "expectedStatus": {
          "type": "string",
          "enum": [
            "todo",
            "in_progress",
            "review",
            "done"
          ],
          "description": "STATUS_CONFLICT only: the status the request expected."
        },
        "currentStatus": {
          "type": "string",
          "enum": [
            "todo",
            "in_progress",
            "review",
            "done"
          ],
          "description": "STATUS_CONFLICT only: the status the task is actually in."
        },
        "expectedVersion": {
          "type": "string",
          "description": "VERSION_CONFLICT only: the version the request expected."
        },
        "currentVersion": {
          "type": "string",
          "description": "VERSION_CONFLICT only: the task's version now."
        },
        "expectedAssigneeId": {
          "type": [
            "string",
            "null"
          ],
          "description": "ASSIGNEE_CONFLICT only: the holder the request expected (null = unassigned)."
        },
        "currentAssigneeId": {
          "type": [
            "string",
            "null"
          ],
          "description": "ASSIGNEE_CONFLICT only: the task's holder now (null = unassigned)."
        }
      },
      "required": [
        "code",
        "message"
      ]
    },
    "task": {
      "$ref": "#/components/schemas/Task",
      "description": "VERSION_CONFLICT and ASSIGNEE_CONFLICT: the current card, so the caller can re-decide without another read."
    }
  },
  "required": [
    "error"
  ]
}
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"
      ]
    },
    "reviewHandedInByProfileId": {
      "type": [
        "string",
        "null"
      ],
      "description": "Profile that handed the work in when it last entered review (self-review guard: it cannot accept or send the card back)."
    },
    "reviewHandedInByUserId": {
      "type": [
        "string",
        "null"
      ],
      "description": "Account that handed the work in, for account sessions only; null for profile keys."
    },
    "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"
      ]
    },
    "wakeAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "Wake me later: the wait's instant (UTC), or null. Cleared by unblock, reassign, archive, done, or wakeAt:null."
    },
    "wakeReason": {
      "type": [
        "string",
        "null"
      ]
    },
    "wakeTimeZone": {
      "type": [
        "string",
        "null"
      ],
      "description": "The zone the wait was set in: an IANA name, or the submitted offset (+01:00, UTC). Display only."
    },
    "wakeEpoch": {
      "type": "integer",
      "description": "Bumps on every new wait. task.wake_due carries it: resume only if the card's epoch still matches."
    },
    "wakeFired": {
      "type": "boolean",
      "description": "task.wake_due already went out for this wait (\"Wake due\")."
    },
    "archivedAt": {
      "type": [
        "string",
        "null"
      ]
    },
    "createdByProfileId": {
      "type": [
        "string",
        "null"
      ]
    },
    "createdAt": {
      "type": "string"
    },
    "updatedAt": {
      "type": "string"
    },
    "version": {
      "type": "string",
      "description": "Opaque concurrency token. Moves on every write to the card, artifacts and claim notes included (a PATCH that changes nothing keeps it); send it back as expectedVersion on PATCH to write only if nothing changed since this read."
    },
    "holderActiveAt": {
      "type": [
        "string",
        "null"
      ],
      "description": "When the current assignee last did work on this card (claim, status, note, artifact, block, escalation; owner edits and acks never count). Null when unassigned or quiet for the last ~40 minutes."
    },
    "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"
    }
  }
}