Knock Translations API

openapi: 3.2.0
info:
  title: Knock Management API (mAPI) Translations API
  version: '1.0'
  description: Knock Management API (mAPI) — the resource-management surface for Knock. Programmatic CRUD over Workflows, Channels, Email Layouts, Partials, Templates, Translations, Audiences, Broadcasts, Guides, Message Types, Variables, Members, Channel Groups, Environments, Branches, Commits, and API Keys. Distinct from the runtime Knock API (api.knock.app) — mAPI lives at control.knock.app and is what powers the Knock CLI and MCP server.
  contact:
    name: Knock
    url: https://knock.app
servers:
- url: https://control.knock.app
  variables: {}
security:
- BearerAuth: []
tags:
- description: Translations are per-locale string files that can be used in your templates.
  name: Translations
paths:
  /v1/translations:
    get:
      callbacks: {}
      description: Returns a paginated list of translations available in a given environment. The translations are returned in alphabetical order by locale code.
      operationId: listTranslations
      parameters:
      - description: A specific locale code to filter translations for.
        in: query
        name: locale_code
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: A specific namespace to filter translations for.
        in: query
        name: namespace
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: A specific tenant to filter translations for.
        in: query
        name: tenant
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: Optionally specify the returned content format. Supports 'json' and 'po'. Defaults to 'json'.
        in: query
        name: format
        required: false
        schema:
          enum:
          - json
          - po
          type: string
          x-struct: null
          x-validate: null
      - description: The environment slug.
        in: query
        name: environment
        required: true
        schema:
          example: development
          type: string
          x-struct: null
          x-validate: null
      - description: The slug of a branch to use. This option can only be used when `environment` is `"development"`.
        in: query
        name: branch
        required: false
        schema:
          example: feature-branch
          type: string
          x-struct: null
          x-validate: null
      - description: Whether to annotate the resource. Only used in the Knock CLI.
        in: query
        name: annotate
        required: false
        schema:
          type: boolean
          x-struct: null
          x-validate: null
      - description: Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.
        in: query
        name: hide_uncommitted_changes
        required: false
        schema:
          type: boolean
          x-struct: null
          x-validate: null
      - description: The cursor to fetch entries after.
        in: query
        name: after
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The cursor to fetch entries before.
        in: query
        name: before
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The number of entries to fetch per-page.
        in: query
        name: limit
        required: false
        schema:
          type: integer
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                description: A paginated list of Translation. Contains a list of entries and page information.
                example:
                  entries:
                  - content: '{"hello":"Hello, world!"}'
                    format: json
                    inserted_at: '2021-01-01T00:00:00Z'
                    locale_code: en
                    namespace: my_app
                    updated_at: '2021-01-01T00:00:00Z'
                  page_info:
                    after: null
                    before: null
                    page_size: 25
                properties:
                  entries:
                    description: A list of entries.
                    items:
                      $ref: '#/components/schemas/Translation'
                    type: array
                    x-struct: null
                    x-validate: null
                  page_info:
                    $ref: '#/components/schemas/PageInfo'
                required:
                - entries
                - page_info
                title: PaginatedTranslationResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: List translations
      tags:
      - Translations
  /v1/translations/{locale_code}/validate:
    put:
      callbacks: {}
      description: 'Validates a translation payload without persisting it.


        Note: this endpoint only operates on translations in the "development" environment.'
      operationId: validateTranslation
      parameters:
      - description: The translation's locale code.
        in: path
        name: locale_code
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The environment slug.
        in: query
        name: environment
        required: true
        schema:
          example: development
          type: string
          x-struct: null
          x-validate: null
      - description: The slug of a branch to use. This option can only be used when `environment` is `"development"`.
        in: query
        name: branch
        required: false
        schema:
          example: feature-branch
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            schema:
              description: Wraps the TranslationRequest request under the translation key.
              example:
                translation:
                  content: '{"hello":"Hello, world!"}'
                  format: json
              properties:
                translation:
                  $ref: '#/components/schemas/TranslationRequest'
              required:
              - translation
              title: WrappedTranslationRequestRequest
              type: object
              x-struct: null
              x-validate: null
        description: Params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Wraps the Translation response under the `translation` key.
                example:
                  translation:
                    content: '{"hello":"Hello, world!"}'
                    format: json
                    inserted_at: '2021-01-01T00:00:00Z'
                    locale_code: en
                    namespace: my_app
                    updated_at: '2021-01-01T00:00:00Z'
                properties:
                  translation:
                    $ref: '#/components/schemas/Translation'
                required:
                - translation
                title: WrappedTranslationResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: Validate translation
      tags:
      - Translations
  /v1/translations/{locale_code}:
    get:
      callbacks: {}
      description: Retrieve a translation by its locale and namespace, in a given environment.
      operationId: getTranslation
      parameters:
      - description: A specific locale code to filter translations for.
        in: path
        name: locale_code
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The environment slug.
        in: query
        name: environment
        required: true
        schema:
          example: development
          type: string
          x-struct: null
          x-validate: null
      - description: The slug of a branch to use. This option can only be used when `environment` is `"development"`.
        in: query
        name: branch
        required: false
        schema:
          example: feature-branch
          type: string
          x-struct: null
          x-validate: null
      - description: Optionally specify the returned content format. Supports 'json' and 'po'. Defaults to 'json'.
        in: query
        name: format
        required: false
        schema:
          enum:
          - json
          - po
          type: string
          x-struct: null
          x-validate: null
      - description: A specific namespace to filter translations for.
        in: query
        name: namespace
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: A specific tenant to scope the translation to.
        in: query
        name: tenant
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: Whether to annotate the resource. Only used in the Knock CLI.
        in: query
        name: annotate
        required: false
        schema:
          type: boolean
          x-struct: null
          x-validate: null
      - description: Whether to hide uncommitted changes. When true, only committed changes will be returned. When false, both committed and uncommitted changes will be returned.
        in: query
        name: hide_uncommitted_changes
        required: false
        schema:
          type: boolean
          x-struct: null
          x-validate: null
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Wraps the Translation response under the `translation` key.
                example:
                  translation:
                    content: '{"hello":"Hello, world!"}'
                    format: json
                    inserted_at: '2021-01-01T00:00:00Z'
                    locale_code: en
                    namespace: my_app
                    updated_at: '2021-01-01T00:00:00Z'
                properties:
                  translation:
                    $ref: '#/components/schemas/Translation'
                required:
                - translation
                title: WrappedTranslationResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: Get translation
      tags:
      - Translations
    put:
      callbacks: {}
      description: 'Updates a translation of a given locale code + namespace, or creates a new one if it does not yet exist.


        Note: this endpoint only operates on translations in the "development" environment.'
      operationId: upsertTranslation
      parameters:
      - description: A locale code of the translation.
        in: path
        name: locale_code
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: The environment slug.
        in: query
        name: environment
        required: true
        schema:
          example: development
          type: string
          x-struct: null
          x-validate: null
      - description: The slug of a branch to use. This option can only be used when `environment` is `"development"`.
        in: query
        name: branch
        required: false
        schema:
          example: feature-branch
          type: string
          x-struct: null
          x-validate: null
      - description: An optional namespace that identifies the translation.
        in: query
        name: namespace
        required: true
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: An optional tenant to scope the translation to.
        in: query
        name: tenant
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      - description: Optionally specify the returned content format. Supports 'json' and 'po'. Defaults to 'json'.
        in: query
        name: format
        required: false
        schema:
          enum:
          - json
          - po
          type: string
          x-struct: null
          x-validate: null
      - description: Whether to annotate the resource. Only used in the Knock CLI.
        in: query
        name: annotate
        required: false
        schema:
          type: boolean
          x-struct: null
          x-validate: null
      - description: When set to true, forces the upsert to override existing content regardless of environment restrictions. This bypasses the development-only environment check and origin environment checks.
        in: query
        name: force
        required: false
        schema:
          type: boolean
          x-struct: null
          x-validate: null
      - description: Whether to commit the resource at the same time as modifying it.
        in: query
        name: commit
        required: false
        schema:
          type: boolean
          x-struct: null
          x-validate: null
      - description: The message to commit the resource with, only used if `commit` is `true`.
        in: query
        name: commit_message
        required: false
        schema:
          type: string
          x-struct: null
          x-validate: null
      requestBody:
        content:
          application/json:
            schema:
              description: Wraps the TranslationRequest request under the translation key.
              example:
                translation:
                  content: '{"hello":"Hello, world!"}'
                  format: json
              properties:
                translation:
                  $ref: '#/components/schemas/TranslationRequest'
              required:
              - translation
              title: WrappedTranslationRequestRequest
              type: object
              x-struct: null
              x-validate: null
        description: Params
        required: false
      responses:
        '200':
          content:
            application/json:
              schema:
                description: Wraps the Translation response under the `translation` key.
                example:
                  translation:
                    content: '{"hello":"Hello, world!"}'
                    format: json
                    inserted_at: '2021-01-01T00:00:00Z'
                    locale_code: en
                    namespace: my_app
                    updated_at: '2021-01-01T00:00:00Z'
                properties:
                  translation:
                    $ref: '#/components/schemas/Translation'
                required:
                - translation
                title: WrappedTranslationResponse
                type: object
                x-struct: null
                x-validate: null
          description: OK
      summary: Upsert translation
      tags:
      - Translations
