Working with documents

Documents are PRDs, specs, strategy docs and other product documents. Each one is stored as Markdown, lives in your personal workspace or in a team organization, and can optionally belong to a project.

Full request and response schemas are in the reference: List documents, Create a document, Get a document and Update a document.

Scoping to a team

Omit organizationId to work in your personal workspace. Pass organizationId (an id starting with org_, from GET /organizations) to work inside one of your teams. Always pass the same organizationId when reading or updating a document you found under it.

Searching

GET /documents?q=onboarding&organizationId=org_...&projectId=...&limit=20

q matches document titles and bodies, in both personal and team workspaces. Results are sorted by most recently updated and omit document bodies; fetch a single document for its contentMarkdown.

Creating

POST /documents requires connector:write. title and contentMarkdown are required. Send complete, well-structured Markdown with headings; ChatPRD renders it in the rich-text editor and returns a url you can open in the app.

Creating is not idempotent. Search first (GET /documents?q=<title>) if you may already have created the document.

Updating: read before you write

PATCH /documents/{id} requires connector:write and replaces the entire document; there is no partial patch.

1. GET /documents/{id} to fetch the current contentMarkdown.
2. Edit the Markdown.
3. PATCH the whole document back with the GET response's updatedAt value as expectedUpdatedAt, passing organizationId if it lives in a team.

If someone changes the document after your GET, the update returns 409 conflict. Fetch the latest document, reapply the requested edit, and retry with its new updatedAt value instead of overwriting the newer work.

Formatting is normalized on save (for example, list bullets may be rewritten), so don't rely on byte-for-byte equality between what you send and what you read back.