openapi: 3.1.1
info:
  title: SuprSend Broadcast Translation API
  description: APIs supported on suprsend platform
  version: 1.2.2
servers:
- url: https://hub.suprsend.com
security:
- sec0: []
- BearerAuth: []
tags:
- name: Translation
paths:
  /v1/{workspace}/translation/:
    get:
      summary: List Translations
      description: Retrieve a list of translation files in a workspace. By default, returns draft translations. Use the mode query parameter to filter by draft or live translations.
      operationId: list-translations
      servers:
      - url: https://management-api.suprsend.com
      security:
      - ServiceTokenAuth: []
      x-codeSamples:
      - lang: cURL
        label: List Translations
        source: "curl -X GET \"https://management-api.suprsend.com/v1/{workspace}/translation/\" \\\n  --header 'Authorization: ServiceToken <token>' \n"
      parameters:
      - in: path
        name: workspace
        required: true
        schema:
          type: string
        description: Workspace slug (staging, production, etc.)
      - in: query
        name: mode
        schema:
          type: string
          enum:
          - draft
          - live
          default: draft
        description: Mode to filter translations (draft or live). By default, draft translations are returned.
      - in: query
        name: limit
        schema:
          type: integer
          description: Maximum number of results per page
          example: 10
        description: Maximum number of results per page
      - in: query
        name: offset
        schema:
          type: integer
          example: 0
        description: Number of results to skip
      responses:
        '200':
          description: Successfully retrieved list of translations
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      count:
                        type: integer
                        description: Total number of translation files
                      limit:
                        type: integer
                        description: Maximum number of results per page
                      offset:
                        type: integer
                        description: Number of results to skip in case offset is passed in the request
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        filename:
                          type: string
                          description: Name of the translation file. Should be in the format of <locale>.json or <namespace>.<locale>.json.
                          example: en.json
                        locale:
                          type: string
                          description: Locale code for the translation file. This would be matched with user locale code to fetch translation.
                          example: en
                        locale_name:
                          type: string
                          description: Human-readable name of the locale
                          example: English
                        namespace:
                          type: string
                          nullable: true
                          description: Namespace for the translation file, if any. Namespace can be used to group translations by feature or module.
                          example: task
                        action:
                          type: string
                          description: action done in the version compared to last commit.
                          enum:
                          - added
                          - updated
                          - deleted
                          - unchanged
                          example: added
                        updated_at:
                          type: string
                          format: date-time
                          description: When the translation file was last updated
              example:
                meta:
                  count: 2
                  limit: 10
                  offset: 0
                results:
                - filename: en.json
                  locale: en
                  locale_name: English
                  namespace: null
                  action: unchanged
                  updated_at: '2025-10-30T12:23:50.380614Z'
                - filename: fr.json
                  locale: fr
                  locale_name: French
                  namespace: null
                  action: added
                  updated_at: '2025-10-28T07:59:43.397124Z'
        '401':
          $ref: '#/components/responses/AuthenticationError'
          description: AuthenticationFailed - Invalid service token.
        '404':
          $ref: '#/components/responses/NotFoundError'
          description: Workspace not found
      tags:
      - Translation
  /v1/{workspace}/translation/content/{locale_file}/:
    post:
      summary: Add Translation
      description: Upload or create a new translation file. The file content should be valid JSON following the translation file structure.
      operationId: add-translation
      servers:
      - url: https://management-api.suprsend.com
      security:
      - ServiceTokenAuth: []
      x-codeSamples:
      - lang: cURL
        label: Add Translation
        source: "curl -X POST \"https://management-api.suprsend.com/v1/{workspace}/translation/content/{locale_file}/\" \\\n  --header 'Authorization: ServiceToken <token>' \\\n  --header 'Content-Type: application/json' \\\n  --data '{\n    \"content\": {\n      \"welcome\": \"Bienvenue\",\n      \"goodbye\": \"Au revoir\"\n    }\n  }'\n"
      parameters:
      - in: path
        name: workspace
        required: true
        schema:
          type: string
        description: Workspace slug (staging, production, etc.)
      - in: path
        name: locale_file
        required: true
        schema:
          type: string
        description: Locale file name (e.g., "fr.json", "es-MX.json", "auth.en.json")
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - locale
              - content
              properties:
                locale:
                  type: string
                  description: Locale file name (e.g., "fr.json", "es-MX.json", "auth.en.json")
                  example: fr.json
                content:
                  type: object
                  description: Translation key-value pairs in JSON format
                  additionalProperties: true
            example:
              locale: fr.json
              content:
                welcome: Bienvenue
                goodbye: Au revoir
                greeting: Bonjour, {{name}}!
      responses:
        '201':
          description: Translation file successfully updated
          content:
            application/json:
              schema:
                type: object
                properties:
                  filename:
                    type: string
                    description: Name of the translation file
                    example: fr.json
                  locale:
                    type: string
                    description: Locale code for the translation file
                    example: fr
                  locale_name:
                    type: string
                    description: Human-readable name of the locale
                    example: French
                  namespace:
                    type: string
                    nullable: true
                    description: Namespace for the translation file, if any. Namespace can be used to group translations by feature or module.
                    example: null
                  action:
                    type: string
                    description: action done in the version compared to last commit.
                    enum:
                    - added
                    - updated
                    - deleted
                    - unchanged
                    example: updated
                  updated_at:
                    type: string
                    format: date-time
                    description: When the translation file was last updated
                  content:
                    type: object
                    description: Translation key-value pairs
                    additionalProperties:
                      type: string
              example:
                filename: fr.json
                locale: fr
                locale_name: French
                namespace: null
                action: updated
                updated_at: '2025-10-29T17:14:33.048313Z'
                content:
                  task_created: Tâche créée
                  task_completed: Tâche terminée
                  task_due: Tâche due
                  task_assigned: Tâche assignée
        '400':
          description: Invalid translation format
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: integer
                    example: 400
                  error_code:
                    type: string
                    example: validation_error
                  type:
                    type: string
                    example: ValidationError
                  message:
                    type: string
                    example: Invalid JSON format
        '401':
          $ref: '#/components/responses/AuthenticationError'
          description: AuthenticationFailed - Invalid service token.
        '404':
          $ref: '#/components/responses/NotFoundError'
          description: Workspace not found
      tags:
      - Translation
    get:
      summary: Get Translation
      description: Retrieve the content of a translation file for a specific locale file.
      operationId: get-translation
      servers:
      - url: https://management-api.suprsend.com
      security:
      - ServiceTokenAuth: []
      x-codeSamples:
      - lang: cURL
        label: Get Translation
        source: "curl -X GET \"https://management-api.suprsend.com/v1/{workspace}/translation/content/fr.json/\" \\\n  --header 'Authorization: ServiceToken <token>'\n"
      parameters:
      - in: path
        name: workspace
        required: true
        schema:
          type: string
          description: Workspace slug (staging, production, etc.)
      - in: path
        name: locale_file
        required: true
        schema:
          type: string
          description: Locale file name (e.g., "fr.json", "es-MX.json", "auth.en.json")
      - in: query
        name: mode
        schema:
          type: string
          enum:
          - draft
          - live
          default: draft
          description: Mode to fetch translation (draft or live). By default, draft translation is returned.
      responses:
        '200':
          description: Successfully retrieved translation content
          content:
            application/json:
              schema:
                type: object
                properties:
                  filename:
                    type: string
                    description: Name of the translation file
                    example: fr.json
                  locale:
                    type: string
                    description: Locale code for the translation file
                    example: fr
                  locale_name:
                    type: string
                    description: Human-readable name of the locale
                    example: French
                  namespace:
                    type: string
                    nullable: true
                    description: Namespace for the translation file, if any
                    example: null
                  action:
                    type: string
                    description: action done in the version compared to last commit.
                    enum:
                    - added
                    - updated
                    - deleted
                    - unchanged
                    example: updated
                  updated_at:
                    type: string
                    format: date-time
                    description: When the translation file was last updated
                  content:
                    type: object
                    description: Translation key-value pairs
                    additionalProperties:
                      type: string
              example:
                filename: fr.json
                locale: fr
                locale_name: French
                namespace: null
                action: updated
                updated_at: '2025-10-29T17:14:33.048313Z'
                content:
                  task_created: Tâche créée
                  task_completed: Tâche terminée
                  task_due: Tâche due
                  task_assigned: Tâche assignée
        '401':
          $ref: '#/components/responses/AuthenticationError'
          description: AuthenticationFailed - Invalid service token.
        '404':
          $ref: '#/components/responses/NotFoundError'
          description: Translation file or workspace not found
      tags:
      - Translation
    delete:
      summary: Delete Translation
      description: Marks a file for deletion in the next commit. Actual deletion will happen when you commit the draft.
      operationId: delete-translation
      servers:
      - url: https://management-api.suprsend.com
      security:
      - ServiceTokenAuth: []
      x-codeSamples:
      - lang: cURL
        label: Delete Translation
        source: "curl -X DELETE \"https://management-api.suprsend.com/v1/{workspace}/translation/content/{locale_file}/\" \\\n  --header 'Authorization: ServiceToken <token>' \n"
      parameters:
      - in: path
        name: workspace
        required: true
        schema:
          type: string
        description: Workspace slug (staging, production, etc.)
      - in: path
        name: locale_file
        required: true
        schema:
          type: string
        description: Locale file name (e.g., "fr.json", "es-MX.json", "auth.en.json")
        example: fr.json
      responses:
        '204':
          description: Translation file deleted successfully
        '401':
          $ref: '#/components/responses/AuthenticationError'
          description: AuthenticationFailed - Invalid service token.
        '404':
          $ref: '#/components/responses/NotFoundError'
          description: Translation file or workspace not found
      tags:
      - Translation
  /v1/{workspace}/translation/version/{version}/:
    get:
      summary: Get Translation History
      description: Retrieve version history information for translations, including all versions and their details.
      operationId: get-translation-history
      servers:
      - url: https://management-api.suprsend.com
      security:
      - ServiceTokenAuth: []
      x-codeSamples:
      - lang: cURL
        label: Get Translation History
        source: "curl -X GET \"https://management-api.suprsend.com/v1/{workspace}/translation/version/{version_no}/\" \\\n  --header 'Authorization: ServiceToken <token>' \n"
      parameters:
      - in: path
        name: workspace
        required: true
        schema:
          type: string
        description: Workspace slug (staging, production, etc.)
      - in: path
        name: version
        required: true
        schema:
          type: integer
        description: Version number to retrieve
        example: 1
      responses:
        '200':
          description: Successfully retrieved translation version history
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      count:
                        type: integer
                        description: Total number of translation files
                      limit:
                        type: integer
                        description: Maximum number of results per page
                      offset:
                        type: integer
                        description: Number of results to skip in case offset is passed in the request
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        filename:
                          type: string
                          description: Name of the translation file. Should be in the format of <locale>.json or <namespace>.<locale>.json.
                          example: en.json
                        locale:
                          type: string
                          description: Locale code for the translation file. This would be matched with user locale code to fetch translation.
                          example: en
                        locale_name:
                          type: string
                          description: Human-readable name of the locale
                          example: English
                        namespace:
                          type: string
                          nullable: true
                          description: Namespace for the translation file, if any. Namespace can be used to group translations by feature or module.
                          example: task
                        action:
                          type: string
                          description: action done in the version compared to last commit.
                          enum:
                          - added
                          - updated
                          - deleted
                          - unchanged
                          example: added
                        updated_at:
                          type: string
                          format: date-time
                          description: When the translation file was last updated
              example:
                meta:
                  count: 2
                  limit: 10
                  offset: 0
                results:
                - filename: en.json
                  locale: en
                  locale_name: English
                  namespace: null
                  action: unchanged
                  updated_at: '2025-10-30T12:23:50.380614Z'
                - filename: fr.json
                  locale: fr
                  locale_name: French
                  namespace: null
                  action: added
                  updated_at: '2025-10-28T07:59:43.397124Z'
        '401':
          $ref: '#/components/responses/AuthenticationError'
          description: AuthenticationFailed - Invalid service token.
        '404':
          $ref: '#/components/responses/NotFoundError'
          description: Version or workspace not found
      tags:
      - Translation
  /v1/{workspace}/translation/version/{version_no}/rollback/:
    post:
      summary: Rollback Translation
      description: Rollback translations to a previous version. This will replace all files with what was available at the previous version.
      operationId: rollback-translation
      servers:
      - url: https://management-api.suprsend.com
      security:
      - ServiceTokenAuth: []
      x-codeSamples:
      - lang: cURL
        label: Rollback Translation
        source: "curl -X POST \"https://stagingapi.suprsend.com/v1/{workspace}/translation/version/{version_no}/rollback/\" \\\n  --header 'Authorization: ServiceToken <token>'\n"
      parameters:
      - in: path
        name: workspace
        required: true
        schema:
          type: string
        description: Workspace slug (staging, production, etc.)
      - in: path
        name: version_no
        required: true
        schema:
          type: integer
        description: Version number to rollback to
        example: 1
      responses:
        '200':
          description: Details of available translation files after rollback.
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      count:
                        type: integer
                        description: Total number of translation files
                      limit:
                        type: integer
                        description: Maximum number of results per page
                      offset:
                        type: integer
                        description: Number of results to skip in case offset is passed in the request
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        filename:
                          type: string
                          description: Name of the translation file. Should be in the format of <locale>.json or <namespace>.<locale>.json.
                          example: en.json
                        locale:
                          type: string
                          description: Locale code for the translation file. This would be matched with user locale code to fetch translation.
                          example: en
                        locale_name:
                          type: string
                          description: Human-readable name of the locale
                          example: English
                        namespace:
                          type: string
                          nullable: true
                          description: Namespace for the translation file, if any. Namespace can be used to group translations by feature or module.
                          example: task
                        action:
                          type: string
                          description: action done in the version compared to last commit.
                          enum:
                          - added
                          - updated
                          - deleted
                          - unchanged
                          example: added
                        updated_at:
                          type: string
                          format: date-time
                          description: When the translation file was last updated
              example:
                meta:
                  count: 2
                  limit: 10
                  offset: 0
                results:
                - filename: en.json
                  locale: en
                  locale_name: English
                  namespace: null
                  action: unchanged
                  updated_at: '2025-10-30T12:23:50.380614Z'
                - filename: fr.json
                  locale: fr
                  locale_name: French
                  namespace: null
                  action: added
                  updated_at: '2025-10-28T07:59:43.397124Z'
        '401':
          $ref: '#/components/responses/AuthenticationError'
          description: AuthenticationFailed - Invalid service token.
        '404':
          $ref: '#/components/responses/NotFoundError'
          description: Version or workspace not found
      tags:
      - Translation
  /v1/{workspace}/translation/commit/:
    patch:
      summary: Commit Translation
      description: Commit all files changes to make them live.
      operationId: commit-translation
      servers:
      - url: https://management-api.suprsend.com
      security:
      - ServiceTokenAuth: []
      x-codeSamples:
      - lang: cURL
        label: Commit Translation
        source: "curl -X PATCH \"https://management-api.suprsend.com/v1/{workspace}/translation/commit/\" \\\n  --header 'Authorization: ServiceToken <token>'\n"
      parameters:
      - in: path
        name: workspace
        required: true
        schema:
          type: string
        description: Workspace slug (staging, production, etc.)
      - in: query
        name: commit_message
        required: false
        schema:
          type: string
        description: Commit message describing the changes
      responses:
        '202':
          description: Translations committed successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  meta:
                    type: object
                    properties:
                      count:
                        type: integer
                        description: Total number of translation files
                      limit:
                        type: integer
                        description: Maximum number of results per page
                      offset:
                        type: integer
                        description: Number of results to skip in case offset is passed in the request
                  results:
                    type: array
                    items:
                      type: object
                      properties:
                        filename:
                          type: string
                          description: Name of the translation file. Should be in the format of <locale>.json or <namespace>.<locale>.json.
                          example: en.json
                        locale:
                          type: string
                          description: Locale code for the translation file. This would be matched with user locale code to fetch translation.
                          example: en
                        locale_name:
                          type: string
                          description: Human-readable name of the locale
                          example: English
                        namespace:
                          type: string
                          nullable: true
                          description: Namespace for the translation file, if any. Namespace can be used to group translations by feature or module.
                          example: task
                        action:
                          type: string
                          description: action done in the version compared to last commit.
                          enum:
                          - added
                          - updated
                          - deleted
                          - unchanged
                          example: added
                        updated_at:
                          type: string
                          format: date-time
                          description: When the translation file was last updated
              example:
                meta:
                  count: 2
                  limit: 10
                  offset: 0
                results:
                - filename: en.json
                  locale: en
                  locale_name: English
                  namespace: null
                  action: unchanged
                  updated_at: '2025-10-30T12:23:50.380614Z'
                - filename: fr.json
                  locale: fr
                  locale_name: French
                  namespace: null
                  action: added
                  updated_at: '2025-10-28T07:59:43.397124Z'
        '401':
          $ref: '#/components/responses/AuthenticationError'
          description: AuthenticationFailed - Invalid service token.
        '404':
          $ref: '#/components/responses/NotFoundError'
          description: Workspace not found
      tags:
      - Translation
