> ## Documentation Index
> Fetch the complete documentation index at: https://developers.phrase.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a single task of a revision

> Returns a single task including its full configuration and its `validation_status`. Check it after editing the revision: every task must be `valid` or `needs_check` before the revision can be published.



## OpenAPI

````yaml /openapi/phrase-orchestrator.json get /orchestrator/api/v1/workflows/{workflow_id}/revisions/{revision_id}/tasks/{id}
openapi: 3.0.0
info:
  description: >
    # Introduction


    Phrase Orchestrator automates work across Phrase products by composing
    pre-built actions into workflows that run when an event fires, on a
    schedule, or on demand. Use this API to browse the catalog of actions,
    events and templates, and to build and publish workflows. You can also
    monitor each execution and the artifacts its tasks produce.


    Send requests to the host of the region your Phrase organization is in.
    Every endpoint is under `/orchestrator/api/v1`.


    | Region | Host |

    | --- | --- |

    | EU | `https://eu.phrase.com` |

    | US | `https://us.phrase.com` |


    # Authentication and access


    Exchange a Phrase Platform API token for a JSON Web Token (JWT) at the
    Platform OAuth token endpoint, as described in [Platform
    Authentication](https://developers.phrase.com/en/api/platform/authentication).


    ```bash

    curl -X POST https://eu.phrase.com/idm/oauth/token \
      -H "Content-Type: application/x-www-form-urlencoded" \
      -d "grant_type=urn:ietf:params:oauth:grant-type:token-exchange" \
      -d "subject_token=$PHRASE_API_TOKEN"
    ```


    Send the JWT from `access_token` in the `Authorization` header of every
    request. It expires after `expires_in` seconds; request a new one then.


    ```bash

    curl "https://eu.phrase.com/orchestrator/api/v1/workflows?page_size=1" \
      -H "Authorization: Bearer $PHRASE_JWT"
    ```


    A missing, expired or invalid token, or one not issued for Orchestrator,
    returns `401`. A valid token returns `403` when the user may not perform the
    action on the resource.


    ## Access


    A workflow is available to its owner and to everyone it's shared with,
    directly or through their organization. They can all read and change it,
    including its revisions, tasks, dependencies, trigger and executions, but
    only the owner can delete it. Folders and variables are private to the user
    who created them. Actions, events and templates are a catalog every user can
    read, though some actions are only available to the users or organizations
    they were granted to. A resource you can't reach returns `404`, the same as
    one that doesn't exist.


    # Pagination


    List endpoints take `page` (from 1) and `page_size` (default 25, at most
    100), and return page details in `meta`:


    ```json

    {
      "current_page": 1,
      "page_size": 25,
      "total_count": 61,
      "total_pages": 3
    }

    ```


    # Rate limits


    Each user can send 1,000 requests per 5-minute window. Past the limit,
    requests return `429` with a
    [`Retry-After`](https://www.rfc-editor.org/rfc/rfc9110#section-10.2.3)
    header, the number of seconds to wait before retrying. Every authenticated
    response carries the current state of the limit, in the header fields
    defined by the [RateLimit header fields
    draft](https://datatracker.ietf.org/doc/draft-ietf-httpapi-ratelimit-headers/):


    | Header | Description |

    | --- | --- |

    | `RateLimit-Policy` | The quota: `q` requests per `w`-second window, such
    as `"default";q=1000;w=300`. |

    | `RateLimit` | Requests remaining (`r`) and seconds until the window resets
    (`t`), such as `"default";r=998;t=241`. |


    # Errors


    Every error response is an [RFC
    9457](https://www.rfc-editor.org/rfc/rfc9457) problem details object, sent
    as `application/problem+json`. Base your error handling on `code`, which
    doesn't change. `title` and `detail` are written for people and may be
    reworded. When Orchestrator knows more about a particular error, such as why
    a token was rejected or when to retry, `detail` says so.


    ```json

    {
      "type": "https://developers.phrase.com/en/api/orchestrator/errors#not_found",
      "title": "Not Found",
      "status": 404,
      "detail": "The resource doesn't exist, or the authenticated user can't access it.",
      "code": "not_found"
    }

    ```


    A `422` can have several causes, so it also lists each one in `errors`, with
    a `detail` and, when the cause is tied to a field, a `pointer` to that field
    as a [JSON Pointer](https://www.rfc-editor.org/rfc/rfc6901):


    ```json

    {
      "type": "https://developers.phrase.com/en/api/orchestrator/errors#unprocessable_content",
      "title": "Unprocessable Content",
      "status": 422,
      "detail": "A parameter doesn't match its schema, or the change isn't allowed in the resource's current state. Each entry in `errors` describes one cause.",
      "code": "unprocessable_content",
      "errors": [
        {
          "detail": "can't be blank",
          "pointer": "/name"
        },
        {
          "detail": "Only locked revisions can be renamed."
        }
      ]
    }

    ```


    A `401` also carries a `WWW-Authenticate: Bearer` header, as defined in [RFC
    6750](https://www.rfc-editor.org/rfc/rfc6750#section-3), with
    `error="invalid_token"` when a token was sent but rejected.


    | Code | Status | Meaning |

    | --- | --- | --- |

    | `bad_request` | 400 | The request is malformed, for example its body isn't
    valid JSON. |

    | `unauthorized` | 401 | The request has no valid Phrase Platform JWT issued
    for Orchestrator. Send one as `Authorization: Bearer <JWT>`. |

    | `forbidden` | 403 | The authenticated user isn't allowed to perform this
    action on the resource. |

    | `not_found` | 404 | The resource doesn't exist, or the authenticated user
    can't access it. |

    | `request_timeout` | 408 | The request body arrived too slowly. Retry the
    request. |

    | `content_too_large` | 413 | The request body is larger than 8 MB. |

    | `unprocessable_content` | 422 | A parameter doesn't match its schema, or
    the change isn't allowed in the resource's current state. Each entry in
    `errors` describes one cause. |

    | `rate_limited` | 429 | The authenticated user's rate limit is used up.
    Retry after the number of seconds in the `Retry-After` header. |

    | `internal_server_error` | 500 | Orchestrator failed unexpectedly. A write
    may or may not have been applied, so check the resource before retrying it.
    |


    A `502`, `503` or `504` comes from the load balancer in front of
    Orchestrator, not from Orchestrator itself, and has no JSON body.


    # Patch requests


    A `PATCH` request changes only the attributes you send. Anything you leave
    out keeps its current value. To clear an optional attribute, such as a
    workflow's `description`, send `null`. Attributes that can't be cleared,
    such as `name`, reject `null` with a `422`.


    An object attribute, such as a task's `input_parameters`, replaces the
    stored object as a whole, so send all of it, including the keys you aren't
    changing. A task's `event_trigger` is the exception: only the keys you send
    change.


    # Pass data through a workflow


    A workflow starts with a trigger and runs a set of tasks. Each task runs one
    action from the catalog and takes input parameters. A parameter can hold a
    fixed value, or take data from the trigger or from a task that ran before
    it. Parameter objects say where the data comes from. Interpolation with `{{
    ... }}` reads the data into the value, and
    [functions](https://developers.phrase.com/en/api/orchestrator/transform-data-with-functions)
    can transform it first.


    ## Parameter objects


    Every input parameter, on tasks and on the trigger, is an object with three
    keys: `value`, `source` and `type`. Values in `loop`, in conditions, and in
    the filters of the trigger and of "Wait for trigger" actions use the same
    object.


    - `value`: the literal value, or an interpolation that reads the output of a
    task or of the trigger, such as `{{ $.message }}`. Here `$.message` is a
    JSONPath. It runs against the output of the task or trigger in `source`.
    That output has the shape of the `output_json_schema` returned by `GET
    /actions/{id}` and `GET /events/{id}`. `{{ @raw }}` passes the whole output.
    Interpolation, below, lists every form.

    - `source`: `""` for a literal. Otherwise the task or the trigger that
    produces the value, named as described in Referencing tasks and the trigger,
    below.

    - `type`: what `source` points at:
      - `task`: the task's output body.
      - `task_header`: the task's response headers.
      - `trigger`: the trigger data.
      - `action_bundle`: an input parameter of the enclosing action bundle, a reusable group of actions that a workflow runs as one action.
      - `""`: a literal, or an interpolation that doesn't read a task or the trigger, such as `@item` and `@var`.

    `GET /actions/{id}` returns the exact `value`/`source`/`type` shape an
    action expects, as its `input_json_schema`.


    For example, in a `workflow_definition`, an action with a literal `url` and
    a `name` taken from the output of an earlier action with slug `fetch_user`:


    ```json

    {
      "url":  { "value": "https://example.com", "source": "", "type": "" },
      "name": { "value": "{{ $.name }}", "source": "fetch_user", "type": "task" }
    }

    ```


    ## Referencing tasks and the trigger


    How you name a task or the trigger in `source` depends on the endpoint:


    - In a `workflow_definition` (`POST /workflows`), use the `slug` you gave
    the action under `actions`, or the literal `trigger`.

    - On the per-task endpoints (`POST
    /workflows/{workflow_id}/revisions/{revision_id}/tasks` and `PATCH
    /workflows/{workflow_id}/revisions/{revision_id}/tasks/{id}`), use the
    task's `id`, a UUID returned by the task endpoints, or the trigger's `id`,
    returned by `GET /workflows/{workflow_id}/revisions/{revision_id}/trigger`.
    These endpoints don't resolve slugs or the literal `trigger`.


    On the per-task endpoints, the `fetch_user` reference from the example above
    uses that task's `id`:


    ```json

    { "name": { "value": "{{ $.name }}", "source":
    "4b0d6c0e-6f1a-4c43-9a8e-2f7f7f1b9d3a", "type": "task" } }

    ```


    A task can only read the output of tasks that run before it. A task
    referenced with `type` `task` or `task_header` has to be connected to the
    task that references it through the revision's dependencies, either directly
    or through other tasks. References to tasks that run in parallel or later
    are rejected. If a task is already connected through others, don't add a
    direct dependency on it.


    ## Interpolation


    A parameter `value` is a string that can contain `{{ ... }}` interpolations.
    If the whole value is one interpolation, it keeps the type of what it
    resolves to, such as an object, list or number. If the value mixes text with
    interpolations or holds more than one, it becomes a string. Non-string
    values are JSON-encoded and missing values become `null`. For example, `"Job
    {{ $.id }} done"` becomes `"Job 42 done"` when `id` is `42`.


    What an interpolation reads depends on the value's `source` and `type`:


    - `{{ $.path.to.field }}`: a JSONPath into the output of the task or trigger
    in `source`. With `type` `task`, that is the task's output body. With `type`
    `trigger`, it is the trigger data. With `type` `task_header`, it is the
    task's response headers, with header names in lower case, such as `{{
    $.content-type }}`. A missing field resolves to `null`.

    - `{{ @raw }}` or `{{ $ }}`: the whole output of the task or trigger in
    `source`.

    - `{{ @file.path }}`: the content of the `source` task's output file, which
    is the same content as `{{ @raw }}`. Use it for file parameters, such as
    `file` and `file_2` of "Transform JSON with jq v2". On a "Create signed
    upload URL" task, it is the uploaded file, while `{{ @raw }}` is still the
    URL. The referencing task fails until the file has been uploaded. For the
    trigger, it resolves to `null`, so use `{{ @raw }}` there.

    - `{{ @metadata.filename }}`, `{{ @metadata.extension }}`, `{{
    @metadata.content_type }}`: the file name, extension and content type of the
    `source` task's output. For "Create signed upload URL", they describe the
    uploaded file.

    - `{{ @item }}` or `{{ @item.field.path }}`: the current item of the task's
    own `loop`, available in that task's input parameters and conditions. Leave
    `source` and `type` empty.

    - `{{ @action_bundle.<name> }}`: the input parameter `<name>` of the
    enclosing action bundle, available to the actions inside it. An action
    bundle is a reusable group of actions that a workflow runs as one action.
    For a file parameter, use `{{ @action_bundle.<name>.as_file }}`. Set `type`
    to `action_bundle`. `source` isn't used for this interpolation and can be
    empty.

    - `{{ @var.<name> }}`: the workflow owner's variable `<name>`, or an empty
    string if it doesn't exist. Leave `source` and `type` empty.

    - `{{ workflow_execution_webhook.<variable_name> }}`: the callback URL of
    the "Wait for trigger" task whose webhook is in `dynamic` mode with that
    `variable_name`. Each execution gets its own URL. Leave `source` and `type`
    empty.

    - `{{ sprig.<function>(<arguments>) }}`: a function call, as described in
    Functions. An argument can be a double-quoted string, an integer, a `{ ...
    }` closure, another function call, or any interpolation above except `@var`,
    written without the braces, such as `sprig.upper($.name)`.


    All `$` JSONPath, `@raw`, `@file.path` and `@metadata` interpolations in a
    value read the same `source`, including those passed to functions. In
    `sprig.replace($.old, $.new, $.text)`, all three paths read that one task.
    Different parameters can read different tasks. To combine the outputs of two
    tasks in one value, merge them first with "Transform JSON with jq v2"
    (`phrase_jq_v2/jq`), passing one task's `{{ @file.path }}` to `file` and the
    other's to `file_2`, then reference its output. `@item`, `@action_bundle`,
    `@var` and `workflow_execution_webhook` don't depend on `source`, so they
    can appear in the same value as interpolations that do.


    An interpolation that is only a string literal, like `{{ "[1, 2]" }}` or `{{
    "true" }}`, is parsed as JSON and resolves to the decoded value, here a list
    and a boolean, not a string. A literal that isn't valid JSON, like `{{
    "hello" }}`, stays a string. So does a string literal passed to a function.
    An interpolation that is only an integer, like `{{ 42 }}`, resolves to that
    integer.


    # Transform data with functions


    Function names follow [Sprig](https://masterminds.github.io/sprig/), a Go
    template function library, but only the functions listed below are
    available. Any other function is rejected. The `sprig.` prefix is optional.


    A method call passes the result before it as the method's last argument, so
    `sprig.now().Weekday()` means `Weekday(sprig.now())`. Methods can be
    chained.


    A closure is a `{ ... }` expression that list functions such as `filter` and
    `map` run once per item. Inside it, `#` is the item, so `{ #.status ==
    'done' }` is true for items whose `status` is `done`. `#.field`, `.field`
    and `[0]` read from the item. Closures support string, number, boolean and
    `nil` literals, `== != > < >= <=`, `and`/`or`/`not` (or `&& || !`) and `+ -
    * /`. Arithmetic and comparisons only work inside closures.


    String:


    - `len(value)`: Number of characters in a string, items in a list, or keys
    in an object.

    - `upper(string)`: Upper-cases `string`.

    - `lower(string)`: Lower-cases `string`.

    - `trim(string)`: Removes leading and trailing whitespace.

    - `substr(start, end, string)`: Characters from index `start` to `end`, both
    inclusive (unlike Sprig): `substr(0, 3, "hello")` is `"hell"`.

    - `replace(old, new, string)`: Replaces every `old` in `string` with `new`.

    - `contains(substring, string)`: Whether `string` contains `substring`.


    Number:


    - `int(value)`: Integer from an integer or a numeric string; also maps
    `"Monday"`..`"Sunday"` to 1..7.

    - `asInt(value)`: Integer from an integer or a numeric string.

    - `randInt(min, max)`: Random integer from `min` to `max`, both inclusive.


    Date and time:


    - `now()`: Current UTC date and time.

    - `date(layout, time)`: Formats `time` with a Go layout, such as
    `"2006-01-02 15:04:05"`, `"Jan 2"`, `"MST"`, `"-0700"`.

    - `Format(layout, time)`: Same as `date`, usually called as a method:
    `sprig.now().Format("15:04")`.

    - `Year(time)`: Year as a string, such as `"2024"`.

    - `Month(time)`: Month name, such as `"March"`.

    - `Day(time)`: Day of the month as a string, such as `"5"`.

    - `Hour(time)`: Hour (0-23) as a string.

    - `Minute(time)`: Minute as a string.

    - `Second(time)`: Second as a string.

    - `Weekday(time)`: Weekday name, such as `"Tuesday"`; `int` turns it into
    1..7.

    - `YearDay(time)`: Day of the year as a string, such as `"65"`.

    - `unixEpoch(time)`: Seconds since the Unix epoch; `time` can also be an RFC
    3339 string.

    - `duration(string)`: Parses a Go duration like `"90m"`, `"1h30m"` or
    `"-1.5h"`, for `Add` and `Truncate`.

    - `Add(duration, time)`: `time` shifted by `duration`:
    `sprig.now().Add(sprig.duration("-24h"))`.

    - `Truncate(duration, time)`: `time` rounded down to a multiple of
    `duration`, as in Go.

    - `dateModify(offset, time)`: `time` shifted by an offset of hours, minutes
    and seconds, such as `"-1h30m"`.

    - `date_modify(offset, time)`: Same as `dateModify`.


    List:


    - `list(value, ...)`: List of the arguments.

    - `first(list)`: First item, or `null` for an empty list.

    - `chunk(size, list)`: Splits `list` into lists of `size` items.

    - `filter(list, closure)`: Items for which `closure` is true.

    - `map(list, closure)`: Result of `closure` for each item.

    - `find(list, closure)`: First item for which `closure` is true, or `null`.

    - `count(list, closure)`: Number of items for which `closure` is true.

    - `all(list, closure)`: Whether `closure` is true for every item.

    - `any(list, closure)`: Whether `closure` is true for at least one item.

    - `none(list, closure)`: Whether `closure` is false for every item.

    - `one(list, closure)`: Whether `closure` is true for exactly one item.


    Values:


    - `default(fallback, value)`: `value`, or `fallback` when `value` is empty.

    - `empty(value)`: Whether `value` is `null`, `false`, `0`, `""`, `[]` or
    `{}`.

    - `string(value)`: Debug representation, not a conversion: a string comes
    back wrapped in quotes and an object as `%{"key" => value}`. Use `toJson` to
    serialize.


    Encoding:


    - `toJson(value)`: Encodes `value` as a JSON string.

    - `toJSON(value)`: Same as `toJson`.

    - `fromJson(string)`: Decodes a JSON string; invalid JSON fails the task.

    - `fromJSON(string)`: Same as `fromJson`.

    - `b64enc(string)`: Base64-encodes `string`.

    - `b64dec(string)`: Base64-decodes `string`; invalid input gives the text
    `"illegal base64 data"` instead of failing.

    - `b32enc(string)`: Base32-encodes `string`.

    - `b32dec(string)`: Base32-decodes `string`; invalid input gives the text
    `"illegal base32 data"` instead of failing.


    Examples:


    - String: `{"value": "{{ sprig.lower($.title).replace(\" \", \"-\") }}",
    "source": "fetch_post", "type": "task"}` turns the `title` `My Title` from
    `fetch_post` into `my-title`.

    - Date: `{{ sprig.now().Add(sprig.duration("-24h")).Format("2006-01-02") }}`
    is yesterday's date, such as `2026-10-20`.

    - List: `{{ sprig.filter($.items, { #.status == 'done' }) }}` keeps the
    items whose `status` is `done`.
  title: Orchestrator
  version: 1.0.0
servers:
  - description: Phrase Production EU
    url: https://eu.phrase.com
    variables: {}
  - description: Phrase Production US
    url: https://us.phrase.com
    variables: {}
security:
  - bearerHttpAuthentication: []
tags:
  - description: >-
      Pre-built integration steps available to reference in a workflow
      definition.
    name: Actions
  - description: Catalog of events and schedules that can be used as a workflow trigger.
    name: Events
  - description: Output files and data produced by an execution task.
    name: Execution artifacts
  - description: >-
      Per-action execution records within a workflow run, each tracking state,
      timing, and output.
    name: Execution tasks
  - description: >-
      Individual runs of a workflow, each capturing its trigger, state, and
      timing.
    name: Executions
  - description: Named containers for organizing workflows into a hierarchy.
    name: Folders
  - description: >-
      Directed dependencies between the tasks of a revision, defining execution
      order.
    name: Revision dependencies
  - description: >-
      Individual actions configured within a revision, each bound to a catalog
      action. Their `input_parameters` follow the rules described in [Pass data
      through a
      workflow](https://developers.phrase.com/en/api/orchestrator/pass-data-through-a-workflow).
    name: Revision tasks
  - description: The trigger configured on a revision, bound to a catalog event.
    name: Revision trigger
  - description: >-
      Versioned snapshots of a workflow definition; publishing a revision
      activates the workflow.
    name: Revisions
  - description: >-
      Pre-configured, read-only workflow definitions available as a starting
      point.
    name: Templates
  - description: >-
      Named values owned by a user, such as IDs or API keys, that the user's
      workflows reference as `{{ @var.<name> }}`.
    name: Variables
  - description: Automation definitions composed of a trigger and a sequence of actions.
    name: Workflows
paths:
  /orchestrator/api/v1/workflows/{workflow_id}/revisions/{revision_id}/tasks/{id}:
    get:
      tags:
        - Revision tasks
      summary: Get a single task of a revision
      description: >-
        Returns a single task including its full configuration and its
        `validation_status`. Check it after editing the revision: every task
        must be `valid` or `needs_check` before the revision can be published.
      operationId: OrchestratorWeb.Api.RevisionTasksController.show
      parameters:
        - description: ID of the workflow the revision belongs to.
          in: path
          name: workflow_id
          required: true
          schema:
            example: 123
            type: integer
        - description: ID of the revision the task belongs to.
          in: path
          name: revision_id
          required: true
          schema:
            example: 789
            type: integer
        - description: ID of the task.
          in: path
          name: id
          required: true
          schema:
            example: 8fa72263-21ab-4f76-83ba-50c6b4378c49
            format: uuid
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Task'
          description: OK
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
        '502':
          $ref: '#/components/responses/BadGateway'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
        '504':
          $ref: '#/components/responses/GatewayTimeout'
      callbacks: {}
components:
  schemas:
    Task:
      description: A task configured within a revision, including its full configuration.
      example:
        conditions: {}
        continue_on_status: succeeded
        description: Creates a job in the TMS project.
        id: 8fa72263-21ab-4f76-83ba-50c6b4378c49
        input_parameters:
          message:
            source: ''
            type: ''
            value: hello
        loop: {}
        name: Create job
        note: null
        retry_strategy: {}
        source:
          operation_id: rest_operation
          provider: tms
        validation_status: valid
      properties:
        conditions:
          $ref: '#/components/schemas/Conditions'
        continue_on_status:
          description: >-
            Which outcome of this task lets the tasks that depend on it run:
            `succeeded` (only when it succeeds, its execution state `completed`)
            or `succeeded_skipped` (when it succeeds or is skipped).
          enum:
            - succeeded
            - succeeded_skipped
          example: succeeded
          type: string
        description:
          description: >-
            Description of the task, taken from its action, or `null` if the
            action has none.
          example: Creates a job in the TMS project.
          nullable: true
          type: string
        event_trigger:
          $ref: '#/components/schemas/EventTrigger'
        id:
          description: Unique identifier of the task.
          example: 8fa72263-21ab-4f76-83ba-50c6b4378c49
          format: uuid
          type: string
        input_parameters:
          description: >-
            Inputs passed to the action, keyed by its parameter names, following
            the action's input_json_schema.
          type: object
        loop:
          $ref: '#/components/schemas/Loop'
        name:
          description: Name of the task.
          example: Create job
          type: string
        note:
          description: Free-text note about the task, or `null` if it has none.
          example: Creates the job for the incoming project.
          nullable: true
          type: string
        retry_strategy:
          $ref: '#/components/schemas/RetryStrategy'
        source:
          $ref: '#/components/schemas/TaskSource'
        validation_status:
          description: >-
            Result of validating the task's configuration against its action's
            input schema: `new` (created, not validated yet), `valid`, `invalid`
            (its configuration doesn't match the action's input schema) or
            `needs_check` (it has inputs the action doesn't accept, usually
            after the action was updated). A revision can be published once
            every task is `valid` or `needs_check`.
          enum:
            - new
            - valid
            - invalid
            - needs_check
          example: valid
          type: string
      required:
        - id
        - name
        - source
        - validation_status
      title: Task
      type: object
    Conditions:
      description: >-
        Conditions controlling whether the action runs; omit when the action has
        none.
      properties:
        conditionals:
          description: Top-level statements.
          items:
            $ref: '#/components/schemas/ConditionStatement'
          minItems: 1
          type: array
        new_group:
          default: []
          description: Nested groups of statements.
          items:
            $ref: '#/components/schemas/ConditionGroup'
          type: array
      required:
        - conditionals
      title: Conditions
      type: object
    EventTrigger:
      description: >-
        Configuration of an `orchestrator` `orchestrator/event_trigger` ("Wait
        for trigger") action, which pauses the workflow until the event selected
        in its `input_parameters.event` arrives. Not allowed on other actions.
      properties:
        filters:
          $ref: '#/components/schemas/EventTriggerFilters'
        webhook:
          description: >-
            Callback URL of a webhook event; defaults to static mode. Static
            mode: one URL shared by all executions, minted on import. Dynamic
            mode: each execution gets its own URL, which other actions reference
            as `{"value": "{{ workflow_execution_webhook.<variable_name> }}",
            "source": "", "type": ""}` (for example, to pass it to an external
            system as a callback URL).
          properties:
            mode:
              description: >-
                Webhook mode: `static` (one URL shared by all executions) or
                `dynamic` (a new URL for each execution). A webhook event starts
                in `static` mode; omit to keep the current mode.
              enum:
                - static
                - dynamic
              example: static
              type: string
            regenerate_static_token:
              description: >-
                When `true`, replaces the static URL with a new one, and the old
                URL stops working. When `false` or omitted, the URL stays the
                same.
              example: false
              type: boolean
              writeOnly: true
            static_url:
              description: >-
                Static-mode callback URL. Returned for the workflow's own tasks
                and revisions; ignored on write.
              example: >-
                https://eu.phrase.com/orchestrator/webhooks/callback/6f1c2a9e-8b3d-4e5f-a7c1-2d9e0b4f6a83
              readOnly: true
              type: string
            variable_name:
              description: >-
                Name of the dynamic URL variable. Generated when omitted; unique
                within the workflow.
              example: approval_callback
              pattern: ^[A-Za-z0-9_]{1,64}$
              type: string
          type: object
      title: EventTrigger
      type: object
    Loop:
      additionalProperties: false
      description: >-
        Loop configuration controlling how the action iterates. The action runs
        once per item; its input_parameters and conditions reference the current
        item with `{{ @item }}` or `{{ @item.field.path }}`.

        To use the iterations' outputs downstream, add an `orchestrator`
        `collect_loop_outputs/call` action that depends on the looped action,
        with input_parameters `{"source": {"source": "<looped action slug>",
        "type": "task", "value": "{{ @raw }}"}}`. Its output is a JSON array of
        the iterations' outputs, referenced like any other action's output.
      properties:
        loop_with:
          description: >-
            How the action iterates, which also decides the other fields that
            apply: `withItems` (over `with_items`), `withComplexItems` (over the
            objects in `with_complex_items`), `withParam` (over the array that
            `with_param_reference` points at) or `withSequence` (over numbers,
            from `with_sequence_count` or from `with_sequence_start` to
            `with_sequence_end`).
          enum:
            - withSequence
            - withItems
            - withComplexItems
            - withParam
          example: withItems
          type: string
        with_complex_items:
          description: List of objects to iterate over, for the withComplexItems strategy.
          items:
            description: An object represented as a list of key/value pairs.
            items:
              properties:
                key:
                  description: Key name.
                  example: locale
                  type: string
                value:
                  $ref: '#/components/schemas/SourceValueType'
              type: object
            type: array
          type: array
        with_items:
          description: List of items to iterate over, for the withItems strategy.
          items:
            $ref: '#/components/schemas/SourceValueType'
          type: array
        with_param_reference:
          $ref: '#/components/schemas/SourceValueType'
        with_sequence_count:
          $ref: '#/components/schemas/SourceValueType'
        with_sequence_end:
          $ref: '#/components/schemas/SourceValueType'
        with_sequence_start:
          $ref: '#/components/schemas/SourceValueType'
      title: Loop
      type: object
    RetryStrategy:
      description: Retry strategy configuration.
      properties:
        backoff_duration:
          description: Initial duration in seconds to wait between retries.
          example: 10
          maximum: 120
          minimum: 1
          type: integer
        backoff_factor:
          description: Multiplier applied to the wait duration between each retry.
          example: 2
          maximum: 10
          minimum: 1
          type: integer
        limit:
          description: Maximum number of attempts before retries stop.
          example: 3
          maximum: 10
          minimum: 0
          type: integer
        retry_policy:
          description: >-
            When a failed action is retried: `never`, `5xx` (only when its HTTP
            response had a 5xx status) or `always`.
          enum:
            - never
            - 5xx
            - always
          example: 5xx
          type: string
      required:
        - retry_policy
      title: RetryStrategy
      type: object
    TaskSource:
      description: The catalog action a task is bound to.
      example:
        action_id: 7
        operation_id: rest_operation
        provider: tms
      properties:
        action_id:
          description: ID of the bound action, as used by `GET /actions/{id}`.
          example: 7
          readOnly: true
          type: integer
        operation_id:
          description: Operation identifier of the bound action.
          example: rest_operation
          type: string
        provider:
          description: Provider of the bound action.
          example: tms
          type: string
      required:
        - provider
        - operation_id
      title: TaskSource
      type: object
    Error:
      description: An RFC 9457 problem.
      example:
        code: not_found
        detail: The resource doesn't exist, or the authenticated user can't access it.
        status: 404
        title: Not Found
        type: https://developers.phrase.com/en/api/orchestrator/errors#not_found
      properties:
        code:
          description: >-
            Stable, machine-readable error code. Branch on it rather than on
            `title` or `detail`.
          example: not_found
          type: string
        detail:
          description: Explanation of this occurrence of the problem.
          example: >-
            The resource doesn't exist, or the authenticated user can't access
            it.
          type: string
        status:
          description: HTTP status code of the response.
          example: 404
          type: integer
        title:
          description: >-
            Short summary of the problem type. The same for every occurrence of
            the type.
          example: Not Found
          type: string
        type:
          description: >-
            URI identifying the problem type. Points at its entry on the Errors
            page.
          example: https://developers.phrase.com/en/api/orchestrator/errors#not_found
          format: uri
          type: string
      required:
        - type
        - title
        - status
        - detail
        - code
      title: Error
      type: object
    UnprocessableEntity:
      description: >-
        An RFC 9457 problem listing each reason the request was rejected in
        `errors`.
      example:
        code: unprocessable_content
        detail: >-
          A parameter doesn't match its schema, or the change isn't allowed in
          the resource's current state. Each entry in `errors` describes one
          cause.
        errors:
          - detail: Has already been taken in this folder.
            pointer: /name
        status: 422
        title: Unprocessable Content
        type: >-
          https://developers.phrase.com/en/api/orchestrator/errors#unprocessable_content
      properties:
        code:
          description: >-
            Stable, machine-readable error code. Branch on it rather than on
            `title` or `detail`.
          example: unprocessable_content
          type: string
        detail:
          description: Explanation of this occurrence of the problem.
          example: >-
            A parameter doesn't match its schema, or the change isn't allowed in
            the resource's current state. Each entry in `errors` describes one
            cause.
          type: string
        errors:
          description: The errors found, at least one.
          items:
            properties:
              detail:
                description: What's wrong.
                example: Has already been taken in this folder.
                type: string
              pointer:
                description: >-
                  JSON Pointer (RFC 6901) to the field at fault. Omitted when
                  the error isn't tied to a single field.
                example: /name
                type: string
            required:
              - detail
            type: object
          type: array
        status:
          description: HTTP status code of the response.
          example: 422
          type: integer
        title:
          description: >-
            Short summary of the problem type. The same for every occurrence of
            the type.
          example: Unprocessable Content
          type: string
        type:
          description: >-
            URI identifying the problem type. Points at its entry on the Errors
            page.
          example: >-
            https://developers.phrase.com/en/api/orchestrator/errors#unprocessable_content
          format: uri
          type: string
      required:
        - type
        - title
        - status
        - detail
        - code
        - errors
      title: UnprocessableEntity
      type: object
    TooManyRequests:
      description: >-
        The per-user rate limit has been exceeded. Retry after the number of
        seconds in the `Retry-After` header.
      example:
        code: rate_limited
        detail: >-
          This user's limit of 1000 requests per 300 seconds is used up. Retry
          in 42 seconds.
        status: 429
        title: Too Many Requests
        type: https://developers.phrase.com/en/api/orchestrator/errors#rate_limited
      properties:
        code:
          description: >-
            Stable, machine-readable error code. Branch on it rather than on
            `title` or `detail`.
          example: rate_limited
          type: string
        detail:
          description: Explanation of this occurrence of the problem.
          example: >-
            The authenticated user's rate limit is used up. Retry after the
            number of seconds in the `Retry-After` header.
          type: string
        status:
          description: HTTP status code of the response.
          example: 429
          type: integer
        title:
          description: >-
            Short summary of the problem type. The same for every occurrence of
            the type.
          example: Too Many Requests
          type: string
        type:
          description: >-
            URI identifying the problem type. Points at its entry on the Errors
            page.
          example: >-
            https://developers.phrase.com/en/api/orchestrator/errors#rate_limited
          format: uri
          type: string
      required:
        - type
        - title
        - status
        - detail
        - code
      title: TooManyRequests
      type: object
    InternalServerError:
      description: An unexpected server error. The body carries no details about the cause.
      example:
        code: internal_server_error
        detail: >-
          Orchestrator failed unexpectedly. A write may or may not have been
          applied, so check the resource before retrying it.
        status: 500
        title: Internal Server Error
        type: >-
          https://developers.phrase.com/en/api/orchestrator/errors#internal_server_error
      properties:
        code:
          description: >-
            Stable, machine-readable error code. Branch on it rather than on
            `title` or `detail`.
          example: internal_server_error
          type: string
        detail:
          description: Explanation of this occurrence of the problem.
          example: >-
            Orchestrator failed unexpectedly. A write may or may not have been
            applied, so check the resource before retrying it.
          type: string
        status:
          description: HTTP status code of the response.
          example: 500
          type: integer
        title:
          description: >-
            Short summary of the problem type. The same for every occurrence of
            the type.
          example: Internal Server Error
          type: string
        type:
          description: >-
            URI identifying the problem type. Points at its entry on the Errors
            page.
          example: >-
            https://developers.phrase.com/en/api/orchestrator/errors#internal_server_error
          format: uri
          type: string
      required:
        - type
        - title
        - status
        - detail
        - code
      title: InternalServerError
      type: object
    ConditionStatement:
      description: A single comparison statement.
      properties:
        compare:
          description: >-
            Comparison operator: `StringEquals`, `StringMatches` (the value
            matches a regular expression), `IntegerEquals`,
            `IntegerGreaterOrEqualsThan`, `IntegerLessOrEqualsThan`,
            `BooleanEquals`, `IsNull` or `IsPresent`.
          enum:
            - StringEquals
            - IntegerEquals
            - IntegerGreaterOrEqualsThan
            - IntegerLessOrEqualsThan
            - BooleanEquals
            - IsNull
            - IsPresent
            - StringMatches
          example: StringEquals
          type: string
        group:
          default: AND
          description: >-
            Logical operator joining this statement with the preceding one:
            `AND` or `OR`.
          enum:
            - AND
            - OR
          example: AND
          type: string
        negation:
          default: ''
          description: Negates the comparison when set to "NOT".
          enum:
            - ''
            - NOT
          example: ''
          type: string
        value:
          description: Value to compare against. Not used for IsNull/IsPresent.
          example: completed
          type: string
        variable:
          $ref: '#/components/schemas/SourceValueType'
      required:
        - variable
        - compare
      title: ConditionStatement
      type: object
    ConditionGroup:
      description: A nested group of statements joined by a logical operator.
      properties:
        conditionals:
          description: Statements belonging to this group.
          items:
            $ref: '#/components/schemas/ConditionStatement'
          minItems: 1
          type: array
        group:
          default: AND
          description: >-
            Logical operator joining this group with the preceding one: `AND` or
            `OR`.
          enum:
            - AND
            - OR
          example: OR
          type: string
        new_group:
          default: []
          description: Nested sub-groups.
          items:
            $ref: '#/components/schemas/ConditionGroup'
          type: array
      required:
        - conditionals
      title: ConditionGroup
      type: object
    EventTriggerFilters:
      description: Filters the incoming event must match.
      properties:
        data:
          description: Filter conditions.
          items:
            description: >-
              A single filter condition matched against the incoming event.
              `path` holds a JSONPath into the event payload, for example
              `{"value": "{{ $.job.uid }}", "source": "", "type": ""}`; `value`
              items may also reference upstream outputs, resolved when the
              action starts waiting.
            properties:
              comparator:
                description: >-
                  Comparison operator: `=`, `!=`, `>`, `>=`, `<`, `<=`, `match`
                  or `not_match` (the value does or doesn't match the regular
                  expression in `value`), `is_null` or `is_not_null`.
                enum:
                  - '='
                  - '!='
                  - is_null
                  - is_not_null
                  - '>'
                  - '>='
                  - <
                  - <=
                  - match
                  - not_match
                example: '='
                type: string
              path:
                $ref: '#/components/schemas/SourceValueType'
              type:
                description: >-
                  Data type of the value at the path: `string`, `bool` or
                  `number`.
                enum:
                  - string
                  - bool
                  - number
                example: string
                type: string
              value:
                description: >-
                  Values to compare against, each a literal or a reference to an
                  upstream output. Not used for is_null/is_not_null.
                items:
                  oneOf:
                    - type: string
                    - $ref: '#/components/schemas/SourceValueType'
                type: array
            required:
              - path
              - type
              - comparator
            type: object
          type: array
        dataLogicalOperator:
          description: >-
            Logical operator joining the filter conditions: `and` (all must
            match) or `or` (any must match).
          enum:
            - and
            - or
          example: and
          type: string
      required:
        - dataLogicalOperator
      title: EventTriggerFilters
      type: object
    SourceValueType:
      description: >-
        A value that is either a literal or a reference to the output of another
        step.
      properties:
        source:
          description: >-
            Origin of the value, correlated with type:

            - `""` for a literal or an `@item` loop item reference;

            - the step that produces the referenced value: the slug of the
            action in a workflow definition, or the id of the task when
            configuring a task directly. It must be upstream of this step,
            directly or through other steps;

            - to read from the workflow's trigger, `"trigger"` in a workflow
            definition, or the trigger's id when configuring a task directly.
          example: trigger
          type: string
        type:
          description: |-
            Kind of reference, correlated with source:
            - `""` for a literal or an `@item` loop item reference;
            - `"task"` for an action's output body;
            - `"task_header"` for an action's response headers;
            - `"trigger"` for trigger data;
            - `"action_bundle"` for an action-bundle input parameter.
          enum:
            - ''
            - trigger
            - task
            - task_header
            - action_bundle
          example: trigger
          type: string
        value:
          description: >-
            The value to use: a literal (for example, `"https://example.com"`,
            an enum member, or a number as a string), or a string with `{{ ...
            }}` interpolations such as `"{{ $.field.path }}"`. See [Pass data
            through a
            workflow](https://developers.phrase.com/en/api/orchestrator/pass-data-through-a-workflow)
            for every supported form and how it correlates with source and type.
          example: '{{ $.project.uid }}'
          type: string
      required:
        - value
        - source
        - type
      title: SourceValueType
      type: object
  responses:
    Unauthorized:
      content:
        application/problem+json:
          examples:
            Unauthorized:
              value:
                code: unauthorized
                detail: >-
                  The request has no valid Phrase Platform JWT issued for
                  Orchestrator. Send one as `Authorization: Bearer <JWT>`.
                status: 401
                title: Unauthorized
                type: >-
                  https://developers.phrase.com/en/api/orchestrator/errors#unauthorized
          schema:
            $ref: '#/components/schemas/Error'
      description: >-
        The `Authorization` header is missing or not a `Bearer` token, or the
        token is invalid: its signature doesn't verify, it has expired or isn't
        valid yet, or it wasn't issued for Orchestrator.
      headers:
        WWW-Authenticate:
          description: >-
            The authentication scheme: `Bearer`, with `error="invalid_token"`
            when a token was sent but rejected.
          schema:
            example: Bearer error="invalid_token"
            type: string
          style: simple
    Forbidden:
      content:
        application/problem+json:
          examples:
            Forbidden:
              value:
                code: forbidden
                detail: >-
                  The authenticated user isn't allowed to perform this action on
                  the resource.
                status: 403
                title: Forbidden
                type: >-
                  https://developers.phrase.com/en/api/orchestrator/errors#forbidden
          schema:
            $ref: '#/components/schemas/Error'
      description: >-
        The token is valid, but the user may not perform this action on the
        resource, or Orchestrator has no user for the account the token was
        issued to.
    NotFound:
      content:
        application/problem+json:
          examples:
            NotFound:
              value:
                code: not_found
                detail: >-
                  The resource doesn't exist, or the authenticated user can't
                  access it.
                status: 404
                title: Not Found
                type: >-
                  https://developers.phrase.com/en/api/orchestrator/errors#not_found
          schema:
            $ref: '#/components/schemas/Error'
      description: The resource doesn't exist, or the authenticated user can't access it.
    UnprocessableEntity:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/UnprocessableEntity'
      description: >-
        The request was rejected: a path, query or body parameter doesn't match
        its schema, or the change isn't allowed in the resource's current state.
        Each entry's `pointer`, when present, points at the field at fault.
    TooManyRequests:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/TooManyRequests'
      description: >-
        The per-user rate limit of 1,000 requests per 5-minute window is used
        up. Every authenticated response carries the `RateLimit-Policy` and
        `RateLimit` headers; wait the number of seconds in `Retry-After` before
        retrying.
      headers:
        RateLimit:
          description: Requests remaining (`r`) and seconds until the window resets (`t`).
          schema:
            example: '"default";r=0;t=42'
            type: string
          style: simple
        RateLimit-Policy:
          description: 'The quota policy: `q` requests per `w`-second window.'
          schema:
            example: '"default";q=1000;w=300'
            type: string
          style: simple
        Retry-After:
          description: Seconds until the rate-limit window resets.
          schema:
            example: 42
            type: integer
          style: simple
    InternalServerError:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/InternalServerError'
      description: >-
        Orchestrator failed unexpectedly while handling the request. A write may
        or may not have been applied, so check the resource before retrying it.
    BadGateway:
      description: >-
        Returned by the load balancer in front of Orchestrator when the service
        closed the connection or sent an invalid response, for example while an
        instance restarts. The body isn't JSON. Retry with a backoff.
    ServiceUnavailable:
      description: >-
        Returned by the load balancer in front of Orchestrator when no instance
        is available to handle the request. The body isn't JSON. Retry with a
        backoff.
    GatewayTimeout:
      description: >-
        Returned by the load balancer in front of Orchestrator when the service
        didn't respond in time. The body isn't JSON. A write may still complete,
        so check the resource before retrying it.
  securitySchemes:
    bearerHttpAuthentication:
      bearerFormat: JWT
      description: >-
        A Phrase Platform JWT issued for Orchestrator, sent as `Authorization:
        Bearer <JWT>`. See [Authentication and
        access](https://developers.phrase.com/en/api/orchestrator/authentication-and-access)
        for how to obtain one.
      scheme: bearer
      type: http

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.