main.yaml

openapi: 3.0.3

info:
  title: Phrase Strings API Reference
  version: 2.0.0
  description: Phrase Strings is a translation management platform for software projects. You can collaborate on language file translation with your team or order translations through our platform. The API allows you to import locale files, download locale files, tag keys or interact in other ways with the localization data stored in Phrase Strings for your account.

  contact:
    name: Phrase Support
    url: https://developers.phrase.com/api/
    email: support@phrase.com

  x-logo:
    url: "https://developers.phrase.com/images/phrase-logo.svg"
    backgroundColor: "#03eab3"
    altText: "Phrase Strings"

  termsOfService: "https://phrase.com/terms/"

  license:
    name: MIT
    url: https://choosealicense.com/licenses/mit/

servers:
  - url: https://api.phrase.com/v2
    description: EU production server
  - url: https://api.us.app.phrase.com/v2
    description: US production server

security:
  - Token: []
  - Basic: []

tags:
  - name: Accounts
  - name: Authorizations
    description: |
      The endpoints provided by the Authorizations API are **only accessible via Basic authentication with email and password**.

      When creating a new authorization, the new access token for this authorization will be returned in the immediate response but not later, due to security reasons. When accessing authorizations later, you will only see the last eight chars of the token in plain text (`token_last_eight`) and the SHA256 digest of the token for reference (`hashed_token`).

      For instructions on how authorization in general works, see our [Auth Guide](#overview--authentication).

      ### Scopes

      When creating or updating an OAuth authorization, you can define a list of scopes to limit the access that can be performed by that authorization.

      #### Available Scopes

      <div class="table-responsive">
        <table class="basic-table">
          <thead>
            <tr class="basic-table__row basic-table__row--header">
              <th class="basic-table__cell basic-table__cell--header">Scope</th>
              <th class="basic-table__cell basic-table__cell--header">Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td class="basic-table__cell"><code>read</code></td>
              <td class="basic-table__cell">Read projects, locales, keys, translations, orders</td>
            </tr>
            <tr>
              <td class="basic-table__cell"><code>write</code></td>
              <td class="basic-table__cell">Write projects, locales, keys, translations but not orders</td>
            </tr>
            <tr>
              <td class="basic-table__cell"><code>orders.create</code></td>
              <td class="basic-table__cell">Create and confirm orders</td>
            </tr>
            <tr>
              <td class="basic-table__cell"><code>team.manage</code></td>
              <td class="basic-table__cell">Manage invitations and members</td>
            </tr>
          </tbody>
        </table>
      </div>
  - name: Automation Events
  - name: Blacklisted Keys
  - name: Branches
    description: |
      ### Branch creation

      Branches will be created asynchronously. State of branch creation is returned as state.

      #### Available States

      <div class="table-responsive">
        <table class="basic-table">
          <thead>
            <tr class="basic-table__row basic-table__row--header">
              <th class="basic-table__cell basic-table__cell--header">State</th>
              <th class="basic-table__cell basic-table__cell--header">Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td class="basic-table__cell"><code>initialized</code></td>
              <td class="basic-table__cell">Data received.</td>
            </tr>
            <tr>
              <td class="basic-table__cell"><code>processing</code></td>
              <td class="basic-table__cell">Branch is currently creating.</td>
            </tr>
            <tr>
              <td class="basic-table__cell"><code>success</code></td>
              <td class="basic-table__cell">Branch was created successfully</td>
            </tr>
            <tr>
              <td class="basic-table__cell"><code>error</code></td>
              <td class="basic-table__cell">Branch creation failed.</td>
            </tr>
          </tbody>
        </table>
      </div>
  - name: Checks
    description: |
      **Note:** The Checks API is still in development and might change in subsequent releases.

      The Checks API lets you list the check issues detected in a project and dismiss issues that should no longer appear on the list of active check issues.

      #### Available States

      <div class="table-responsive">
        <table class="basic-table">
          <thead>
            <tr class="basic-table__row basic-table__row--header">
              <th class="basic-table__cell basic-table__cell--header">State</th>
              <th class="basic-table__cell basic-table__cell--header">Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td class="basic-table__cell"><code>active</code></td>
              <td class="basic-table__cell">The issue is unresolved and not dismissed.</td>
            </tr>
            <tr>
              <td class="basic-table__cell"><code>solved</code></td>
              <td class="basic-table__cell">The issue has been resolved.</td>
            </tr>
            <tr>
              <td class="basic-table__cell"><code>dismissed</code></td>
              <td class="basic-table__cell">The issue has been dismissed by a user.</td>
            </tr>
          </tbody>
        </table>
      </div>
  - name: Comments
  - name: Comment Reactions
  - name: Comment Replies
  - name: Custom Metadata
  - name: Distributions
  - name: Documents
  - name: Figma Attachments
  - name: Formats
  - name: Glossaries
  - name: Glossary Terms
  - name: Glossary Term Translations
  - name: ICU
  - name: Invitations
    description: |
      With the invitation endpoint you can [manage and invite users](https://support.phrase.com/hc/en-us/articles/5709742418716) to Phrase Strings via API. A user can have the role Manager, Developer or Translator each with its own access rights. Developers and translators need resources like projects and locales assigned in order to access them.
  - name: Job Annotations
    description: |
      The job annotations endpoints allow you to create, update and delete annotations for jobs and job locales. Annotations are used to add metadata to a job or job locale.
  - name: Job Comments
  - name: Job Locales
  - name: Job Template Locales
  - name: Job Templates
  - name: Jobs
  - name: Key Format Annotations
  - name: Keys
  - name: Linked Keys
  - name: Locales
  - name: Locale Downloads
  - name: Machine Translation
  - name: Members
    description: |
      With the members endpoints you can do basic [team and user management](https://support.phrase.com/hc/en-us/articles/5709742418716) via API. A user can have the role Manager, Developer or Translator each with its own access rights. Developers and translators need resources like projects and locales assigned in order to access them.
  - name: Notifications
  - name: Notification Groups
  - name: Orders
    description: |
      ### List of categories [TextMaster]

      When ordering translations from TextMaster, you need to specify a category ID along with your order. See this list for information on the category ID and their equivalent description.

      <div class="table-responsive">
        <table class="basic-table">
          <thead>
            <tr class="basic-table__row basic-table__row--header">
              <th class="basic-table__cell basic-table__cell--header">Category ID</th>
              <th class="basic-table__cell basic-table__cell--header">Description</th>
            </tr>
          </thead>
          <tbody>
            <tr><td class="basic-table__cell">C001</td><td class="basic-table__cell">Agriculture</td></tr>
            <tr><td class="basic-table__cell">C002</td><td class="basic-table__cell">Aerospace</td></tr>
            <tr><td class="basic-table__cell">C003</td><td class="basic-table__cell">Animals/Pets/Plants</td></tr>
            <tr><td class="basic-table__cell">C004</td><td class="basic-table__cell">Arts/Culture/Literature</td></tr>
            <tr><td class="basic-table__cell">C005</td><td class="basic-table__cell">Automotive/Transportation</td></tr>
            <tr><td class="basic-table__cell">C006</td><td class="basic-table__cell">Computers/Technology/Software</td></tr>
            <tr><td class="basic-table__cell">C007</td><td class="basic-table__cell">Telecom</td></tr>
            <tr><td class="basic-table__cell">C008</td><td class="basic-table__cell">Real Estate/Construction/Building</td></tr>
            <tr><td class="basic-table__cell">C009</td><td class="basic-table__cell">Consumer Goods</td></tr>
            <tr><td class="basic-table__cell">C010</td><td class="basic-table__cell">Education</td></tr>
            <tr><td class="basic-table__cell">C011</td><td class="basic-table__cell">Entertainment</td></tr>
            <tr><td class="basic-table__cell">C012</td><td class="basic-table__cell">Ecology/Environment</td></tr>
            <tr><td class="basic-table__cell">C013</td><td class="basic-table__cell">Health/Biotechnology/Pharma</td></tr>
            <tr><td class="basic-table__cell">C014</td><td class="basic-table__cell">Internet</td></tr>
            <tr><td class="basic-table__cell">C015</td><td class="basic-table__cell">Policy/Government/Public</td></tr>
            <tr><td class="basic-table__cell">C016</td><td class="basic-table__cell">Publishing/Media/Communication</td></tr>
            <tr><td class="basic-table__cell">C017</td><td class="basic-table__cell">Religion</td></tr>
            <tr><td class="basic-table__cell">C018</td><td class="basic-table__cell">Food/Beverages</td></tr>
            <tr><td class="basic-table__cell">C019</td><td class="basic-table__cell">Retail</td></tr>
            <tr><td class="basic-table__cell">C020</td><td class="basic-table__cell">Fashion/Luxury/Textiles</td></tr>
            <tr><td class="basic-table__cell">C021</td><td class="basic-table__cell">Travel/Tourism</td></tr>
            <tr><td class="basic-table__cell">C022</td><td class="basic-table__cell">Natural Resources/Energy</td></tr>
            <tr><td class="basic-table__cell">C023</td><td class="basic-table__cell">Banking/Financial Services/Insurance</td></tr>
            <tr><td class="basic-table__cell">C024</td><td class="basic-table__cell">Legal Affairs/Tax/Law</td></tr>
            <tr><td class="basic-table__cell">C025</td><td class="basic-table__cell">Raw Materials/Industrial Goods</td></tr>
            <tr><td class="basic-table__cell">C026</td><td class="basic-table__cell">Lifestyle/Leisure/Hobbies</td></tr>
            <tr><td class="basic-table__cell">C027</td><td class="basic-table__cell">Sports</td></tr>
            <tr><td class="basic-table__cell">C028</td><td class="basic-table__cell">Home/Family/Friends/Children</td></tr>
            <tr><td class="basic-table__cell">C029</td><td class="basic-table__cell">Economy/Financial Markets</td></tr>
            <tr><td class="basic-table__cell">C030</td><td class="basic-table__cell">Science</td></tr>
            <tr><td class="basic-table__cell">C031</td><td class="basic-table__cell">Human Resources/Employment</td></tr>
            <tr><td class="basic-table__cell">C032</td><td class="basic-table__cell">Adult (Pornography, Violence, etc.)</td></tr>
          </tbody>
        </table>
      </div>
  - name: Organization Job Template Locales
  - name: Organization Job Templates
  - name: Pre Translations
  - name: Projects
  - name: Quality
  - name: Releases
  - name: Release Triggers
  - name: Repo Syncs
    description: |
      The Repo Syncs API allows you to synchronize your Phrase projects with your code repositories.
      You can import translations from your repository to Phrase and export translations from Phrase to your repository.
  - name: Repo Sync Events
  - name: Reports
  - name: Search
  - name: Screenshot Markers
  - name: Screenshots
  - name: Spaces
  - name: Style guides
  - name: Supported Languages
  - name: Tags
  - name: Teams
  - name: Translations
  - name: Uploads
    description: |
      ### Formats

      We support all common localization file formats. For a detailed overview, see our [Format Guide](https://support.phrase.com/hc/en-us/sections/6111343326364).

      ### Processing

      Uploads will be processed asynchronously and thus the data might not be imported yet although the upload is completed. Therefore we recommend to evaluate the returned <code>state</code> field for information on the import progress.

      #### Available States

      <div class="table-responsive">
        <table class="basic-table">
          <thead>
            <tr class="basic-table__row basic-table__row--header">
              <th class="basic-table__cell basic-table__cell--header">State</th>
              <th class="basic-table__cell basic-table__cell--header">Description</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td class="basic-table__cell"><code>initialized</code></td>
              <td class="basic-table__cell">Data received.</td>
            </tr>
            <tr>
              <td class="basic-table__cell"><code>waiting_for_preview</code></td>
              <td class="basic-table__cell">Upload is waiting for preview to be finished.</td>
            </tr>
            <tr>
              <td class="basic-table__cell"><code>waiting</code></td>
              <td class="basic-table__cell">Upload is waiting for processing.</td>
            </tr>
            <tr>
              <td class="basic-table__cell"><code>processing</code></td>
              <td class="basic-table__cell">Upload is being processed, data is currently imported.</td>
            </tr>
            <tr>
              <td class="basic-table__cell"><code>success</code></td>
              <td class="basic-table__cell">Upload is complete and all data is imported.</td>
            </tr>
            <tr>
              <td class="basic-table__cell"><code>error</code></td>
              <td class="basic-table__cell">Upload or import process failed.</td>
            </tr>
          </tbody>
        </table>
      </div>
  - name: Users
  - name: Variables
  - name: Versions / History
  - name: Webhooks
  - name: Webhook Deliveries

x-tagGroups:
  - name: Core Resources
    tags:
      - Projects
      - Locales
      - Keys
      - Key Format Annotations
      - Translations
      - Uploads
      - Tags
      - Custom Metadata Properties
      - Blacklisted Keys
      - Versions / History
  - name: Workflows
    tags:
      - Spaces
      - Jobs
      - Job Comments
      - Job Locales
      - Job Templates
      - Job Template Locales
      - Organization Job Templates
      - Organization Job Template Locales
      - Comments
      - Comment Reactions
      - Comment Replies
      - Branches
  - name: Quality
    tags:
      - Checks
      - Glossaries
      - Glossary Terms
      - Glossary Term Translations
  - name: Integrations
    tags:
      - Webhooks
      - Distributions
      - Releases
      - Release Triggers
  - name: Ordering
    tags:
      - Orders
      - Style guides
  - name: User management
    tags:
      - Authorizations
      - Users
      - Accounts
      - Members
      - Invitations
  - name: Screenshots
    tags:
      - Screenshots
      - Screenshot Markers
  - name: Misc
    tags:
      - Formats
  - name: Figma Attachments
    tags:
      - Figma attachments
      - Key's Figma attachments

components:
  securitySchemes:
    Token:
      type: apiKey
      in: header
      name: Authorization
      description: Enter your token in the format `token TOKEN`
    Basic:
      type: http
      scheme: basic

  headers:
    $ref: "./headers.yaml"

  schemas:
    $ref: "./schemas.yaml#/schemas"

  parameters:
    $ref: "./parameters.yaml"

  responses:
    $ref: "./responses.yaml"

paths:
  $ref: "./paths.yaml"