API reference

Notes pages

Pages, databases, search, trash and favorites.

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

A one-time ticket for this tab's socket (2 minutes): the org's change events, and co-editing of the page it joins. socket is null where the stage has none.

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

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

Query parameter	Type	Required	Notes
`tab`	`string`	Yes	matches `^[\w-]{8,64}$`
`device`	`string`	No	up to 60 characters

Response 200

{
  socket: null
}
| {
  socket: {
    url: string
    ticket: string
  }
}

Errors

Status	Message
`404`	Page not found

`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
    fullWidth?: boolean
    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
    fullWidth?: boolean
    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" | "checkbox" | "multi_select" | "relation"
      options?: {
        id: string
        name: string
        color?: "gray" | "brown" | "orange" | "yellow" | "green" | "blue" | "purple" | "pink" | "red"
      }[]
      databaseId?: string
    }[]
    views?: {
      name: string
      layout: "calendar" | "table" | "board"
      filters: {
        property: string
        op: "before" | "after" | "contains" | "not_contains" | "is" | "is_not" | "gt" | "lt" | "is_empty" | "is_not_empty"
        value?: boolean | string | number | string[]
      }[]
      id: string
      sort?: null | {
        by: string
        desc: boolean
      }
      groupBy?: string
      dateProperty?: string
      hidden?: string[]
      widths?: {
        [key: string]: number
      }
    }[]
    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
    icon?: string
    parentId: string
    pageId: 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: a Notes page (`doc_…`), or a Feed page (`pgx_…`) under `/v1/messaging/social`; under `marketing` a landing page (`mkp_…`).

Response 200

{
  page: {
    pageId: string
    parentId: string
    kind: "database" | "doc"
    title: string
    icon?: string
    fullWidth?: boolean
    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" | "checkbox" | "multi_select" | "relation"
      options?: {
        id: string
        name: string
        color?: "gray" | "brown" | "orange" | "yellow" | "green" | "blue" | "purple" | "pink" | "red"
      }[]
      databaseId?: string
    }[]
    views?: {
      name: string
      layout: "calendar" | "table" | "board"
      filters: {
        property: string
        op: "before" | "after" | "contains" | "not_contains" | "is" | "is_not" | "gt" | "lt" | "is_empty" | "is_not_empty"
        value?: boolean | string | number | string[]
      }[]
      id: string
      sort?: null | {
        by: string
        desc: boolean
      }
      groupBy?: string
      dateProperty?: string
      hidden?: string[]
      widths?: {
        [key: string]: number
      }
    }[]
    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
    fullWidth?: boolean
    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" | "checkbox" | "multi_select" | "relation"
      options?: {
        id: string
        name: string
        color?: "gray" | "brown" | "orange" | "yellow" | "green" | "blue" | "purple" | "pink" | "red"
      }[]
      databaseId?: string
    }[]
    views?: {
      name: string
      layout: "calendar" | "table" | "board"
      filters: {
        property: string
        op: "before" | "after" | "contains" | "not_contains" | "is" | "is_not" | "gt" | "lt" | "is_empty" | "is_not_empty"
        value?: boolean | string | number | object
      }[]
      id: string
      sort?: null | {
        by: string
        desc: boolean
      }
      groupBy?: string
      dateProperty?: string
      hidden?: string[]
      widths?: {
        [key: string]: number
      }
    }[]
    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" | "checkbox" | "multi_select" | "relation"
      options?: {
        id: string
        name: string
        color?: "gray" | "brown" | "orange" | "yellow" | "green" | "blue" | "purple" | "pink" | "red"
      }[]
      databaseId?: string
    }[]
  }
}

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: a Notes page (`doc_…`), or a Feed page (`pgx_…`) under `/v1/messaging/social`; under `marketing` a landing page (`mkp_…`).

Request body

Field	Type	Required	Default	Notes
`title`	`string`	No		up to 200 characters
`icon`	`string`	No		up to 16 characters; trimmed; can be `null`
`fullWidth`	`boolean`	No
`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" \| "relation"`	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
`schema[].databaseId`	`string`	No		matches `^[A-Za-z0-9_-]{1,64}$`
`views`	`object[]`	No		up to 20 items
`views[].id`	`string`	No		matches `^[A-Za-z0-9_-]{1,32}$`
`views[].name`	`string`	Yes		1–100 characters; trimmed
`views[].layout`	`"table" \| "board" \| "calendar"`	Yes
`views[].filters`	`object[]`	No	`[]`	up to 20 items
`views[].filters[].property`	`string`	Yes		matches `^[A-Za-z0-9_-]{1,32}$`
`views[].filters[].op`	`"contains" \| "not_contains" \| "is" \| "is_not" \| "gt" \| "lt" \| "before" \| "after" \| "is_empty" \| "is_not_empty"`	Yes
`views[].filters[].value`	`string \| number \| boolean \| string[]`	No		up to 2,000 characters; up to 50 items; each up to 64 characters
`views[].sort`	`object`	No		can be `null`
`views[].sort.by`	`string`	Yes		matches `^[A-Za-z0-9_-]{1,32}$`
`views[].sort.desc`	`boolean`	Yes
`views[].groupBy`	`string`	No		matches `^[A-Za-z0-9_-]{1,32}$`
`views[].dateProperty`	`string`	No		matches `^[A-Za-z0-9_-]{1,32}$`
`views[].hidden`	`string[]`	No		up to 50 items; each matches `^[A-Za-z0-9_-]{1,32}$`
`views[].widths`	`object`	No		keys match `^[A-Za-z0-9_-]{1,32}$`; values: integer (80–1000)
`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
    fullWidth?: boolean
    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" | "checkbox" | "multi_select" | "relation"
      options?: {
        id: string
        name: string
        color?: "gray" | "brown" | "orange" | "yellow" | "green" | "blue" | "purple" | "pink" | "red"
      }[]
      databaseId?: string
    }[]
    views?: {
      name: string
      layout: "calendar" | "table" | "board"
      filters: {
        property: string
        op: "before" | "after" | "contains" | "not_contains" | "is" | "is_not" | "gt" | "lt" | "is_empty" | "is_not_empty"
        value?: boolean | string | number | string[]
      }[]
      id: string
      sort?: null | {
        by: string
        desc: boolean
      }
      groupBy?: string
      dateProperty?: string
      hidden?: string[]
      widths?: {
        [key: string]: number
      }
    }[]
    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 databases have views.
`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: a Notes page (`doc_…`), or a Feed page (`pgx_…`) under `/v1/messaging/social`; under `marketing` a landing page (`mkp_…`).

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
`collab`	`boolean`	No
`epoch`	`string`	No	1–64 characters

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 was changed elsewhere and reloaded.
`409`	This page changed since you opened it.
`413`	Pages can be up to 1 MB.

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

