Documents

Documents are notes, specs, references and links filed under your spaces and projects. Every endpoint acts only on your own documents and needs an API key or a signed-in session — see API keys. Requests without one get 401 Unauthorized; error responses carry an error message.

List documents

Lists your documents, ordered by sortOrder. There is no pagination.

GET /api/documents

Both filters are optional and combine.

Query parameters

Name	Type	Required	Description
spaceId	string	No	Only documents in this space
projectId	string	No	Only documents in this project

Response

200 OK with a JSON array of documents.

[
  {
    "id": "7c2f9a4e-1b3d-4a6c-9e08-2f5d81b7a9c4",
    "userId": "b1d4e7a0-2c5f-4b8e-9a1d-6c3f0e2b5a78",
    "spaceId": "9a3c6e2f-7d1b-4f5a-8c0e-3b6d9f1a4c27",
    "projectId": null,
    "title": "Reading list",
    "content": "# To read\n\n- The Pragmatic Programmer",
    "url": null,
    "docType": "note",
    "sortOrder": 0,
    "createdAt": "2026-09-28T22:14:03.118Z",
    "updatedAt": "2026-09-29T07:41:52.664Z",
    "space": { "id": "9a3c6e2f-7d1b-4f5a-8c0e-3b6d9f1a4c27", "name": "Personal", "color": "#6B7280" },
    "project": null
  }
]

Each document carries space and project summaries with id, name and color, or null when it has none.

Errors

• 401 Unauthorized — no valid API key or session.

Create a document

Creates a document.

POST /api/documents

The body sets the new document’s fields.

Body fields

Name	Type	Required	Description
title	string	Yes	1–500 characters
content	string	No	Markdown content
url	string	No	External link; must be a valid URL
docType	string	No	note, spec, reference or link; defaults to note
spaceId	string	No	Space to file it under; must be one of yours
projectId	string	No	Project to file it under; must be one of yours

Response

201 Created with the new document.

{
  "id": "2b9e4f71-8d0c-4a3b-b52e-7f1c8a6d0e39",
  "userId": "b1d4e7a0-2c5f-4b8e-9a1d-6c3f0e2b5a78",
  "spaceId": "9a3c6e2f-7d1b-4f5a-8c0e-3b6d9f1a4c27",
  "projectId": "4d8c1f60-9a2b-4e7d-8c5a-1f0e3b7a9c26",
  "title": "Launch checklist",
  "content": "# Launch\n\n- [ ] Smoke test",
  "url": null,
  "docType": "spec",
  "sortOrder": 0,
  "createdAt": "2026-09-30T22:14:03.118Z",
  "updatedAt": "2026-09-30T22:14:03.118Z"
}

The create response carries the plain record; the space, project and tasks entries only come back from the Get a document response.

Errors

• 400 Bad Request — a field failed validation; details names the fields.
• 400 Bad Request — spaceId or projectId is not a UUID or does not name one of your records; field names the offender and error is <field> not found.
• 401 Unauthorized — no valid API key or session.

Get a document

Returns one document with its space, project and linked tasks.

GET /api/documents/{id}

{id} is the document’s id.

Response

200 OK with the document.

{
  "id": "2b9e4f71-8d0c-4a3b-b52e-7f1c8a6d0e39",
  "userId": "b1d4e7a0-2c5f-4b8e-9a1d-6c3f0e2b5a78",
  "spaceId": "9a3c6e2f-7d1b-4f5a-8c0e-3b6d9f1a4c27",
  "projectId": "4d8c1f60-9a2b-4e7d-8c5a-1f0e3b7a9c26",
  "title": "Launch checklist",
  "content": "# Launch\n\n- [ ] Smoke test",
  "url": null,
  "docType": "spec",
  "sortOrder": 0,
  "createdAt": "2026-09-30T22:14:03.118Z",
  "updatedAt": "2026-09-30T22:14:03.118Z",
  "space": { "id": "9a3c6e2f-7d1b-4f5a-8c0e-3b6d9f1a4c27", "name": "Personal", "color": "#6B7280" },
  "project": { "id": "4d8c1f60-9a2b-4e7d-8c5a-1f0e3b7a9c26", "name": "Launch", "color": "#3B82F6" },
  "tasks": [
    {
      "taskId": "c9f2a5d8-3e6b-4a1c-9d7f-2b5e8a0c3f64",
      "documentId": "2b9e4f71-8d0c-4a3b-b52e-7f1c8a6d0e39",
      "task": { "id": "c9f2a5d8-3e6b-4a1c-9d7f-2b5e8a0c3f64", "title": "Write project brief", "status": "todo" }
    }
  ]
}

Each tasks entry is a task linked to the document, carrying the task’s id, title and status.

Errors

• 404 Not Found — no document of that id belongs to you.
• 401 Unauthorized — no valid API key or session.

Update a document

Changes a document’s fields.

PATCH /api/documents/{id}

Every body field is optional; fields you leave out keep their values.

Body fields

Name	Type	Required	Description
title	string	No	1–500 characters
content	string	No	Replaces the markdown content
url	string or null	No	External link; null clears it
docType	string	No	note, spec, reference or link
spaceId	string or null	No	Move it to another space; null detaches it
projectId	string or null	No	Move it to another project; null detaches it
sortOrder	number	No	Position in manual sorts

Response

200 OK with the updated document in the same shape as the Create a document response.

{
  "id": "2b9e4f71-8d0c-4a3b-b52e-7f1c8a6d0e39",
  "userId": "b1d4e7a0-2c5f-4b8e-9a1d-6c3f0e2b5a78",
  "spaceId": null,
  "projectId": "4d8c1f60-9a2b-4e7d-8c5a-1f0e3b7a9c26",
  "title": "Launch checklist",
  "content": "# Launch\n\n- [x] Smoke test",
  "url": null,
  "docType": "spec",
  "sortOrder": 1,
  "createdAt": "2026-09-30T22:14:03.118Z",
  "updatedAt": "2026-09-30T23:02:47.559Z"
}

This update detached the document from its space by sending spaceId as null.

Errors

• 400 Bad Request — a field failed validation; details names the fields.
• 400 Bad Request — spaceId or projectId is not a UUID or does not name one of your records; field names the offender and error is <field> not found.
• 404 Not Found — no document of that id belongs to you.
• 401 Unauthorized — no valid API key or session.

Delete a document

Deletes a document for good.

DELETE /api/documents/{id}

It takes no body.

Response

200 OK once the document is gone.

{ "success": true }

Deleting a document removes its links to tasks; the tasks themselves stay.

Errors

• 404 Not Found — no document of that id belongs to you.
• 401 Unauthorized — no valid API key or session.

Example: create a document

Create a markdown note filed under a space in one call.

curl -X POST https://tasks.example.com/api/documents \
  -H "Authorization: Bearer dp_change-me" \
  -H "Content-Type: application/json" \
  -d '{"title":"Reading list","content":"# To read","docType":"note","spaceId":"9a3c6e2f-7d1b-4f5a-8c0e-3b6d9f1a4c27"}'

The response is 201 Created with the new document; drop spaceId to leave the document unfiled.

See also

• Using documents: how documents fit around spaces and projects
• Tasks: link documents to tasks
• MCP tools: list, read and create documents from an agent
• API keys: authenticate REST calls