# impartire API — Reference: Workflows

Every path is under `https://impartire.com/api/v1`. The machine-readable contract is https://impartire.com/api/v1/openapi.json (OpenAPI 3.1).

#### GET /api/v1/workflows

List the workflow templates a run can be started from

The org's live templates and the platform's system ones, ordered by name unless `sort` says otherwise (`updated_after` polls for changed ones). Each `param_schema` is what `params` on POST /runs is validated against. A template whose feature the org does not have is not listed; for an OAuth token, a team-private template only for a member of its team.

Scopes: `workflows:read`

Parameters:

- `updated_after` (query, string (date-time)) — Only templates changed strictly after this instant (ISO 8601 with offset), compared to the millisecond — poll with the newest `updated_at` you have seen (that template does not come back).
- `sort` (query, "name" | "-name" | "updated_at" | "-updated_at") — Sort key; a leading `-` is descending. Default `name`. Ties break on id.
- `limit` (query, integer) — Page size, default 50. Values above 100 are treated as 100.
- `cursor` (query, string) — next_cursor from the previous page, with the other parameters unchanged.

Response 200 — `WorkflowList`

- `data` (array of Workflow, required)
  - `id` (string (uuid), required) — The template's current version. Pass it as `workflow_id` to POST /api/v1/runs.
  - `name` (string, required)
  - `description` (string or null, required)
  - `target_asset_type` (object or null, required) — The asset type the template was built for (advisory: a run may be started on any asset).
    - `id` (string (uuid), required)
    - `name` (string, required)
  - `action_type` (string or null, required) — The media action the template runs, when it is a one-action template (e.g. transcode, captions); null for a multi-step process.
  - `param_schema` (map of object or null, required) — The launch parameters `params` on POST /api/v1/runs is validated against, keyed by name; null when the template takes none.
  - `updated_at` (string (date-time), required) — When the template (its current version) last changed — poll on it with GET /api/v1/workflows?updated_after=.
- `next_cursor` (string or null, required) — Pass as `cursor` to get the next page; null means this is the last page.

Other responses:

- 401 (Problem) — unauthenticated — no key, or an unknown, revoked or expired one.
- 403 (Problem) — insufficient-scope — the key lacks a required scope.
- 404 (Problem) — not-found.
- 422 (Problem) — validation — a bad `updated_after`, `sort`, `limit` or `cursor`.
- 429 (Problem) — rate-limited — the key's request budget is spent; wait Retry-After seconds.
- 500 (Problem) — internal.

#### GET /api/v1/workflows/{id}

Get one workflow template

Scopes: `workflows:read`

Parameters:

- `id` (path, string (uuid), required) — The template's id, from GET /api/v1/workflows (any version's id resolves to the current version).

Response 200 — `Workflow`: A workflow template a run can be started from.

- `id` (string (uuid), required) — The template's current version. Pass it as `workflow_id` to POST /api/v1/runs.
- `name` (string, required)
- `description` (string or null, required)
- `target_asset_type` (object or null, required) — The asset type the template was built for (advisory: a run may be started on any asset).
  - `id` (string (uuid), required)
  - `name` (string, required)
- `action_type` (string or null, required) — The media action the template runs, when it is a one-action template (e.g. transcode, captions); null for a multi-step process.
- `param_schema` (map of object or null, required) — The launch parameters `params` on POST /api/v1/runs is validated against, keyed by name; null when the template takes none.
- `updated_at` (string (date-time), required) — When the template (its current version) last changed — poll on it with GET /api/v1/workflows?updated_after=.

Other responses:

- 401 (Problem) — unauthenticated — no key, or an unknown, revoked or expired one.
- 403 (Problem) — insufficient-scope — the key lacks a required scope.
- 404 (Problem) — not-found.
- 429 (Problem) — rate-limited — the key's request budget is spent; wait Retry-After seconds.
- 500 (Problem) — internal.