Co-editing: the page's shared document (base64 Yjs state, epoch: null before anyone opened it this way), and a one-time ticket for the socket (socket is null where co-editing isn't set up).

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:pageId`	Page id: a Notes page (`doc_…`), or a Feed page (`pgx_…`) under `/v1/messaging/social`; under `marketing` a landing page (`mkp_…`).

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

Response 200

{
  contentVersion: number
  canWrite: boolean
  socket: null | {
    url: string
    ticket: string
  } | {
    url: string
    ticket: null
  }
  epoch: null | string
  seq: number
  state: null | string
  baseVersion: number
}

Errors

Status	Message
`404`	Page not found

`POST /v1/orgs/:orgId/pages/:pageId/collab/seed`

The first editor's document, made from the stored content. 409 if someone else's came first.

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:pageId`	Page id: a Notes page (`doc_…`), or a Feed page (`pgx_…`) under `/v1/messaging/social`; under `marketing` a landing page (`mkp_…`).

Request body (up to 2,936,012.8 bytes)

Field	Type	Required	Notes
`update`	`string`	Yes	at least 1 character
`baseVersion`	`integer`	Yes	≥ 0

Response 201

{
  epoch: string
  seq: number
}

Errors

Status	Message
`404`	Page not found
`409`	This page is in the trash. Restore it to edit.
`413`	Too large.

`POST /v1/orgs/:orgId/pages/:pageId/collab/updates`

An update too large for the socket (a big paste); relayed like socket updates.

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:pageId`	Page id: a Notes page (`doc_…`), or a Feed page (`pgx_…`) under `/v1/messaging/social`; under `marketing` a landing page (`mkp_…`).

Request body (up to 2,936,012.8 bytes)

Field	Type	Required	Notes
`epoch`	`string`	Yes	1–64 characters
`update`	`string`	Yes	at least 1 character

Response 200

{
  seq: number
}

Errors

Status	Message
`404`	Page not found
`409`	This page is in the trash. Restore it to edit.
`413`	Too large.

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

Comment threads on the page (kept apart from the shared document; they survive a reset).

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:pageId`	Page id: a Notes page (`doc_…`), or a Feed page (`pgx_…`) under `/v1/messaging/social`; under `marketing` a landing page (`mkp_…`).

Response 200

