main.yaml

openapi: 3.0.3

info:
  title: Phrase Strings API Reference
  version: 2.0.0
  description:
    $ref: "./intro.md"

  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

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: 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: 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 Comments
  - name: Job Locales
  - name: Job Template Locales
  - name: Job Templates
  - name: Jobs
  - name: Keys
  - name: Linked Keys
  - name: Locales
  - name: Locale Downloads
  - 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: 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: 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
      - 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:
      - 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"