components:
  responses:
    NotFoundError:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 404
            error_code: not_found
            type: NotFound
            message: workspace 'demo' not found
            detail: workspace 'demo' not found
    AuthenticationError:
      description: Authentication failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            code: 401
            error_code: authentication_failed
            type: AuthenticationFailed
            message: Invalid service token.
            detail: Invalid service token.
  schemas:
    ErrorResponse:
      type: object
      properties:
        code:
          type: integer
          description: HTTP status code
        error_code:
          type: string
          description: Specific error code identifier
        type:
          type: string
          description: Error type classification
        message:
          type: string
          description: Human-readable error message
        detail:
          type: string
          description: Additional error details
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API_Key
      description: Pass as `Bearer <API_KEY>`. Get API Key from SuprSend dashboard Developers -> API Keys section.
    ServiceTokenAuth:
      type: apiKey
      in: header
      name: ServiceToken <token>
      description: You can get Service Token from [SuprSend dashboard -> Account Settings -> Service Tokens](https://app.suprsend.com/en/account-settings/service-tokens) section.
    sec0:
      type: apiKey
      in: header
      name: Authorization
      x-bearer-format: bearer
      description: Bearer authentication header of the form `Bearer <token>`, where <token> is your auth token.
x-readme:
  headers: []
  explorer-enabled: true
  proxy-enabled: true
x-readme-fauxas: true