openapi: 3.0.1
info:
  title: Localazy API
  description: >-
    REST API for the Localazy localization and translation management platform.
    Import and upload source content, export and download translated files, list
    files and their keys, read project languages, and manage projects. All
    endpoints are relative to https://api.localazy.com and authenticated with a
    Bearer token (project, translation, or organization token).
  termsOfService: https://localazy.com/terms
  contact:
    name: Localazy Support
    email: team@localazy.com
    url: https://localazy.com/docs/api/introduction
  version: '1.0'
servers:
  - url: https://api.localazy.com
security:
  - bearerAuth: []
tags:
  - name: Projects
    description: List and create projects, and read project languages.
  - name: Import
    description: Import and upload source and translation content.
  - name: Files
    description: List files and read file content as keys and translations.
  - name: Export
    description: Download translated files for a specific language.
paths:
  /projects:
    get:
      operationId: listProjects
      tags:
        - Projects
      summary: List projects
      description: >-
        Returns the projects accessible to the supplied token. A project token
        returns the single associated project; an organization token returns all
        organization projects.
      parameters:
        - name: organization
          in: query
          description: When true, includes information about the owning organization.
          required: false
          schema:
            type: boolean
        - name: languages
          in: query
          description: When true, includes the project languages and their translation statistics.
          required: false
          schema:
            type: boolean
      responses:
        '200':
          description: A list of projects.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Project'
        '401':
          description: Missing or invalid authentication token.
    post:
      operationId: createProject
      tags:
        - Projects
      summary: Create a project
      description: >-
        Creates a new project under an organization. Requires an organization
        token.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateProjectRequest'
      responses:
        '200':
          description: The newly created project.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateProjectResponse'
        '401':
          description: Missing or invalid authentication token.
  /projects/{projectId}/import:
    post:
      operationId: importContent
      tags:
        - Import
      summary: Import content to a project
      description: >-
        Imports and uploads source and translation strings into the project from
        one or more files in any supported format.
      parameters:
        - name: projectId
          in: path
          required: true
          description: The project identifier.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportRequest'
      responses:
        '200':
          description: The import was accepted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ImportResponse'
        '401':
          description: Missing or invalid authentication token.
        '429':
          description: Rate limit exceeded.
  /import/formats:
    get:
      operationId: listImportFormats
      tags:
        - Import
      summary: List available import file formats
      description: >-
        Returns the supported file types for importing strings, along with their
        capabilities (strings, plurals, arrays, and supported parameters).
      responses:
        '200':
          description: A list of supported import formats.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ImportFormat'
  /projects/{projectId}/files:
    get:
      operationId: listFiles
      tags:
        - Files
      summary: List files in a project
      description: Returns the set of files in the project.
      parameters:
        - name: projectId
          in: path
          required: true
          description: The project identifier.
          schema:
            type: string
      responses:
        '200':
          description: A list of files.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/File'
        '401':
          description: Missing or invalid authentication token.
  /projects/{projectId}/files/{fileId}/keys/{lang}:
    get:
      operationId: listFileKeys
      tags:
        - Files
      summary: List file content (keys)
      description: >-
        Returns the keys and translations for a file in a specific language, with
        cursor-based pagination.
      parameters:
        - name: projectId
          in: path
          required: true
          description: The project identifier.
          schema:
            type: string
        - name: fileId
          in: path
          required: true
          description: The file identifier.
          schema:
            type: string
        - name: lang
          in: path
          required: true
          description: The language in the form ll-Scrp-RR (for example en, cs, pt-BR).
          schema:
            type: string
        - name: deprecated
          in: query
          description: Include deprecated keys.
          schema:
            type: boolean
        - name: limit
          in: query
          description: Number of results per call (maximum 1000).
          schema:
            type: integer
            maximum: 1000
        - name: next
          in: query
          description: Pagination cursor returned by the previous call.
          schema:
            type: string
        - name: extra_info
          in: query
          description: Include additional metadata for each key.
          schema:
            type: boolean
        - name: no_content
          in: query
          description: Exclude translation content from the response.
          schema:
            type: boolean
        - name: unapproved
          in: query
          description: Include unapproved translations.
          schema:
            type: boolean
      responses:
        '200':
          description: The keys for the file and language.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/KeysResponse'
        '401':
          description: Missing or invalid authentication token.
  /projects/{projectId}/files/{fileId}/download/{lang}:
    get:
      operationId: downloadFile
      tags:
        - Export
      summary: Download (export) a file in a language
      description: >-
        Exports the translated file for the given language and returns the raw
        file contents with the appropriate content type.
      parameters:
        - name: projectId
          in: path
          required: true
          description: The project identifier.
          schema:
            type: string
        - name: fileId
          in: path
          required: true
          description: The file identifier.
          schema:
            type: string
        - name: lang
          in: path
          required: true
          description: The language to export (for example en, cs, pt-BR).
          schema:
            type: string
      responses:
        '200':
          description: The exported file contents.
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '401':
          description: Missing or invalid authentication token.
        '429':
          description: Rate limit exceeded.
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Authenticate with the header `Authorization: Bearer {token}`. Tokens may
        be a project token (read/write to one project), a translation token (AI
        translation only), or an organization token (organization scope, by
        request).
  schemas:
    Project:
      type: object
      properties:
        id:
          type: string
          description: Unique project identifier.
        orgId:
          type: string
          description: Organization identifier.
        name:
          type: string
        slug:
          type: string
        image:
          type: string
        url:
          type: string
        description:
          type: string
        type:
          type: string
          description: Project visibility - public, private, or restricted.
        tone:
          type: string
          description: Project tone - formal, informal, or not_specified.
        role:
          type: string
          description: Current user's role on the project.
        sourceLanguage:
          type: integer
          description: Source language identifier.
        organization:
          type: object
          description: Feature availability and key limits for the organization.
        languages:
          type: array
          description: Language objects with translation statistics (when languages=true).
          items:
            $ref: '#/components/schemas/Language'
    Language:
      type: object
      properties:
        id:
          type: integer
        code:
          type: string
          description: Language code (for example en, cs, pt-BR).
        name:
          type: string
        rtl:
          type: boolean
        progress:
          type: integer
          description: Translation completion percentage.
    CreateProjectRequest:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: Project name.
        slug:
          type: string
          description: Project slug; auto-generated if omitted.
        description:
          type: string
          default: ''
        sourceLanguage:
          type: string
          default: en
        type:
          type: string
          default: restricted
          description: public or restricted.
        tone:
          type: string
          default: not_specified
        useShareTM:
          type: boolean
          default: true
    CreateProjectResponse:
      type: object
      properties:
        projectId:
          type: string
          description: Identifier of the newly created project.
    ImportRequest:
      type: object
      properties:
        importAsNew:
          type: boolean
          default: false
          description: Import translations through the review process.
        forceCurrent:
          type: boolean
          default: false
          description: Set imported translations as the current version.
        filterSource:
          type: boolean
          default: true
          description: Skip translations matching the source language.
        forceSource:
          type: boolean
          default: false
          description: Overwrite the source language.
        files:
          type: array
          items:
            $ref: '#/components/schemas/ImportFile'
    ImportFile:
      type: object
      required:
        - name
      properties:
        name:
          type: string
          description: File name.
        path:
          type: string
          description: File path without the name.
        module:
          type: string
        buildType:
          type: string
        productFlavors:
          type: array
          items:
            type: string
        content:
          $ref: '#/components/schemas/ImportContent'
    ImportContent:
      type: object
      description: >-
        File content with language-specific strings. Includes format directives
        plus one entry per language code (for example en, fr, cs).
      properties:
        type:
          type: string
          default: api
          description: File format for publishing strings.
        plural:
          type: string
          description: Plural encoding type.
        array:
          type: string
          description: String-array encoding method.
        keyTransformer:
          type: string
          description: Key flattening approach.
        params:
          type: object
          description: Additional format parameters.
        features:
          type: array
          items:
            type: string
      additionalProperties: true
    ImportResponse:
      type: object
      properties:
        result:
          type: string
          description: Import result status.
    ImportFormat:
      type: object
      properties:
        id:
          type: string
          description: Format identifier (for example android, json).
        name:
          type: string
        supportsPlurals:
          type: boolean
        supportsArrays:
          type: boolean
        params:
          type: object
          description: Supported parameters for the format.
    File:
      type: object
      properties:
        id:
          type: string
          description: Unique file identifier.
        type:
          type: string
          description: File format type.
        name:
          type: string
        path:
          type: string
          description: Optional stored file path.
        module:
          type: string
        productFlavors:
          type: array
          items:
            type: string
        buildType:
          type: string
    KeysResponse:
      type: object
      properties:
        keys:
          type: array
          items:
            $ref: '#/components/schemas/Key'
        next:
          type: string
          description: Pagination cursor for the next page, present when more pages exist.
    Key:
      type: object
      properties:
        id:
          type: string
        key:
          type: array
          items:
            type: string
        value:
          type: string
          description: Translation value for the requested language.
        deprecated:
          type: boolean