AI Docs (Magic Pad)

Create, edit, and share project-scoped documents — the same docs users see in the Kolbo app's Magic Pad editor.

AI Docs are HTML documents that live inside a project, editable in the Kolbo app's Magic Pad editor. Through the API you (or an LLM driving the MCP) author the document content directly — production plans, briefs, scripts, research summaries — and the user picks it up in the app, fully formatted and editable.

Content is HTML and is sanitized server-side (scripts, iframes, and styles are stripped). Stick to semantic elements the editor understands: <h1>–<h3>, <p>, <ul>/<ol>, <table>, <blockquote>, <strong>/<em>, <a>.

Create a Doc

POST /api/v1/docs

Field	Type	Required	Description
`title`	string	Yes	Document title (max 200 chars).
`content`	string	No	Full HTML body of the document.
`project_id`	string	No	Project to create the doc in (needs `edit`+ permission — see Projects). Omitted → the "API Generations" default project.

curl -X POST https://api.kolbo.ai/api/v1/docs \
  -H "X-API-Key: kolbo_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Production Plan",
    "content": "<h1>Production Plan</h1><p>Shot list and schedule…</p>",
    "project_id": "65f1c8a2e4b0a3c1d9f5e123"
  }'

Response (201):

{
  "success": true,
  "doc": {
    "id": "6a53c31f49989427bdaf199b",
    "title": "Production Plan",
    "project_id": "65f1c8a2e4b0a3c1d9f5e123",
    "is_shared": false,
    "is_editable_by_link": false,
    "share_url": null,
    "created_at": "2026-07-12T16:38:55.871Z",
    "updated_at": "2026-07-12T16:38:55.871Z"
  }
}

List Docs

GET /api/v1/docs

Parameter	Type	Description
`project_id`	string	Optional — restrict to one project.
`page`	number	Page number (default: 1).
`limit`	number	Results per page (default: 20, max: 50).

Returns docs across all your projects, most recently updated first (metadata only — use Get for content).

Get a Doc

GET /api/v1/docs/:id

Returns the doc metadata plus its full HTML content. Readable by the owner and by members of the doc's project.

Update a Doc

PUT /api/v1/docs/:id

Field	Type	Description
`title`	string	New title (optional).
`content`	string	Full replacement HTML — the content replaces the whole document. Read first, apply edits, send the complete result.

Writable by the owner and project members with edit+ permission.

PATCH /api/v1/docs/:id/share

Field	Type	Description
`shared`	boolean	`true` = publicly shared, `false` = private (link stops working). Explicit set, not a toggle.
`editable`	boolean	Optional — allow link visitors to edit the doc.

When shared, the response includes a stable public link:

{
  "success": true,
  "doc": {
    "id": "6a53c31f49989427bdaf199b",
    "is_shared": true,
    "share_url": "https://app.kolbo.ai/shared/magicpad/6d5f837497f742393cb766b0c59f728a"
  }
}

Delete a Doc

DELETE /api/v1/docs/:id

Soft delete, owner only.

MCP Tools

The matching @kolbo/mcp tools are create_doc, list_docs, get_doc, update_doc, share_doc, and delete_doc. The intended flow for an LLM:

1. (user names a project?) list_projects -> capture id
2. create_doc { title, content: "<full HTML you authored>", project_id }
3. (user wants a link?) share_doc { doc_id, shared: true } -> give share_url to the user