From edd317fe66ee236e518cf6c53e8a0224a55c19fc Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Mon, 15 Jun 2026 16:53:41 +0200 Subject: [PATCH 1/2] feat(API): improve get /projects/{project_id}/documents documentation --- doc/compiled.json | 40 ++++++++++++++++++++++++------- paths/documents/index.yaml | 49 ++++++++++++++++++++++++++++++++------ 2 files changed, 74 insertions(+), 15 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index afba5090..f67214b7 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 all documents in a project that the authenticated user has read access to. A Document is a source file — such as an HTML or YAML file — that has been uploaded to Phrase Strings and whose content is segmented into translation keys for localization.\n\nUse this endpoint to enumerate documents before downloading, previewing, or triggering translation workflows for individual files.\n\nThe q parameter performs a prefix match on the document name (case-insensitive). For example, passing q=invoice returns documents whose names begin with \"invoice\" but not documents containing \"invoice\" elsewhere in the name.\n\nRequires the read OAuth scope. Returns 403 when the requesting user does not have read permission on documents in this project.\n", "operationId": "documents/list", "tags": [ "Documents" @@ -5579,19 +5579,20 @@ "$ref": "#/components/parameters/X-PhraseApp-OTP" }, { - "$ref": "#/components/parameters/page" + "$ref": "#/components/parameters/project_id" }, { - "$ref": "#/components/parameters/per_page" + "$ref": "#/components/parameters/page" }, { - "$ref": "#/components/parameters/project_id" + "$ref": "#/components/parameters/per_page" }, { - "description": "Search query. Filters documents by name (case-insensitive substring match).", + "description": "Filter documents by name prefix. Returns documents whose name starts with the given value (case-insensitive).", + "example": "invoice", "name": "q", "in": "query", - "example": "invoice", + "required": false, "schema": { "type": "string" } @@ -5630,6 +5631,25 @@ "updated_at": "2015-01-28T09:52:53Z" } } + }, + "examples": { + "success": { + "summary": "Example document list response", + "value": [ + { + "id": "abcd1234cdef1234abcd1234cdef1234", + "name": "email.html", + "created_at": "2015-01-28T09:52:53Z", + "updated_at": "2015-03-04T11:22:30Z" + }, + { + "id": "ef012345ef012345ef012345ef012345", + "name": "invoice.yaml", + "created_at": "2015-02-10T14:30:00Z", + "updated_at": "2015-03-01T08:00:00Z" + } + ] + } } } }, @@ -5659,7 +5679,7 @@ }, "403": { "$ref": "#/components/responses/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." + "description": "Forbidden. Returned when the access token lacks the `read` OAuth scope, when the account email is unconfirmed, or when the requesting user does not have read permission on documents in this project." }, "404": { "$ref": "#/components/responses/404" @@ -5671,7 +5691,11 @@ "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\" \\\n -u USERNAME_OR_ACCESS_TOKEN" + }, + { + "lang": "Response", + "source": "[\n {\n \"id\": \"abcd1234cdef1234abcd1234cdef1234\",\n \"name\": \"email.html\",\n \"created_at\": \"2015-01-28T09:52:53Z\",\n \"updated_at\": \"2015-03-04T11:22:30Z\"\n },\n {\n \"id\": \"ef012345ef012345ef012345ef012345\",\n \"name\": \"invoice.yaml\",\n \"created_at\": \"2015-02-10T14:30:00Z\",\n \"updated_at\": \"2015-03-01T08:00:00Z\"\n }\n]" }, { "lang": "CLI v2", diff --git a/paths/documents/index.yaml b/paths/documents/index.yaml index 718672f5..aa1b4080 100644 --- a/paths/documents/index.yaml +++ b/paths/documents/index.yaml @@ -1,19 +1,26 @@ --- summary: List documents -description: List all documents the current user has access to. +description: | + Returns all documents in a project that the authenticated user has read access to. A Document is a source file — such as an HTML or YAML file — that has been uploaded to Phrase Strings and whose content is segmented into translation keys for localization. + + Use this endpoint to enumerate documents before downloading, previewing, or triggering translation workflows for individual files. + + The q parameter performs a prefix match on the document name (case-insensitive). For example, passing q=invoice returns documents whose names begin with "invoice" but not documents containing "invoice" elsewhere in the name. + + Requires the read OAuth scope. Returns 403 when the requesting user does not have read permission on documents in this project. operationId: documents/list tags: - Documents parameters: - "$ref": "../../parameters.yaml#/X-PhraseApp-OTP" +- "$ref": "../../parameters.yaml#/project_id" - "$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 prefix. Returns documents whose name starts with the given value (case-insensitive). + example: invoice name: q in: query - example: invoice + required: false schema: type: string responses: @@ -25,6 +32,18 @@ responses: type: array items: "$ref": "../../schemas/document.yaml#/document" + examples: + success: + summary: Example document list response + value: + - id: abcd1234cdef1234abcd1234cdef1234 + name: email.html + created_at: '2015-01-28T09:52:53Z' + updated_at: '2015-03-04T11:22:30Z' + - id: ef012345ef012345ef012345ef012345 + name: invoice.yaml + created_at: '2015-02-10T14:30:00Z' + updated_at: '2015-03-01T08:00:00Z' headers: X-Rate-Limit-Limit: "$ref": "../../headers.yaml#/X-Rate-Limit-Limit" @@ -44,14 +63,30 @@ responses: "$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. + description: Forbidden. Returned when the access token lacks the `read` OAuth scope, when the account email is unconfirmed, or when the requesting user does not have read permission on documents in this project. '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" \ -u USERNAME_OR_ACCESS_TOKEN +- lang: Response + source: |- + [ + { + "id": "abcd1234cdef1234abcd1234cdef1234", + "name": "email.html", + "created_at": "2015-01-28T09:52:53Z", + "updated_at": "2015-03-04T11:22:30Z" + }, + { + "id": "ef012345ef012345ef012345ef012345", + "name": "invoice.yaml", + "created_at": "2015-02-10T14:30:00Z", + "updated_at": "2015-03-01T08:00:00Z" + } + ] - lang: CLI v2 source: |- phrase documents list \ From f916aa048aafb553cb76bd0a24c1ac038c93ed9c Mon Sep 17 00:00:00 2001 From: Stephen Lumenta Date: Wed, 17 Jun 2026 21:01:21 +0100 Subject: [PATCH 2/2] docs(API): address review on get /projects/{project_id}/documents - Correct the document-type description: only HTML and DOCX files are listed (was 'HTML or YAML'); fix the example value invoice.yaml -> invoice.docx accordingly. (theSoenke) - Drop the 'Requires the read OAuth scope ...' sentence from the description; no other endpoint documents scopes in prose and the 403 response already explains the read requirement. (theSoenke) - Remove the 'Response' code sample; the 200 example already shows the response shape and no other endpoint inlines a response sample. (theSoenke) Co-Authored-By: Claude Opus 4.8 (1M context) --- doc/compiled.json | 8 ++------ paths/documents/index.yaml | 22 ++-------------------- 2 files changed, 4 insertions(+), 26 deletions(-) diff --git a/doc/compiled.json b/doc/compiled.json index f67214b7..7ae44a6b 100644 --- a/doc/compiled.json +++ b/doc/compiled.json @@ -5569,7 +5569,7 @@ "/projects/{project_id}/documents": { "get": { "summary": "List documents", - "description": "Returns all documents in a project that the authenticated user has read access to. A Document is a source file — such as an HTML or YAML file — that has been uploaded to Phrase Strings and whose content is segmented into translation keys for localization.\n\nUse this endpoint to enumerate documents before downloading, previewing, or triggering translation workflows for individual files.\n\nThe q parameter performs a prefix match on the document name (case-insensitive). For example, passing q=invoice returns documents whose names begin with \"invoice\" but not documents containing \"invoice\" elsewhere in the name.\n\nRequires the read OAuth scope. Returns 403 when the requesting user does not have read permission on documents in this project.\n", + "description": "Returns all documents in a project that the authenticated user has read access to. A Document is a source file — an HTML or DOCX file — that has been uploaded to Phrase Strings and whose content is segmented into translation keys for localization.\n\nUse this endpoint to enumerate documents before downloading, previewing, or triggering translation workflows for individual files.\n\nThe q parameter performs a prefix match on the document name (case-insensitive). For example, passing q=invoice returns documents whose names begin with \"invoice\" but not documents containing \"invoice\" elsewhere in the name.\n", "operationId": "documents/list", "tags": [ "Documents" @@ -5644,7 +5644,7 @@ }, { "id": "ef012345ef012345ef012345ef012345", - "name": "invoice.yaml", + "name": "invoice.docx", "created_at": "2015-02-10T14:30:00Z", "updated_at": "2015-03-01T08:00:00Z" } @@ -5693,10 +5693,6 @@ "lang": "Curl", "source": "curl \"https://api.phrase.com/v2/projects/:project_id/documents\" \\\n -u USERNAME_OR_ACCESS_TOKEN" }, - { - "lang": "Response", - "source": "[\n {\n \"id\": \"abcd1234cdef1234abcd1234cdef1234\",\n \"name\": \"email.html\",\n \"created_at\": \"2015-01-28T09:52:53Z\",\n \"updated_at\": \"2015-03-04T11:22:30Z\"\n },\n {\n \"id\": \"ef012345ef012345ef012345ef012345\",\n \"name\": \"invoice.yaml\",\n \"created_at\": \"2015-02-10T14:30:00Z\",\n \"updated_at\": \"2015-03-01T08:00:00Z\"\n }\n]" - }, { "lang": "CLI v2", "source": "phrase documents list \\\n--project_id \\\n--access_token " diff --git a/paths/documents/index.yaml b/paths/documents/index.yaml index aa1b4080..8f5442ec 100644 --- a/paths/documents/index.yaml +++ b/paths/documents/index.yaml @@ -1,13 +1,11 @@ --- summary: List documents description: | - Returns all documents in a project that the authenticated user has read access to. A Document is a source file — such as an HTML or YAML file — that has been uploaded to Phrase Strings and whose content is segmented into translation keys for localization. + Returns all documents in a project that the authenticated user has read access to. A Document is a source file — an HTML or DOCX file — that has been uploaded to Phrase Strings and whose content is segmented into translation keys for localization. Use this endpoint to enumerate documents before downloading, previewing, or triggering translation workflows for individual files. The q parameter performs a prefix match on the document name (case-insensitive). For example, passing q=invoice returns documents whose names begin with "invoice" but not documents containing "invoice" elsewhere in the name. - - Requires the read OAuth scope. Returns 403 when the requesting user does not have read permission on documents in this project. operationId: documents/list tags: - Documents @@ -41,7 +39,7 @@ responses: created_at: '2015-01-28T09:52:53Z' updated_at: '2015-03-04T11:22:30Z' - id: ef012345ef012345ef012345ef012345 - name: invoice.yaml + name: invoice.docx created_at: '2015-02-10T14:30:00Z' updated_at: '2015-03-01T08:00:00Z' headers: @@ -71,22 +69,6 @@ x-code-samples: source: |- curl "https://api.phrase.com/v2/projects/:project_id/documents" \ -u USERNAME_OR_ACCESS_TOKEN -- lang: Response - source: |- - [ - { - "id": "abcd1234cdef1234abcd1234cdef1234", - "name": "email.html", - "created_at": "2015-01-28T09:52:53Z", - "updated_at": "2015-03-04T11:22:30Z" - }, - { - "id": "ef012345ef012345ef012345ef012345", - "name": "invoice.yaml", - "created_at": "2015-02-10T14:30:00Z", - "updated_at": "2015-03-01T08:00:00Z" - } - ] - lang: CLI v2 source: |- phrase documents list \