Phrase Job Annotations API
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.
OpenAPI Specification
openapi: 3.0.3
info:
title: Phrase Strings API Reference Accounts Job Annotations API
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: 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.
'
paths:
/projects/{project_id}/jobs/{job_id}/annotations:
get:
summary: List job annotations
description: Retrieve a list of annotations for a job.
operationId: job_annotations/list
tags:
- Job Annotations
parameters:
- $ref: '#/components/parameters/X-PhraseApp-OTP'
- $ref: '#/components/parameters/project_id'
- $ref: '#/components/parameters/branch'
- $ref: '#/components/parameters/job_id'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/job_annotation'
headers:
X-Rate-Limit-Limit:
$ref: '#/components/headers/X-Rate-Limit-Limit'
X-Rate-Limit-Remaining:
$ref: '#/components/headers/X-Rate-Limit-Remaining'
X-Rate-Limit-Reset:
$ref: '#/components/headers/X-Rate-Limit-Reset'
x-code-samples:
- lang: Curl
source: "curl \"https://api.phrase.com/v2/projects/:project_id/jobs/:job_id/annotations\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X GET"
- lang: CLI v2
source: 'phrase job_annotations list \
--project_id <project_id> \
--job_id <job_id> \
--access_token <token>'
x-cli-version: '2.43'
/projects/{project_id}/jobs/{job_id}/annotations/{id}:
patch:
summary: Create/Update a job annotation
description: Create or update an annotation for a job. If the annotation already exists, it will be updated; otherwise, a new annotation will be created.
operationId: job_annotation/update
tags:
- Job Annotations
parameters:
- $ref: '#/components/parameters/X-PhraseApp-OTP'
- $ref: '#/components/parameters/project_id'
- $ref: '#/components/parameters/job_id'
- name: id
in: path
required: true
description: Name of the annotation to set or update.
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/job_annotation'
headers:
X-Rate-Limit-Limit:
$ref: '#/components/headers/X-Rate-Limit-Limit'
X-Rate-Limit-Remaining:
$ref: '#/components/headers/X-Rate-Limit-Remaining'
X-Rate-Limit-Reset:
$ref: '#/components/headers/X-Rate-Limit-Reset'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
x-code-samples:
- lang: Curl
source: "curl \"https://api.phrase.com/v2/projects/:project_id/jobs/:job_id/annotations/:id\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X PATCH \\\n -d '{\"value\":\"Some value...\"}' \\\n -H 'Content-Type: application/json'"
- lang: CLI v2
source: 'phrase job_annotations update \
--project_id <project_id> \
--job_id <job_id> \
--id <id> \
--data ''{"value": "Some value..."}'' \
--access_token <token>'
requestBody:
required: true
content:
application/json:
schema:
type: object
title: job_annotation/update/parameters
properties:
value:
description: Annotation value
type: string
example: Some value...
branch:
description: Branch name of the job
type: string
example: my-feature-branch
x-cli-version: '2.43'
delete:
summary: Delete a job annotation
description: Delete an annotation for a job.
operationId: job_annotation/delete
tags:
- Job Annotations
parameters:
- $ref: '#/components/parameters/X-PhraseApp-OTP'
- $ref: '#/components/parameters/project_id'
- $ref: '#/components/parameters/branch'
- $ref: '#/components/parameters/job_id'
- name: id
in: path
required: true
description: Name of the annotation to delete.
schema:
type: string
responses:
'204':
description: No Content
headers:
X-Rate-Limit-Limit:
$ref: '#/components/headers/X-Rate-Limit-Limit'
X-Rate-Limit-Remaining:
$ref: '#/components/headers/X-Rate-Limit-Remaining'
X-Rate-Limit-Reset:
$ref: '#/components/headers/X-Rate-Limit-Reset'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
x-code-samples:
- lang: Curl
source: "curl \"https://api.phrase.com/v2/projects/:project_id/jobs/:job_id/annotations/:id\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X DELETE"
- lang: CLI v2
source: 'phrase job_annotations delete \
--project_id <project_id> \
--job_id <job_id> \
--id <id> \
--access_token <token>'
x-cli-version: '2.43'
/projects/{project_id}/jobs/{job_id}/locales/{job_locale_id}/annotations:
get:
summary: List job locale annotations
description: Retrieve a list of annotations for a job locale.
operationId: job_locale_annotations/list
tags:
- Job Annotations
parameters:
- $ref: '#/components/parameters/X-PhraseApp-OTP'
- $ref: '#/components/parameters/project_id'
- $ref: '#/components/parameters/branch'
- $ref: '#/components/parameters/job_id'
- $ref: '#/components/parameters/job_locale_id'
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/job_annotation'
headers:
X-Rate-Limit-Limit:
$ref: '#/components/headers/X-Rate-Limit-Limit'
X-Rate-Limit-Remaining:
$ref: '#/components/headers/X-Rate-Limit-Remaining'
X-Rate-Limit-Reset:
$ref: '#/components/headers/X-Rate-Limit-Reset'
x-code-samples:
- lang: Curl
source: "curl \"https://api.phrase.com/v2/projects/:project_id/jobs/:job_id/locales/:job_locale_id/annotations\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X GET"
- lang: CLI v2
source: 'phrase job_locale_annotations list \
--project_id <project_id> \
--job_id <job_id> \
--job_locale_id <job_locale_id> \
--access_token <token>'
x-cli-version: '2.43'
/projects/{project_id}/jobs/{job_id}/locales/{job_locale_id}/annotations/{id}:
patch:
summary: Create/Update a job locale annotation
description: Create or update an annotation for a job locale. If the annotation already exists, it will be updated; otherwise, a new annotation will be created.
operationId: job_locale_annotation/update
tags:
- Job Annotations
parameters:
- $ref: '#/components/parameters/X-PhraseApp-OTP'
- $ref: '#/components/parameters/project_id'
- $ref: '#/components/parameters/job_id'
- $ref: '#/components/parameters/job_locale_id'
- name: id
in: path
required: true
description: Name of the annotation to set or update.
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/job_annotation'
headers:
X-Rate-Limit-Limit:
$ref: '#/components/headers/X-Rate-Limit-Limit'
X-Rate-Limit-Remaining:
$ref: '#/components/headers/X-Rate-Limit-Remaining'
X-Rate-Limit-Reset:
$ref: '#/components/headers/X-Rate-Limit-Reset'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
x-code-samples:
- lang: Curl
source: "curl \"https://api.phrase.com/v2/projects/:project_id/jobs/:job_id/locales/:job_locale_id/annotations/:id\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X PATCH \\\n -d '{\"value\":\"Some value...\"}' \\\n -H 'Content-Type: application/json'"
- lang: CLI v2
source: 'phrase job_locale_annotations update \
--project_id <project_id> \
--job_id <job_id> \
--job_locale_id <job_locale_id> \
--id <id> \
--data ''{"value": "Some value..."}'' \
--access_token <token>'
requestBody:
required: true
content:
application/json:
schema:
type: object
title: job_annotation/update/parameters
properties:
value:
description: Annotation value
type: string
example: Some value...
branch:
description: Branch name of the job
type: string
example: my-feature-branch
x-cli-version: '2.43'
delete:
summary: Delete a job locale annotation
description: Delete an annotation for a job locale.
operationId: job_locale_annotation/delete
tags:
- Job Annotations
parameters:
- $ref: '#/components/parameters/X-PhraseApp-OTP'
- $ref: '#/components/parameters/project_id'
- $ref: '#/components/parameters/branch'
- $ref: '#/components/parameters/job_id'
- $ref: '#/components/parameters/job_locale_id'
- name: id
in: path
required: true
description: Name of the annotation to delete.
schema:
type: string
responses:
'204':
description: No Content
headers:
X-Rate-Limit-Limit:
$ref: '#/components/headers/X-Rate-Limit-Limit'
X-Rate-Limit-Remaining:
$ref: '#/components/headers/X-Rate-Limit-Remaining'
X-Rate-Limit-Reset:
$ref: '#/components/headers/X-Rate-Limit-Reset'
'400':
$ref: '#/components/responses/400'
'404':
$ref: '#/components/responses/404'
'429':
$ref: '#/components/responses/429'
x-code-samples:
- lang: Curl
source: "curl \"https://api.phrase.com/v2/projects/:project_id/jobs/:job_id/locales/:job_locale_id/annotations/:id\" \\\n -u USERNAME_OR_ACCESS_TOKEN \\\n -X DELETE"
- lang: CLI v2
source: 'phrase job_locale_annotations delete \
--project_id <project_id> \
--job_id <job_id> \
--job_locale_id <job_locale_id> \
--id <id> \
--access_token <token>'
x-cli-version: '2.43'
components:
responses:
'429':
description: Rate Limiting
headers:
X-Rate-Limit-Limit:
$ref: '#/components/headers/X-Rate-Limit-Limit'
X-Rate-Limit-Remaining:
$ref: '#/components/headers/X-Rate-Limit-Remaining'
X-Rate-Limit-Reset:
$ref: '#/components/headers/X-Rate-Limit-Reset'
'404':
description: Not Found
headers:
X-Rate-Limit-Limit:
$ref: '#/components/headers/X-Rate-Limit-Limit'
X-Rate-Limit-Remaining:
$ref: '#/components/headers/X-Rate-Limit-Remaining'
X-Rate-Limit-Reset:
$ref: '#/components/headers/X-Rate-Limit-Reset'
'400':
description: Bad request
headers:
X-Rate-Limit-Limit:
$ref: '#/components/headers/X-Rate-Limit-Limit'
X-Rate-Limit-Remaining:
$ref: '#/components/headers/X-Rate-Limit-Remaining'
X-Rate-Limit-Reset:
$ref: '#/components/headers/X-Rate-Limit-Reset'
headers:
X-Rate-Limit-Reset:
description: Timestamp of end of current time period as UNIX timestamp, see [Rate Limiting](/en/api/strings/pagination#rate-limiting)
schema:
type: integer
X-Rate-Limit-Remaining:
description: The number of remaining requests in the current period
schema:
type: integer
X-Rate-Limit-Limit:
description: The number of allowed requests in the current period
schema:
type: integer
parameters:
X-PhraseApp-OTP:
in: header
name: X-PhraseApp-OTP
description: Two-Factor-Authentication token (optional)
required: false
allowEmptyValue: false
schema:
type: string
job_locale_id:
in: path
name: job_locale_id
description: Job Locale ID
required: true
schema:
type: string
job_id:
in: path
name: job_id
description: Job ID
required: true
schema:
type: string
branch:
name: branch
in: query
description: Branch to use
schema:
type: string
example: my-feature-branch
project_id:
in: path
name: project_id
description: Project ID
required: true
schema:
type: string
schemas:
job_annotation:
type: object
title: job_annotation
properties:
name:
type: string
value:
type: string
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
required:
- name
- value
example:
name: priority
value: high
created_at: '2023-10-01T12:00:00Z'
updated_at: '2023-10-01T12:00:00Z'
securitySchemes:
Token:
type: apiKey
in: header
name: Authorization
description: Enter your token in the format `token TOKEN`
Basic:
type: http
scheme: basic
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