API reference
The retrieval and task endpoints used by the Takibi CLI. 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 agent retrieval and task 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": "Rate or daily budget limit.",
"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": "Rate or daily budget limit.",
"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": "Rate or daily budget limit.",
"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"
}
}
}
}
}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 the project task board
GET /v1/tasksRequires tasks capability. Any grant touching the project provides membership; folder grants do not filter task cards.
| 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. |
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"
}
}
}
}
}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"
}
}
}
}
}Update a task
PATCH /v1/tasks/{id}Requires tasks capability. Own-task gates apply. Assignment, 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
},
"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"
}
}
}
}
}Attach an output link
POST /v1/tasks/{id}/artifactsRequires tasks capability and own-task access, or task:assign. Only HTTP(S) links are accepted; 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": {
"url": {
"type": "string",
"format": "uri",
"maxLength": 2000
},
"note": {
"type": "string",
"maxLength": 1000
},
"assertedSize": {
"type": [
"integer",
"null"
],
"minimum": 0
},
"assertedHash": {
"type": [
"string",
"null"
],
"maxLength": 256
}
},
"required": [
"url"
]
}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",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"url": {
"type": "string"
},
"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"
]
},
"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"
}
}
}
}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"
}
}
}