Documents API

Read-only access to team documents. Documents can be pages with rich text content or structured databases.

Read-Only Access

The Documents API currently provides read-only access. Creating, updating, and deleting documents is not available through the API.

List Documents

GET/api/v1/documentsread:documents

Retrieve a paginated list of documents for your team.

Query Parameters

pageintegerPage number (default: 1)

limitintegerItems per page (default: 50, max: 100)

teamspace_iduuidFilter by teamspace

parent_iduuidFilter by parent document (for nested docs)

doc_typestringFilter by type: page, database

visibilitystringFilter by visibility: private, team, public

include_archivedbooleanInclude archived documents (default: false)

sort_bystringSort field (default: updated_at)

sort_orderstringSort direction: asc or desc (default: desc)

Request Example

curl -X GET "https://gateway.thekairos.app/v1/documents?doc_type=page&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

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

Get Document

GET/api/v1/documents/:idread:documents

Retrieve a single document by ID, including its content.

Query Parameters

include_contentbooleanInclude document content (default: true)

include_childrenbooleanInclude child documents (default: false)

Request Example

curl -X GET "https://gateway.thekairos.app/v1/documents/doc12345-e29b-41d4-a716-446655440000?include_children=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "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
      }
    ]
  }
}

Document Types

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

Visibility Levels

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

API Access Scope

The API only returns documents that are visible to the team. Private documents require explicit permission grants to access.

Content Format

Page documents use a JSON-based content format compatible with BlockNote/TipTap. The structure follows the ProseMirror document model:

content

The rich text content as a JSON object. Contains nested nodes like paragraphs, headings, lists, code blocks, etc.

plain_text

A plain text extraction of the content for search and preview purposes. All formatting and structure is stripped.

Plain Text for Search

Use the plain_text field when you need to search or display document content without parsing the rich text structure.

Hierarchical 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 siblings

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

Team API SDKs->

API Reference/Documents

Documents API

Read-only access to team documents. Documents can be pages with rich text content or structured databases.

Read-Only Access

The Documents API currently provides read-only access. Creating, updating, and deleting documents is not available through the API.

List Documents

GET/api/v1/documentsread:documents

Retrieve a paginated list of documents for your team.

Query Parameters

pageintegerPage number (default: 1)

limitintegerItems per page (default: 50, max: 100)

teamspace_iduuidFilter by teamspace

parent_iduuidFilter by parent document (for nested docs)

doc_typestringFilter by type: page, database

visibilitystringFilter by visibility: private, team, public

include_archivedbooleanInclude archived documents (default: false)

sort_bystringSort field (default: updated_at)

sort_orderstringSort direction: asc or desc (default: desc)

Request Example

curl -X GET "https://gateway.thekairos.app/v1/documents?doc_type=page&limit=20" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

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

Get Document

GET/api/v1/documents/:idread:documents

Retrieve a single document by ID, including its content.

Query Parameters

include_contentbooleanInclude document content (default: true)

include_childrenbooleanInclude child documents (default: false)

Request Example

curl -X GET "https://gateway.thekairos.app/v1/documents/doc12345-e29b-41d4-a716-446655440000?include_children=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "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
      }
    ]
  }
}

Document Types

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

Visibility Levels

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

API Access Scope

The API only returns documents that are visible to the team. Private documents require explicit permission grants to access.

Content Format

Page documents use a JSON-based content format compatible with BlockNote/TipTap. The structure follows the ProseMirror document model:

content

The rich text content as a JSON object. Contains nested nodes like paragraphs, headings, lists, code blocks, etc.

plain_text

A plain text extraction of the content for search and preview purposes. All formatting and structure is stripped.

Plain Text for Search

Use the plain_text field when you need to search or display document content without parsing the rich text structure.

Hierarchical 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 siblings

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

Team API SDKs->