From da4ac68c036dcf044ca22e7488babbe5900a1c41 Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Wed, 10 Jun 2026 19:22:19 +0200 Subject: [PATCH] docs(API): improve GET /projects/:id/documents documentation MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds conceptual description (why/model including Link header pagination following RFC 5988), documents 401/403 responses with causes, improves curl example to use path param format, adds response example with realistic document values, and fixes q parameter description. Part of DEVEX-119. 🤖 Generated with Claude Code (claude-sonnet-4-6) --- doc/compiled.json | 24 +++++++++++++++++++----- paths/documents/index.yaml | 33 ++++++++++++++++++++++++++------- 2 files changed, 45 insertions(+), 12 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index bf43680f..3041c38f 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -5569,7 +5569,7 @@ "/projects/{project_id}/documents": { "get": { "summary": "List documents", - "description": "List all documents the current user has access to.", + "description": "Returns a paginated list of documents in the specified project that the current user has access to.\n\nUse this endpoint to retrieve the document inventory for a project — for example, to display a list of source files in a dashboard, or to programmatically determine which documents are available before fetching segments.\n\nDocuments are ordered by creation date (newest first). Pagination is communicated via the `Link` response header following RFC 5988 (Web Linking); use the `next` and `prev` relations to traverse pages. The `q` parameter performs a case-insensitive substring match on document names.\n\nPitfalls:\n- Results are scoped to documents the authenticated user can read via `DocumentPolicy#list_documents?`. Users without project read access see an empty list, not a 403.\n- The `per_page` parameter defaults to 25 and is capped at 100. Requests exceeding this cap are clamped silently.\n- Rate limits apply; requests exceeding the account limit return 429. Retry after the interval indicated by the `X-Rate-Limit-Reset` response header.\n", "operationId": "documents/list", "tags": [ "Documents" @@ -5588,7 +5588,7 @@ "$ref": "#/components/parameters/project_id" }, { - "description": "Search query. Filters documents by name (case-insensitive substring match).", + "description": "Filter documents by name. Case-insensitive substring match against the document name field.\n", "name": "q", "in": "query", "example": "invoice", @@ -5599,7 +5599,7 @@ ], "responses": { "200": { - "description": "OK", + "description": "OK — returns an array of document objects. Pagination metadata is in the `Link` response header.", "content": { "application/json": { "schema": { @@ -5630,7 +5630,21 @@ "updated_at": "2015-01-28T09:52:53Z" } } - } + }, + "example": [ + { + "id": "abcd1234cdef1234abcd1234cdef1234", + "name": "email.html", + "created_at": "2024-03-15T10:22:00Z", + "updated_at": "2024-03-16T08:45:00Z" + }, + { + "id": "beef5678cafe5678beef5678cafe5678", + "name": "marketing-landing.html", + "created_at": "2024-02-01T14:00:00Z", + "updated_at": "2024-02-10T09:10:00Z" + } + ] } }, "headers": { @@ -5671,7 +5685,7 @@ "x-code-samples": [ { "lang": "Curl", - "source": "curl \"https://api.phrase.com/v2/documents?project_id=asdf\" \\\n -u USERNAME_OR_ACCESS_TOKEN" + "source": "curl \"https://api.phrase.com/v2/projects/:project_id/documents?q=invoice&page=1&per_page=25\" \\\n -u USERNAME_OR_ACCESS_TOKEN" }, { "lang": "CLI v2", diff --git a/paths/documents/index.yaml b/paths/documents/index.yaml index 718672f5..96b11d76 100644 --- a/paths/documents/index.yaml +++ b/paths/documents/index.yaml @@ -1,6 +1,16 @@ --- summary: List documents -description: List all documents the current user has access to. +description: | + Returns a paginated list of documents in the specified project that the current user has access to. + + Use this endpoint to retrieve the document inventory for a project — for example, to display a list of source files in a dashboard, or to programmatically determine which documents are available before fetching segments. + + Documents are ordered by creation date (newest first). Pagination is communicated via the `Link` response header following RFC 5988 (Web Linking); use the `next` and `prev` relations to traverse pages. The `q` parameter performs a case-insensitive substring match on document names. + + Pitfalls: + - Results are scoped to documents the authenticated user can read via `DocumentPolicy#list_documents?`. Users without project read access see an empty list, not a 403. + - The `per_page` parameter defaults to 25 and is capped at 100. Requests exceeding this cap are clamped silently. + - Rate limits apply; requests exceeding the account limit return 429. Retry after the interval indicated by the `X-Rate-Limit-Reset` response header. operationId: documents/list tags: - Documents @@ -9,8 +19,8 @@ parameters: - "$ref": "../../parameters.yaml#/page" - "$ref": "../../parameters.yaml#/per_page" - "$ref": "../../parameters.yaml#/project_id" -- description: |- - Search query. Filters documents by name (case-insensitive substring match). +- description: | + Filter documents by name. Case-insensitive substring match against the document name field. name: q in: query example: invoice @@ -18,13 +28,22 @@ parameters: type: string responses: '200': - description: OK + description: OK — returns an array of document objects. Pagination metadata is in the `Link` response header. content: application/json: schema: type: array items: "$ref": "../../schemas/document.yaml#/document" + example: + - id: abcd1234cdef1234abcd1234cdef1234 + name: email.html + created_at: '2024-03-15T10:22:00Z' + updated_at: '2024-03-16T08:45:00Z' + - id: beef5678cafe5678beef5678cafe5678 + name: marketing-landing.html + created_at: '2024-02-01T14:00:00Z' + updated_at: '2024-02-10T09:10:00Z' headers: X-Rate-Limit-Limit: "$ref": "../../headers.yaml#/X-Rate-Limit-Limit" @@ -38,19 +57,19 @@ responses: "$ref": "../../headers.yaml#/Pagination" '400': "$ref": "../../responses.yaml#/400" - '404': - "$ref": "../../responses.yaml#/404" '401': "$ref": "../../responses.yaml#/401" '403': "$ref": "../../responses.yaml#/403" description: Forbidden. Returned when the access token lacks the `read` scope or when the requesting user is not allowed to list documents in this project. + '404': + "$ref": "../../responses.yaml#/404" '429': "$ref": "../../responses.yaml#/429" x-code-samples: - lang: Curl source: |- - curl "https://api.phrase.com/v2/documents?project_id=asdf" \ + curl "https://api.phrase.com/v2/projects/:project_id/documents?q=invoice&page=1&per_page=25" \ -u USERNAME_OR_ACCESS_TOKEN - lang: CLI v2 source: |-