Read-only access to team documents. Documents can be pages with rich text content or structured databases.
/api/v1/documentsread:documentsRetrieve a paginated list of documents for your team.
pageintegerPage number (default: 1)limitintegerItems per page (default: 50, max: 100)teamspace_iduuidFilter by teamspaceparent_iduuidFilter by parent document (for nested docs)doc_typestringFilter by type: page, databasevisibilitystringFilter by visibility: private, team, publicinclude_archivedbooleanInclude archived documents (default: false)sort_bystringSort field (default: updated_at)sort_orderstringSort direction: asc or desc (default: desc)curl -X GET "https://gateway.thekairos.app/v1/documents?doc_type=page&limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"{
"data": [
{
"id": "doc12345-e29b-41d4-a716-446655440000",
"team_id": "123e4567-e89b-12d3-a456-426614174000",
"teamspace_id": "ts-456e7890-e12b-34d5",
"owner_id": "456e7890-e12b-34d5-a678-901234567000",
"parent_id": null,
"title": "Product Roadmap 2024",
"icon": "clipboard",
"doc_type": "page",
"visibility": "team",
"is_archived": false,
"depth": 0,
"word_count": 1250,
"cover_image": "https://...",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-10T14:30:00Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 45,
"has_more": true
}
}/api/v1/documents/:idread:documentsRetrieve a single document by ID, including its content.
include_contentbooleanInclude document content (default: true)include_childrenbooleanInclude child documents (default: false)curl -X GET "https://gateway.thekairos.app/v1/documents/doc12345-e29b-41d4-a716-446655440000?include_children=true" \
-H "Authorization: Bearer YOUR_API_KEY"{
"data": {
"id": "doc12345-e29b-41d4-a716-446655440000",
"team_id": "123e4567-e89b-12d3-a456-426614174000",
"teamspace_id": "ts-456e7890-e12b-34d5",
"owner_id": "456e7890-e12b-34d5-a678-901234567000",
"parent_id": null,
"title": "Product Roadmap 2024",
"icon": "clipboard",
"content": {
"type": "doc",
"content": [
{
"type": "heading",
"attrs": { "level": 1 },
"content": [{ "type": "text", "text": "Q1 Objectives" }]
},
{
"type": "paragraph",
"content": [{ "type": "text", "text": "Our main focus areas..." }]
}
]
},
"plain_text": "Q1 Objectives\n\nOur main focus areas...",
"doc_type": "page",
"visibility": "team",
"is_archived": false,
"is_locked": false,
"depth": 0,
"word_count": 1250,
"cover_image": "https://...",
"created_at": "2024-01-01T00:00:00Z",
"updated_at": "2024-01-10T14:30:00Z",
"last_edited_by": "456e7890-e12b-34d5-a678-901234567000",
"children": [
{
"id": "doc67890-e29b-41d4-a716-446655440001",
"title": "Q1 Sprint Planning",
"icon": "target",
"doc_type": "page",
"visibility": "team",
"is_archived": false,
"depth": 1
}
]
}
}Documents can be one of the following types:
| Type | Description |
|---|---|
page | Rich text document with BlockNote content |
database | Structured data with properties, views, and rows |
Documents have visibility settings that control access:
| Visibility | Description |
|---|---|
private | Only accessible to the owner and explicitly shared users |
team | Accessible to all team members |
public | Publicly accessible via a shared link |
Page documents use a JSON-based content format compatible with BlockNote/TipTap. The structure follows the ProseMirror document model:
The rich text content as a JSON object. Contains nested nodes like paragraphs, headings, lists, code blocks, etc.
A plain text extraction of the content for search and preview purposes. All formatting and structure is stripped.
plain_text field when you need to search or display document content without parsing the rich text structure.Documents can be nested within other documents to create a hierarchy:
parent_id - The ID of the parent document (null for root documents)depth - The nesting level (0 for root, 1 for children, etc.)sort_order - The order within siblingsUse the include_children=true parameter to fetch child documents along with the parent. Use parent_id filter to list only documents under a specific parent.