Documentation
Product GuideREST API ReferenceMCP Server for AI AgentsWebhooks & EventsIntegrations
READ

list_documents

Lists a project's generated documents newest first with their kind, reference, title, format, status, scope, stamps and download address, narrowed by kind, status or words; a guest token sees the final copies only.

Read the documents a project generated from its own record before you answer a question about what the client was shown or what the team builds against. Each row carries the kind (brd or srs), the reference (BRD #2: documents are numbered within their kind on the project), the title, the format (pdf or html), the status (rendering, draft, failed, in_review, final or superseded), editable and readable (whether a draft can still change, and whether there is a file to fetch), the scope it was rendered from (baseline_id and drafts), the opening prose as summary, the file's size and checksum, the version (0 until approved, 1 once final), the approval stamps, who rendered it and when, when it became final, which copy superseded it, the reason a render failed, and download_url, the REST address of the file when there is one. Narrow with kind, status or search (words the title must contain) and page with limit and page. Rows are newest first. A client guest's token receives the final and superseded copies only; read one document in full, or its words, with get_document.

Requires ability

document:view-any

The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.

Annotations

Read-only

It reads and never changes anything.

Arguments

project_id*string

UUID of the project.

kindstringoptional

Narrow to one kind.

brdsrssprint_reportrelease_notesuat_sign_off_sheettest_summarypost_mortemstatus_reporttraceability_matrixtimesheet
statusstringoptional

Narrow to one status.

renderingdraftfailedin_reviewfinalsuperseded
searchstringoptional

Words the title must contain.

limitintegeroptional

Rows per page, 1 to 100; 25 by default.

pageintegeroptional

The page, from 1.

What it returns

{  "data": [    {      "id": "d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f70",      "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",      "kind": "brd",      "reference": "BRD #2",      "number": 2,      "title": "BRD for the client workshop",      "format": "pdf",      "status": "final",      "editable": false,      "readable": true,      "scope": {        "baseline_id": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",        "drafts": false      },      "summary": "The client needs a portal that serves its customers around the clock.\n\nThis document covers the first release.",      "size": 48213,      "checksum": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",      "version": 1,      "approved_at": "2026-11-04T10:12:00+00:00",      "approved_revision_id": "0e1f2a3b-4c5d-4e6f-8a7b-9c0d1e2f3a4b",      "rendered_by": "3f8a1c2e-7b4d-4e5f-9a6b-1c2d3e4f5a6b",      "renderer_name": "Bea Analyst",      "rendered_at": "2026-11-03T08:05:00+00:00",      "finalised_at": "2026-11-04T10:12:00+00:00",      "superseded_by_id": null,      "render_failure": null,      "download_url": "https://api.example.test/v1/documents/d4e5f6a7-b8c9-4d0e-8f1a-2b3c4d5e6f70/download",      "created_at": "2026-11-03T08:00:00+00:00",      "updated_at": "2026-11-04T10:12:00+00:00"    }  ],  "meta": { "page": 1, "limit": 25, "total": 3, "has_more": false }}

How it fails

VALIDATION_FAILED

unknown kind or status (the response lists the supported values), or limit outside 1..100.

RESOURCE_NOT_FOUND

unknown project_id, or a project outside the token's scope.

FORBIDDEN

the holder's role on the project does not carry document:view-any.

TOKEN_MISSING_ABILITY

token lacks document:view-any.

Related

get_documentone document with, on request, the rendered words.generate_documentask for a BRD or an SRS as the token's holder.list_baselinesthe frozen scope a client copy is rendered from.Documents APIthe same list over REST, and the file itself.

How is this guide?

Last updated on