PolderAPI

Docs API

Comments, users and skills

Read and post comments, list the workspace's people and skills, and find out who the integration is.

Base URLhttps://docs.polder.work

The comment object

{
  "object": "comment",
  "id": "01k8x3a4b6c8d0e2f4g6h8j0kl",
  "parent": { "type": "page_id", "page_id": "01k8x2m4t7q9b3n5v6c8d0f2gh" },
  "discussion_id": "01k8x3a4b6c8d0e2f4g6h8j0kl",
  "created_time": "2026-10-02T10:00:00.000Z",
  "last_edited_time": "2026-10-02T10:00:00.000Z",
  "created_by": { "object": "user", "id": "3" },
  "rich_text": [ { "type": "text", "text": { "content": "Deployed." }, "plain_text": "Deployed." } ],
  "resolved": false
}

parent is a page_id for a comment on a page and a block_id for a comment on a block. discussion_id is the id of the first comment of the thread; for that comment it is its own id.

List comments

GET/api/v1/commentscapability read_comments

Lists the comments on a page or block, oldest discussion first, each followed by its replies, as a paginated list.

Query

Parameter Required Description
block_id yes The page or block to read. Missing gives 400 validation_error
start_cursor, page_size no Pagination

For a page, the list includes the discussions on blocks in its body, but not those inside sub-pages.

curl "https://docs.polder.work/api/v1/comments?block_id=01k8x2m4t7q9b3n5v6c8d0f2gh" \
  -H "Authorization: Bearer $POLDER_DOCS_KEY"

Create a comment

POST/api/v1/commentscapability insert_comments

Starts a discussion on a page or block, or replies in one. Returns the new comment.

Body

Field Type Required Description
rich_text array yes The text. At most 5000 characters, not empty
parent object for a new discussion {"page_id": …} or {"block_id": …}
discussion_id string for a reply The thread to reply in. An unknown id is a 404

Comments are plain text: formatting in rich_text is dropped. They are posted as the admin who created the integration, and the page's followers are notified as usual. The admin needs permission to comment on the page.

curl https://docs.polder.work/api/v1/comments \
  -H "Authorization: Bearer $POLDER_DOCS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"parent": {"page_id": "01k8x2m4t7q9b3n5v6c8d0f2gh"}, "rich_text": [{"text": {"content": "Deployed."}}]}'

Reply in a thread:

{ "discussion_id": "01k8x3a4b6c8d0e2f4g6h8j0kl", "rich_text": [ { "text": { "content": "Thanks!" } } ] }

List skills

GET/api/v1/skillscapability read_skills

Lists the workspace's skills (Settings → Skills in the app), A to Z by name, as a paginated list. Skills belong to the workspace, so no page has to be connected to the integration. Not in Notion's API.

curl https://docs.polder.work/api/v1/skills \
  -H "Authorization: Bearer $POLDER_DOCS_KEY"

{
  "object": "list",
  "results": [
    {
      "object": "skill",
      "id": "01k8x4b5c7d9e1f3g5h7j9k1lm",
      "name": "Monthly review",
      "slug": "monthly-review",
      "description": "Write the monthly business review.",
      "instructions": "Use our template…",
      "created_time": "2026-10-08T10:00:00.000Z",
      "last_edited_time": "2026-10-08T10:00:00.000Z"
    }
  ],
  "next_cursor": null,
  "has_more": false,
  "type": "skill",
  "skill": {}
}

List users

GET/api/v1/userscapability read_user_info

Lists the workspace's people by name, as a paginated list. Each has an email address.

curl https://docs.polder.work/api/v1/users \
  -H "Authorization: Bearer $POLDER_DOCS_KEY"

{ "object": "user", "id": "3", "type": "person", "name": "Ann", "avatar_url": null, "person": { "email": "ann@example.com" } }

Retrieve the integration

GET/api/v1/users/mecapability none

Returns the integration itself as a bot user. Needs no capability, so it is the easiest way to check a key.

curl https://docs.polder.work/api/v1/users/me \
  -H "Authorization: Bearer $POLDER_DOCS_KEY"

{
  "object": "user",
  "id": "01k8x1z9y8x7w6v5u4t3s2r1qp",
  "type": "bot",
  "name": "Release script",
  "avatar_url": null,
  "bot": { "owner": { "type": "workspace", "workspace": true }, "workspace_name": "Acme" }
}

Note: The bot's id is the integration's id. It never appears as created_by on anything: edits and comments name the admin who made the integration.

Retrieve a user

GET/api/v1/users/{id}capability read_user_info

Returns one person of the workspace (numeric id, as a string). 404 object_not_found for anyone who is not a member, or for an id that is not a number.

curl https://docs.polder.work/api/v1/users/3 \
  -H "Authorization: Bearer $POLDER_DOCS_KEY"