{
  threads: {
    id: string
    createdAt: number
    updatedAt: number
    comments: {
      id: string
      userId: string
      createdAt: number
      updatedAt: number
      body?: unknown
      deletedAt?: number
      reactions: {
        emoji: string
        createdAt: number
        userIds: object
      }[]
      metadata?: unknown
    }[]
    resolved: boolean
    resolvedUpdatedAt?: number
    resolvedBy?: string
    anchor?: {
      blockId?: string
      quote?: string
    }
    metadata?: unknown
  }[]
}

Errors

Status	Message
`404`	Page not found

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

A new thread with its first comment (anchor: the block and text it is about).

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:pageId`	Page id: a Notes page (`doc_…`), or a Feed page (`pgx_…`) under `/v1/messaging/social`; under `marketing` a landing page (`mkp_…`).

Request body (up to 64 KB)

Field	Type	Required	Notes
`body`	`any JSON[]`	Yes	at least 1 item
`metadata`	`any JSON`	No
`anchor`	`object`	No
`anchor.blockId`	`string`	No	up to 64 characters
`anchor.quote`	`string`	No	up to 2,000 characters

Response 201

{
  thread: null | {
    id: string
    createdAt: number
    updatedAt: number
    comments: {
      id: string
      userId: string
      createdAt: number
      updatedAt: number
      body?: unknown
      deletedAt?: number
      reactions: {
        emoji: string
        createdAt: number
        userIds: string[]
      }[]
      metadata?: unknown
    }[]
    resolved: boolean
    resolvedUpdatedAt?: number
    resolvedBy?: string
    anchor?: {
      blockId?: string
      quote?: string
    }
    metadata?: unknown
  }
}

Errors

Status	Message
`400`	That isn't an emoji.
`403`	You can read comments here but not add or change them.
`403`	Only its author can change a comment.
`404`	Page not found
`404`	Thread not found.
`404`	Comment not found.
`409`	This page is in the trash. Restore it to comment.
`409`	This page has too many comment threads.
`409`	That thread already exists.
`409`	This thread has too many replies.
`409`	That comment was deleted.
`409`	That comment was already deleted.
`409`	Too many reactions.
`413`	Comments can be up to 16 KB.

`POST /v1/orgs/:orgId/pages/:pageId/threads/:threadId`

Replies, edits, deletions, resolving and reactions. thread is null once it's gone.

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:pageId`	Page id: a Notes page (`doc_…`), or a Feed page (`pgx_…`) under `/v1/messaging/social`; under `marketing` a landing page (`mkp_…`).
`:threadId`	Conversation id (`thr_…`), or in Mirage a thread id (`mth_…`).

Request body (up to 64 KB)

Field	Type	Required	Notes
`op`	`"comment" \| "edit" \| "delete-comment" \| "delete-thread" \| "resolve" \| "unresolve" \| "react" \| "unreact"`	Yes
`commentId`	`string`	No	1–64 characters
`body`	`any JSON[]`	No	at least 1 item
`metadata`	`any JSON`	No
`soft`	`boolean`	No
`emoji`	`string`	No	1–16 characters

Response 200

{
  thread: null | {
    id: string
    createdAt: number
    updatedAt: number
    comments: {
      id: string
      userId: string
      createdAt: number
      updatedAt: number
      body?: unknown
      deletedAt?: number
      reactions: {
        emoji: string
        createdAt: number
        userIds: string[]
      }[]
      metadata?: unknown
    }[]
    resolved: boolean
    resolvedUpdatedAt?: number
    resolvedBy?: string
    anchor?: {
      blockId?: string
      quote?: string
    }
    metadata?: unknown
  }
}

Errors

Status	Message
`400`	Which comment? Send `commentId`.
`400`	A comment needs some text.
`400`	Send the `emoji`.
`400`	That isn't an emoji.
`403`	You can read comments here but not add or change them.
`403`	Only its author can change a comment.
`404`	Page not found
`404`	Thread not found.
`404`	Comment not found.
`409`	This page is in the trash. Restore it to comment.
`409`	This page has too many comment threads.
`409`	That thread already exists.
`409`	This thread has too many replies.
`409`	That comment was deleted.
`409`	That comment was already deleted.
`409`	Too many reactions.
`413`	Comments can be up to 16 KB.

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

Updates after after (a gap, or one announced as pull); reset when the document was replaced.

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:pageId`	Page id: a Notes page (`doc_…`), or a Feed page (`pgx_…`) under `/v1/messaging/social`; under `marketing` a landing page (`mkp_…`).

Query parameter	Type	Required	Notes
`epoch`	`string`	Yes	1–64 characters
`after`	`integer`	Yes	≥ 0; coerced from a string

Response 200

{
  reset: true
} | {
  reset: false
  updates: {
    seq: number
    update: string
  }[]
  state?: null | string
  seq?: number
}

Errors

Status	Message
`404`	Page not found

`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: a Notes page (`doc_…`), or a Feed page (`pgx_…`) under `/v1/messaging/social`; under `marketing` a landing page (`mkp_…`).