components:
  schemas:
    Translation:
      description: A translation object.
      example:
        content: '{"hello":"Hello, world!"}'
        format: json
        inserted_at: '2021-01-01T00:00:00Z'
        locale_code: en
        namespace: my_app
        updated_at: '2021-01-01T00:00:00Z'
      properties:
        content:
          description: A JSON encoded string containing the key-value pairs of translation references and translation strings.
          type: string
          x-struct: null
          x-validate: null
        format:
          description: Indicates whether content is a JSON encoded object string or a string in the PO format.
          enum:
          - json
          - po
          type: string
          x-struct: null
          x-validate: null
        inserted_at:
          description: The timestamp of when the translation was created.
          format: date-time
          type: string
          x-struct: null
          x-validate: null
        locale_code:
          description: The locale code for the translation object.
          type: string
          x-struct: null
          x-validate: null
        namespace:
          description: An optional namespace for the translation to help categorize your translations.
          type: string
          x-struct: null
          x-validate: null
        tenant:
          description: An optional tenant identifier to scope the translation to a specific tenant.
          type: string
          x-struct: null
          x-validate: null
        updated_at:
          description: The timestamp of when the translation was last updated.
          format: date-time
          type: string
          x-struct: null
          x-validate: null
      required:
      - locale_code
      - namespace
      - content
      - format
      - inserted_at
      - updated_at
      title: Translation
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.Translation
      x-validate: null
    TranslationRequest:
      description: A translation object with a content attribute used to update or create a translation.
      example:
        content: '{"hello":"Hello, world!"}'
        format: json
      properties:
        content:
          description: A JSON encoded string containing the key-value pairs of translation references and translation strings.
          type: string
          x-struct: null
          x-validate: null
        format:
          description: Indicates whether content is a JSON encoded object string or a string in the PO format.
          enum:
          - json
          - po
          example: json
          type: string
          x-struct: null
          x-validate: null
      required:
      - content
      - format
      title: TranslationRequest
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.TranslationRequest
      x-validate: null
    PageInfo:
      description: The information about a paginated result.
      example:
        after: null
        before: null
        page_size: 25
      properties:
        after:
          description: The cursor to fetch entries after. Will only be present if there are more entries to fetch.
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        before:
          description: The cursor to fetch entries before. Will only be present if there are more entries to fetch before the current page.
          type:
          - string
          - 'null'
          x-struct: null
          x-validate: null
        page_size:
          description: The number of entries to fetch per-page.
          type: integer
          x-struct: null
          x-validate: null
      required:
      - page_size
      title: PageInfo
      type: object
      x-struct: Elixir.ControlWeb.V1.Specs.PageInfo
      x-validate: null
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Knock service token (kst_...) as a Bearer token.