Knock Translations API

openapi: 3.0.3
info:
  title: Knock Audiences Accounts Translations API
  version: '1.0'
  description: Manage static Audiences and their members. Audiences power lifecycle messaging — when a user joins an audience, configured workflows fire automatically.
  contact:
    name: Knock
    url: https://knock.app
  license:
    name: Proprietary
servers:
- url: https://api.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'
                    nullable: false
                    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:
    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.
          nullable: true
          type: string
          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.
          nullable: true
          type: string
          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
    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
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: Knock API key as a Bearer token. Use a public key (pk_...) for client-side requests or a secret key (sk_...) for server-side.