overlay: 1.0.0 info: title: API Evangelist enhancements for TextMaster API v1 version: 1.0.0 extends: openapi/textmaster-api-v1-openapi.yml x-generated: '2026-08-17' x-method: generated x-source: >- Enhancements derived from https://developer.textmaster.com/ (the provider's own developer portal) and from live probes of api.textmaster.com on 2026-08-17. The harvested specification at openapi/_original/textmaster-api-v1-openapi-original.yml is never mutated. x-rationale: >- TextMaster's published OpenAPI is functionally complete but metadata-thin: info carries only a title and a version, there are no tag descriptions, no contact, no license, no terms, and — most consequentially — not one of the 54 operations declares an operationId. This overlay adds the descriptive and provenance metadata that the docs supply in prose, without touching a single schema, parameter or response. It deliberately does NOT invent operationIds: minting ids the provider does not publish would create identifiers that look canonical and are not, and would break the moment TextMaster publishes its own. actions: - target: $.info description: Add the descriptive, contact and provenance metadata the published spec omits. update: description: >- REST API for ordering and managing professional translation, proofreading and copywriting work on the TextMaster platform. Projects hold the commercial and linguistic parameters; Documents hold the content. The lifecycle is create -> attach documents -> (optionally quote) -> finalize -> launch, where launch debits a prepaid credit wallet. Progress is delivered by status-change callbacks rather than polling. Authentication is OAuth 2.0 authorization code with 22 granular scopes; a legacy Apikey/Date/Signature strategy exists for test use only. A parallel sandbox is available at https://api.textmasterstaging.com/. contact: name: TextMaster Support email: support@textmaster.com url: https://developer.textmaster.com/ x-security-contact: bounty@textmaster.com x-apievangelist-profile: https://apis.io/provider/textmaster x-parent-organization: Acolad Group - target: $.servers description: >- Record the sandbox host alongside production. The published spec lists only production, so a generated client has no way to reach the test environment the docs describe. update: - url: https://api.textmaster.com description: Production. - url: https://api.textmasterstaging.com description: >- Sandbox. "It behaves the same way as the production environment." (https://developer.textmaster.com/overview/resources-in-the-rest-api). Requires its own account and OAuth app; no shared test credentials are published. - target: $ description: >- Declare the tag vocabulary with descriptions. The spec uses 20 tags across its operations but declares none of them at the document root, so tooling renders bare tag names with no guidance. update: tags: - name: Projects description: >- The container for a unit of work — language pair, activity, category, briefing, options, templates and callbacks. Also carries the lifecycle transitions (quote, finalize, launch, pause, resume, cancel, archive, duplicate) and the translation-memory controls. - name: Documents description: >- The content to be worked on, attached to a project. Prefer the batch create; prefer sending a file URL over inline text. Exposes review URLs and per-document completion. externalDocs: url: https://developer.textmaster.com/guides/integrator-best-practices - name: 'My Authors' description: >- The client's curated roster of preferred, blacklisted or uncategorized human authors. Guarded by the preferred_author:* scope family. - name: Authors description: Discovery of authors eligible to work on a given project. - name: Abilities description: Author capability records, filterable by activity. - name: Glossaries description: >- Client terminology sets enforced across projects, including sets shared from the organization. - name: 'Work Templates' description: Reusable definitions of the work to be performed. - name: 'API Templates' description: Reusable project configurations addressable by the API. - name: 'Support Messages' description: >- Human message thread between the client and the assigned author on a specific document. Guarded by the discussion:* scopes; emits the support_message_created event. - name: Transactions description: Movements against the prepaid credit wallet. - name: Invoices description: Issued invoices. - name: Receipts description: Payment receipts. - name: 'Negotiated Contracts' description: >- Individually negotiated commercial terms — the API-visible evidence that enterprise pricing is bespoke rather than published. - name: Users description: >- The authenticated identity, plus the account-level callback (webhook) registration used to subscribe to events globally. - name: UploadProperties description: >- Issues signed properties for uploading a file to TextMaster's temporary store. Files not linked to a document are deleted after 60 days. - name: Expertises description: Subject-matter expertise taxonomy, with sub-expertises. Public reference data. - name: Categories description: Content category taxonomy (C001-C010). Public reference data. - name: Languages description: Supported source and target languages. Public reference data. - name: Locales description: Supported locales. Public reference data. - name: Countries description: Supported countries. Public reference data. - target: $ description: >- Attach external documentation, which the published spec omits entirely. update: externalDocs: description: TextMaster Developer Documentation url: https://developer.textmaster.com/ - target: $.components.securitySchemes.oauth2 description: >- Complete the scope map. The published flow declares only the three preferred_author scopes even though operation security[] requirements reference 21 and the documented table plus the provider's own Postman collection name 22. Descriptions are the provider's own wording. update: flows: authorizationCode: scopes: public: >- Grants read-only access to public information (such as, but not limited to, available languages, options, pricing, expertises). This is the default scope if none is provided. 'user:manage': Grants full access to user's profile info only (includes user:email). 'user:read': Grants read-only access to user's profile info. 'user:write': Grants read/write access to user's profile info. 'user:email': Grants read-only access to user's private email address. 'glossary:manage': Grants full access to glossaries (includes the ones shared from organization). 'glossary:read': Grants read-only access to glossaries (includes the ones shared from organization). 'glossary:write': Grants read/write access to glossaries (includes the ones shared from organization). 'project:manage': >- Grants full access to projects, documents and templates (includes project:launch and project:quote). 'project:read': Grants read-only access to projects, documents and templates. 'project:write': Grants read/write access to projects, documents and templates. 'project:launch': Grants access to launch projects and debit the client's account. 'project:quote': Grants access to request project quotations. 'discussion:manage': Grants full access to team discussions. 'discussion:read': Grants read-only access to team discussions. 'discussion:write': Grants read/write access to team discussions. 'transaction:manage': >- Full access to financial transactions. Referenced by operation security[] and by TextMaster's own Postman collection, but absent from the published scopes table. 'transaction:read': Grants read-only access to financial transactions. 'transaction:write': >- Write access to financial transactions. Referenced by operation security[] and by TextMaster's own Postman collection, but absent from the published scopes table. 'preferred_author:manage': Grants full access to client's preferred authors. 'preferred_author:read': Grants read-only access to client's preferred authors. 'preferred_author:write': Grants write access to client's preferred authors. - target: $.components.securitySchemes description: >- Add the second authentication strategy. The docs describe a signature scheme the spec does not declare, so a client generated from the spec alone cannot use the test-oriented auth path the quick-start teaches. update: signature: type: apiKey in: header name: Apikey description: >- LEGACY, TEST USE ONLY. "TextMaster discourages using the signature strategy to authenticate production applications to the API. Clients should use OAuth2 Apps instead." Requires three headers: `Apikey` (public key), `Date` (UTC, format YYYY-MM-DD HH:MM:SS), and `Signature` (SHA-1 hex digest of api_secret concatenated with that date). Valid for 5 minutes. Validate a triple against GET /test. x-additional-headers: - Date - Signature x-signature-algorithm: sha1(api_secret || date) x-validity-seconds: 300 x-docs: https://developer.textmaster.com/overview/authentication - target: $.paths['/v1/clients/projects/{project_id}/launch'].put description: >- Warn about the synchronous launch. The provider's own guidance is to prefer the async variant; the spec gives no hint that this operation can be terminated by the 30-second server timeout. update: x-apievangelist-warning: >- Synchronous launch. TextMaster terminates any request exceeding 30 seconds, so this operation can time out on a project of realistic size. Prefer POST /v1/clients/projects/{project_id}/async_launch and wait for the project_in_progress event. x-spend-authority: >- Debits the client's prepaid credit wallet. Requires the project:launch scope. There is no idempotency key on this operation; if the response is lost, do not blind-retry — re-read the project, or wait up to 30 minutes for project_in_progress before retrying (the provider's documented reconciliation window). - target: $.paths['/v1/clients/projects/{project_id}/async_launch'].post update: x-spend-authority: >- Debits the client's prepaid credit wallet. Requires the project:launch scope. Completion is signalled by the project_in_progress event; project_not_launched signals insufficient credits. x-no-idempotency-key: true - target: $.paths['/v1/clients/projects/{project_id}/finalize'].put update: x-apievangelist-note: >- Finalization runs translation-memory and/or PEMT analysis, which can CHANGE the project cost. Re-read the project (or wait for project_tm_completed) before launching so the amount debited is the amount expected. - target: $.paths['/v1/clients/users/{user_id}'].put description: >- Name what this operation actually is. Its summary, "Update my callback information", conceals that it is the account-level webhook subscription API. update: x-apievangelist-role: webhook-subscription x-event-catalog: asyncapi/textmaster-event-surface.yml x-apievangelist-note: >- This is how a client subscribes to events globally, by writing a callback URL per event name under user.callback. Project- and document-level callbacks are set on their own create/update operations instead. There is no HMAC signature header on deliveries; the documented pattern is a high-entropy shared secret carried as a query parameter of the callback URL. - target: $.paths['/v1/clients/projects/quotation'].get update: x-apievangelist-note: >- The dry run. Prices work from activity, language pair, expertise, language level, quality, priority and word count without creating anything or spending anything. TextMaster publishes no rate card, so this operation IS the price list. - target: $.paths['/v1/clients/projects/{project_id}/documents'].post update: x-apievangelist-warning: >- For more than a couple of documents, use POST /v1/clients/projects/{project_id}/batch/documents instead. The provider's best-practices guide works an example showing that unbatched or over-large creates hit the 30-second timeout, and recommends batches of roughly 10 documents or fewer. - target: $.components.schemas.CallbackUrl description: >- Enumerate the event names. The spec types callbacks as free-form object keys, so no generated client knows the vocabulary is closed. update: description: >- A webhook destination. `url` is the HTTPS endpoint TextMaster POSTs to; `format` selects the payload format. The KEY this object sits under is the event name, drawn from a closed set of 19 documented events (7 project-level, 12 document-level) — see asyncapi/textmaster-event-surface.yml. Deliveries carry an X-TextMaster-Event header, are retried up to 20 times with exponential backoff, are at-least-once and are UNORDERED, so the receiver must be idempotent. x-event-names: project: - project_in_progress - project_finalized - project_not_launched - project_canceled - project_tm_completed - project_tm_diff_completed - project_in_review document: - waiting_assignment - in_progress - in_review - incomplete - completed - paused - canceled - quality_control - copyscape - counting_words - word_count_finished - support_message_created