> ## Documentation Index > Fetch the complete documentation index at: https://docs.textsetu.com/llms.txt > Use this file to discover all available pages before exploring further. # List / search keys (paginated) > Return a paginated page of a project's translation keys, each with its values across every language. Combine the query params to search by name or source text, filter by tag / status / outdated, and sort. Pass `?branch=` to read a branch's overlay instead of main — see the [branching guide](/docs/guides/branches). ## OpenAPI ````yaml /openapi/textsetu.json get /projects/{projectId}/keys openapi: 3.1.0 info: title: TextSetu API version: 1.2.0 description: >- Public REST API for TextSetu. Authenticate with a Personal Access Token (tsu_pat_…) or a project token (tsu_proj_…) via the `Authorization: Bearer ` header. **Authorization is permission-based.** Every token carries an explicit allow-list of RBAC permission keys (e.g. `translation_read`), and each endpoint declares the permission it requires (`x-permission`). A token's effective access is its underlying authority ∩ its allow-list — a PAT is further bounded by its owner's role-based permissions, so it can only narrow, never exceed, what the owner already has. A project token is bound to a single project. There are no coarse read/write/manage scopes. **Response envelope.** Every endpoint returns `{ "success": true, "data": … }` on success and `{ "success": false, "error": { "code", "message" } }` on failure. **Rate limit.** 600 requests/minute, keyed by token (or by IP when unauthenticated). Exceeding it returns 429 with the standard error envelope. servers: - url: https://api.textsetu.com/api/v1 description: Production - url: /api/v1 description: This server (self-hosted / same-origin) security: - bearerAuth: [] tags: - name: Projects description: >- Read project metadata — settings, key separator, and the approval/branching flags that shape how the other endpoints behave. - name: Languages description: >- List and manage a project's target languages. Each language is referenced by its BCP-47 code; the source language is flagged separately. - name: Translations description: >- Manage a project's translations: create, read, update, and delete translation keys — the identifiers your app looks up, carrying metadata (description, tags, screenshot) — and set the translated value for a key in a given language. Value writes honor the project's approval workflow — non-approver writes land as `pending_review`. - name: Stats description: >- Per-language completeness and approval progress for a project — the numbers behind the dashboard. - name: Import/Export description: >- Bulk-load source files into a project or export the current translations. Supports the same file formats as the web app. - name: Branches description: >- Work on translations in isolation and merge them back. Branch reads/writes mirror the main endpoints but stage changes as a diff until merge. See the [branching guide](/docs/guides/branches). - name: Glossary description: >- Manage term bases — approved terminology and its translations — and check a string against them. See the [glossary guide](/docs/guides/glossary). - name: Translation Memory description: >- Reusable translation stores. Fuzzy-match and concordance-search prior translations to reuse them. See the [translation memory guide](/docs/guides/translation-memory). - name: AI description: >- Machine-translate a project with the org's configured AI engine (brand voice, glossary/TM grounding, and an optional review pass). Runs asynchronously — start a run and poll the returned `jobId`. - name: Webhooks description: >- Get notified when a project's translations change, instead of polling. Register an HTTPS endpoint, subscribe it to the events you care about, and TextSetu POSTs a signed payload whenever one occurs. Payloads follow the [Standard Webhooks](https://www.standardwebhooks.com) spec — verify the `webhook-signature` header with any compatible library. Delivery is at-least-once and unordered, so treat `webhook-id` as an idempotency key. Failed deliveries are retried five times over roughly seven hours, and every attempt is inspectable and replayable via the delivery log. - name: Meta description: Service-level and cross-cutting endpoints. paths: /projects/{projectId}/keys: get: tags: - Translations summary: List / search keys (paginated) description: >- Return a paginated page of a project's translation keys, each with its values across every language. Combine the query params to search by name or source text, filter by tag / status / outdated, and sort. Pass `?branch=` to read a branch's overlay instead of main — see the [branching guide](/docs/guides/branches). parameters: - name: projectId in: path required: true schema: type: string description: Project id (UUID) or id-embedded path slug. - name: page in: query description: 1-based page number. schema: default: 1 type: integer minimum: 1 - name: limit in: query description: Page size (1–200). schema: default: 50 type: integer minimum: 1 maximum: 200 - name: search in: query description: Substring match on key name. schema: type: string - name: scope in: query description: Key-namespace prefix filter. schema: type: string - name: tags in: query description: Filter by one or more tags. schema: anyOf: - type: string - type: array items: type: string - name: language in: query description: Restrict value-based filters to this language. schema: type: string - name: sourceSearch in: query description: Substring match on the source-language value. schema: type: string - name: outdated in: query description: Only keys with at least one outdated value. schema: anyOf: - type: boolean - type: string enum: - 'true' - 'false' - name: status in: query description: Only keys with at least one value in this approval status. schema: type: string enum: - approved - pending_review - draft - name: sort in: query description: Field to sort by. schema: default: key type: string enum: - key - createdAt - updatedAt - name: order in: query description: Sort direction. schema: default: asc type: string enum: - asc - desc - name: branch in: query schema: type: string description: >- Target an open translation branch instead of main. Required when the project's main branch is protected. responses: '200': description: A page of keys with their per-language values. content: application/json: schema: type: object required: - success - data properties: success: type: boolean const: true data: type: object properties: keys: type: array items: type: object properties: id: type: string description: Unique key id (UUID). examples: - a1b2c3d4-0000-4000-8000-000000000001 projectId: type: string description: Id of the project this key belongs to. examples: - proj_9f8e7d6c key: type: string description: >- The lookup identifier your app resolves, e.g. `home.hero.title`. examples: - home.hero.title description: anyOf: - type: string - type: 'null' description: >- Optional note giving translators context for this key. examples: - Headline shown on the landing page hero. tags: type: array items: type: string description: >- Free-form labels for filtering and organizing keys. examples: - - marketing - landing isPlural: type: boolean description: >- True when the key holds CLDR plural forms rather than a single string. examples: - false screenshotUrl: anyOf: - type: string - type: 'null' description: >- Public URL of an attached screenshot showing the key in context, if any. examples: - null screenshotFileId: anyOf: - type: string - type: 'null' description: Storage id of the attached screenshot, if any. examples: - null keySource: type: string enum: - main - branch description: >- Whether the effective row comes from `main` or a branch overlay. examples: - main createdAt: type: string description: Creation timestamp (ISO 8601). examples: - '2026-01-15T09:24:00.000Z' updatedAt: type: string description: Last-update timestamp (ISO 8601). examples: - '2026-02-02T14:05:00.000Z' values: type: array items: type: object properties: languageCode: type: string description: >- BCP-47 language code this value is written in. examples: - fr value: type: string description: The translated string for this language. examples: - Bienvenue status: type: string description: >- Review state: `approved`, `pending_review`, or `draft`. Branch overrides are always `draft`. examples: - approved pluralForm: anyOf: - type: string - type: 'null' description: >- CLDR plural category (`one`, `other`, …) for plural keys on main; `null` for singular keys and all branch values. examples: - null isOutdated: type: boolean description: >- True when the source string changed after this value was last set. examples: - false required: - languageCode - value - status - pluralForm - isOutdated additionalProperties: false required: - id - projectId - key - description - tags - isPlural - screenshotUrl - screenshotFileId - keySource - createdAt - updatedAt - values additionalProperties: false total: type: integer page: type: integer limit: type: integer required: - keys - total - page - limit additionalProperties: false components: securitySchemes: bearerAuth: type: http scheme: bearer description: >- API token: tsu_pat_… (PAT) or tsu_proj_… (project token). The token's granted RBAC permissions determine access; see each operation's `x-permission`. ````