API reference

Knowledge pages

Pages, databases, search, trash and favorites.

`GET /v1/orgs/:orgId/pages`

The page tree, or the trash with archived=1.

Auth: user access token or platform agent key · Scope: knowledge:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Query parameter	Type	Required	Notes
`archived`	`"0" \| "1"`	No

Response 200

{
  pages: {
    pageId: string
    parentId: string
    kind: "database" | "doc"
    title: string
    icon?: string
    position: number
    archived: boolean
    archivedAt?: number
    contentVersion: number
    createdAt: number
    updatedAt: number
    createdBy: string
    updatedBy?: string
  }[]
  truncated: boolean
}

Errors

Status	Message
`404`	Page not found

`POST /v1/orgs/:orgId/pages`

Creates a page or database, at the top level or under a parent.

Auth: user access token or platform agent key · Scope: knowledge:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Request body

Field	Type	Required	Notes
`parentId`	`string \| "root"`	No	matches `^[A-Za-z0-9_-]{1,64}$`
`title`	`string`	No	up to 200 characters
`icon`	`string`	No	up to 16 characters; trimmed
`kind`	`"doc" \| "database"`	No
`properties`	`object`	No	keys match `^[A-Za-z0-9_-]{1,32}$`; values: string (up to 4,000 characters), number, boolean, string[] (up to 50 items, each up to 32 characters) or null

Response 201

{
  page: {
    pageId: string
    parentId: string
    kind: "database" | "doc"
    title: string
    icon?: string
    position: number
    archived: boolean
    archivedAt?: number
    contentVersion: number
    createdAt: number
    updatedAt: number
    createdBy: string
    updatedBy?: string
    schema?: {
      id: string
      name: string
      type: "number" | "text" | "url" | "date" | "select" | "multi_select" | "checkbox"
      options?: {
        id: string
        name: string
        color?: "gray" | "brown" | "orange" | "yellow" | "green" | "blue" | "purple" | "pink" | "red"
      }[]
    }[]
    properties?: {
      [key: string]: boolean | string | number | string[]
    }
  }
}

Errors

Status	Message
`400`	Parent page not found.
`400`	The parent page is in the trash.
`400`	Unknown property.
`404`	Page not found

`GET /v1/orgs/:orgId/pages/search`

Searches page titles and text.

Auth: user access token or platform agent key · Scope: knowledge:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Query parameter	Type	Required	Default	Notes
`q`	`string`	No	`""`	up to 200 characters

Response 200

{
  results: {
    updatedAt: number
    kind: "database" | "doc"
    title: string
    pageId: string
    parentId: string
    icon?: string
    snippet?: string
  }[]
}

Errors

Status	Message
`404`	Page not found

`GET /v1/orgs/:orgId/pages/:pageId`

A page with its content. Databases include their rows; rows include their database's schema.

Auth: user access token or platform agent key · Scope: knowledge:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:pageId`	Page id (`doc_…`).

Response 200

{
  page: {
    pageId: string
    parentId: string
    kind: "database" | "doc"
    title: string
    icon?: string
    position: number
    archived: boolean
    archivedAt?: number
    contentVersion: number
    createdAt: number
    updatedAt: number
    createdBy: string
    updatedBy?: string
    schema?: {
      id: string
      name: string
      type: "number" | "text" | "url" | "date" | "select" | "multi_select" | "checkbox"
      options?: {
        id: string
        name: string
        color?: "gray" | "brown" | "orange" | "yellow" | "green" | "blue" | "purple" | "pink" | "red"
      }[]
    }[]
    properties?: {
      [key: string]: boolean | string | number | string[]
    }
  }
  content: null | {
    version: number
    blocks: null | unknown[]
    markdown: string
  }
  rows?: {
    pageId: string
    parentId: string
    kind: "database" | "doc"
    title: string
    icon?: string
    position: number
    archived: boolean
    archivedAt?: number
    contentVersion: number
    createdAt: number
    updatedAt: number
    createdBy: string
    updatedBy?: string
    schema?: {
      id: string
      name: string
      type: "number" | "text" | "url" | "date" | "select" | "multi_select" | "checkbox"
      options?: {
        id: string
        name: string
        color?: "gray" | "brown" | "orange" | "yellow" | "green" | "blue" | "purple" | "pink" | "red"
      }[]
    }[]
    properties?: {
      [key: string]: boolean | string | number | string[]
    }
  }[]
  database?: {
    pageId: string
    title: string
    icon?: string
    schema: {
      id: string
      name: string
      type: "number" | "text" | "url" | "date" | "select" | "multi_select" | "checkbox"
      options?: {
        id: string
        name: string
        color?: "gray" | "brown" | "orange" | "yellow" | "green" | "blue" | "purple" | "pink" | "red"
      }[]
    }[]
  }
}

Errors

Status	Message
`404`	Page not found

`PATCH /v1/orgs/:orgId/pages/:pageId`

Renames, moves, trashes or restores a page, or edits a database's properties or a row's values.

Auth: user access token or platform agent key · Scope: knowledge:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:pageId`	Page id (`doc_…`).

Request body