Query parameter	Type	Required	Notes
`permanent`	`"1"`	No

Response 200

{
  deleted: number
}
| {
  page: {
    pageId: string
    parentId: string
    kind: "database" | "doc"
    title: string
    icon?: string
    fullWidth?: boolean
    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" | "checkbox" | "multi_select" | "relation"
      options?: {
        id: string
        name: string
        color?: "gray" | "brown" | "orange" | "yellow" | "green" | "blue" | "purple" | "pink" | "red"
      }[]
      databaseId?: string
    }[]
    views?: {
      name: string
      layout: "calendar" | "table" | "board"
      filters: {
        property: string
        op: "before" | "after" | "contains" | "not_contains" | "is" | "is_not" | "gt" | "lt" | "is_empty" | "is_not_empty"
        value?: boolean | string | number | string[]
      }[]
      id: string
      sort?: null | {
        by: string
        desc: boolean
      }
      groupBy?: string
      dateProperty?: string
      hidden?: string[]
      widths?: {
        [key: string]: number
      }
    }[]
    properties?: {
      [key: string]: boolean | string | number | string[]
    }
  }
}

Errors

Status	Message
`400`	Move the page to the trash first.
`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 databases have views.
`400`	Only database rows have property values.
`400`	Unknown property.
`404`	Page not found
`409`	The page changed. Try again.

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

Saved versions of a page's content, newest first (kept 30 days after they're replaced).

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:pageId`	Page id: a Notes page (`doc_…`), or a Feed page (`pgx_…`) under `/v1/messaging/social`; under `marketing` a landing page (`mkp_…`).

Response 200

{
  versions: {
    versionId: string
    savedAt: number
    size: number
    current: boolean
  }[]
}

Errors

Status	Message
`404`	Page not found

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

One saved version's content, to preview or restore (restoring saves it as a new version).

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:pageId`	Page id: a Notes page (`doc_…`), or a Feed page (`pgx_…`) under `/v1/messaging/social`; under `marketing` a landing page (`mkp_…`).
`:versionId`	Version id: a saved page version, as listed by the page history, an issue space's version (release, `ver_…`), or a Drive file's version (`fvr_…`).

Response 200

{
  content: {
    version: number
    blocks: null | unknown[]
    markdown: string
  }
}

Errors

Status	Message
`404`	Page not found
`404`	Version not found

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

A link to upload an image or file into a page (PUT the bytes with the declared type within 15 minutes).

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:pageId`	Page id: a Notes page (`doc_…`), or a Feed page (`pgx_…`) under `/v1/messaging/social`; under `marketing` a landing page (`mkp_…`).

Request body

Field	Type	Required	Default	Notes
`filename`	`string`	Yes		1–255 characters; trimmed
`contentType`	`string`	No	`"application/octet-stream"`	up to 255 characters; matches `^[\w.+-]+\/[\w.+-]+$`; trimmed
`size`	`integer`	Yes		≥ 1

Response 201

{
  fileId: string
  uploadUrl: string
}

Errors

Status	Message
`400`	This page is in the trash.
`404`	Page not found
`413`	Files can be up to 20 MB.

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

A one-hour link to a file in a page.

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

Path parameter	Description
`:orgId`	Organization id (`org_…`).
`:pageId`	Page id: a Notes page (`doc_…`), or a Feed page (`pgx_…`) under `/v1/messaging/social`; under `marketing` a landing page (`mkp_…`).
`:fileId`	File id, as returned when the upload was created.

Response 200

{
  url: string
}

Errors

Status	Message
`404`	Page not found
`404`	File not found

`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`

Reorders the caller's favorites: page ids in the new order.

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

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

Request body

Field	Type	Required	Notes
`pageIds`	`string[]`	Yes	up to 500 items; each matches `^[A-Za-z0-9_-]{1,64}$`

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: a Notes page (`doc_…`), or a Feed page (`pgx_…`) under `/v1/messaging/social`; under `marketing` a landing page (`mkp_…`).

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: a Notes page (`doc_…`), or a Feed page (`pgx_…`) under `/v1/messaging/social`; under `marketing` a landing page (`mkp_…`).

Response 200

{
  ok: true
}

Errors

Status	Message
`404`	Page not found

Notes pages

On this page