Field	Type	Required	Notes
`title`	`string`	No	up to 200 characters
`icon`	`string`	No	up to 16 characters; trimmed; can be `null`
`parentId`	`string \| "root"`	No	matches `^[A-Za-z0-9_-]{1,64}$`
`position`	`integer`	No	≥ 0
`archived`	`boolean`	No
`schema`	`object[]`	No	up to 50 items
`schema[].id`	`string`	No	matches `^[A-Za-z0-9_-]{1,32}$`
`schema[].name`	`string`	Yes	1–100 characters; trimmed
`schema[].type`	`"text" \| "number" \| "select" \| "multi_select" \| "date" \| "checkbox" \| "url"`	Yes
`schema[].options`	`object[]`	No	up to 100 items
`schema[].options[].id`	`string`	No	matches `^[A-Za-z0-9_-]{1,32}$`
`schema[].options[].name`	`string`	Yes	1–100 characters; trimmed
`schema[].options[].color`	`"gray" \| "brown" \| "orange" \| "yellow" \| "green" \| "blue" \| "purple" \| "pink" \| "red"`	No
`properties`	`object`	No	keys match `^[A-Za-z0-9_-]{1,32}$`; values: string (up to 4,000 characters), number, boolean, string[] (up to 50 items, each up to 32 characters) or null

Response 200

{
  page: {
    pageId: string
    parentId: string
    kind: "database" | "doc"
    title: string
    icon?: string
    position: number
    archived: boolean
    archivedAt?: number
    contentVersion: number
    createdAt: number
    updatedAt: number
    createdBy: string
    updatedBy?: string
    schema?: {
      id: string
      name: string
      type: "number" | "text" | "url" | "date" | "select" | "multi_select" | "checkbox"
      options?: {
        id: string
        name: string
        color?: "gray" | "brown" | "orange" | "yellow" | "green" | "blue" | "purple" | "pink" | "red"
      }[]
    }[]
    properties?: {
      [key: string]: boolean | string | number | string[]
    }
  }
}

Errors

Status	Message
`400`	A page can't be moved into itself.
`400`	Target page not found.
`400`	The target page is in the trash.
`400`	A page can't be moved into one of its subpages.
`400`	Pages are nested too deeply.
`400`	Only databases have properties.
`400`	Only database rows have property values.
`400`	Unknown property.
`404`	Page not found
`409`	The page changed. Try again.

`PUT /v1/orgs/:orgId/pages/:pageId/content`

Saves page content. baseVersion is the version you started from; if the page has changed since, the save fails with 409.

Auth: user access token or platform agent key · Scope: knowledge:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:pageId`	Page id (`doc_…`).

Request body (up to 1,065,536 bytes)

Field	Type	Required	Notes
`blocks`	`any JSON[]`	Yes	can be `null`
`markdown`	`string`	Yes
`baseVersion`	`integer`	Yes	≥ 0

Response 200

{
  version: number
  updatedAt: number
}

Errors

Status	Message
`404`	Page not found
`409`	This page is in the trash. Restore it to edit.
`409`	This page changed since you opened it.
`413`	Pages can be up to 1 MB.

`DELETE /v1/orgs/:orgId/pages/:pageId`

Moves a page to the trash.

Auth: user access token or platform agent key · Scope: knowledge:write

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:pageId`	Page id (`doc_…`).

Response 200

{
  page: {
    pageId: string
    parentId: string
    kind: "database" | "doc"
    title: string
    icon?: string
    position: number
    archived: boolean
    archivedAt?: number
    contentVersion: number
    createdAt: number
    updatedAt: number
    createdBy: string
    updatedBy?: string
    schema?: {
      id: string
      name: string
      type: "number" | "text" | "url" | "date" | "select" | "multi_select" | "checkbox"
      options?: {
        id: string
        name: string
        color?: "gray" | "brown" | "orange" | "yellow" | "green" | "blue" | "purple" | "pink" | "red"
      }[]
    }[]
    properties?: {
      [key: string]: boolean | string | number | string[]
    }
  }
}

Errors

Status	Message
`400`	A page can't be moved into itself.
`400`	Target page not found.
`400`	The target page is in the trash.
`400`	A page can't be moved into one of its subpages.
`400`	Pages are nested too deeply.
`400`	Only databases have properties.
`400`	Only database rows have property values.
`400`	Unknown property.
`404`	Page not found
`409`	The page changed. Try again.

`GET /v1/orgs/:orgId/favorites`

The caller's favorite pages, oldest first.

Auth: user access token or platform agent key · Scope: knowledge:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).

Response 200

{
  favorites: {
    pageId: string
    createdAt: number
  }[]
}

Errors

Status	Message
`404`	Page not found

`PUT /v1/orgs/:orgId/favorites/:pageId`

Adds a page to the caller's favorites. Adding it again keeps its place.

Auth: user access token or platform agent key · Scope: knowledge:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:pageId`	Page id (`doc_…`).

Response 200

{
  favorite: {
    pageId: string
    createdAt: number
  }
}

Errors

Status	Message
`400`	This page is in the trash.
`400`	You can have up to 200 favorites.
`404`	Page not found

`DELETE /v1/orgs/:orgId/favorites/:pageId`

Removes a page from the caller's favorites.

Auth: user access token or platform agent key · Scope: knowledge:read

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:pageId`	Page id (`doc_…`).

Response 200

{
  ok: true
}

Errors

Status	Message
`404`	Page not found

Knowledge pages

On this page