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

# Manage and dispatch Armature workflows over REST

> List, create, update, archive, and manually dispatch workflows over HTTP. Trigger validations from CI and feed workflow definitions from infrastructure-as-code.

The `/workflows` endpoints let any HTTP client manage Armature workflows and dispatch runs on demand. Use them to wire workflow creation into onboarding scripts, trigger validation runs from CI on every deploy, or sync workflow definitions from a source-of-truth repository.

All paths are relative to the [REST API base URL](/rest-api/overview#base-url). All requests require an [API key](/rest-api/authentication); write operations require `editor`, `admin`, or `owner`.

## List workflows

```http theme={null}
GET /workflows
```

Returns active production workflows for your organization.

**Query parameters**

| Parameter      | Description                                                      |
| -------------- | ---------------------------------------------------------------- |
| `category`     | One or more category slugs. Comma-separated values are accepted. |
| `categorySlug` | Alternative single-slug filter.                                  |

```bash theme={null}
curl https://your-org.armature.app/api/armature/v1/workflows \
  -H "Authorization: Bearer amt_<key-id>_<secret>"
```

## Get a workflow

```http theme={null}
GET /workflows/{id}
```

Returns the full workflow record, including its current version and schedule.

## Create a workflow

```http theme={null}
POST /workflows
```

Creates a production workflow and queues its initial dispatch window. Requires `editor`, `admin`, or `owner`.

**Request body**

| Field                                             | Type      | Required | Description                                          |
| ------------------------------------------------- | --------- | -------- | ---------------------------------------------------- |
| `name`                                            | string    | yes      | Workflow name.                                       |
| `mcpServerId`                                     | UUID      | yes      | ID of the MCP source to test.                        |
| `testerPrompt`                                    | string    | yes      | Prompt the tester agent runs against the source.     |
| `description`                                     | string    | —        | Short description shown in the dashboard.            |
| `defaultMcpAuthProfileId`                         | UUID      | —        | Default auth profile for the source.                 |
| `testerModelId`                                   | string    | —        | Single tester model.                                 |
| `testerModelIds`                                  | string\[] | —        | Multiple tester models to fan out across.            |
| `testerTargets`                                   | object\[] | —        | `{ modelId, skillMode, skillVersionId }` per target. |
| `criteria`                                        | object\[] | —        | `{ criterionText, isRequired }` evaluation criteria. |
| `schedule`                                        | object    | —        | Schedule config (omit for manual-only).              |
| `limits`, `retryPolicy`, `toolPolicy`, `metadata` | object    | —        | Execution policy overrides.                          |

**Example**

```bash theme={null}
curl https://your-org.armature.app/api/armature/v1/workflows \
  -H "Authorization: Bearer amt_<key-id>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Search returns recent issues",
    "mcpServerId": "mcp_…",
    "testerPrompt": "Search for the most recent open issue and summarize it.",
    "testerModelIds": ["claude-sonnet-4", "gpt-5"],
    "criteria": [
      { "criterionText": "Returned at least one open issue", "isRequired": true },
      { "criterionText": "Summary references the issue number", "isRequired": true }
    ]
  }'
```

**Response (`201 Created`)**

```json theme={null}
{
  "workflow": { "id": "wf_…", "name": "Search returns recent issues" },
  "currentVersion": { "id": "wfv_…" },
  "initialDispatch": { "queued": 2, "failed": 0 }
}
```

Armature runs a safety preflight before creation and queues the initial dispatch window across the configured tester targets.

## Update a workflow

```http theme={null}
PATCH /workflows/{id}
```

Update any subset of the create fields. Pass `schedule: null` to make a workflow manual-only. A new workflow version is written and returned in `currentVersion`.

## Archive a workflow

```http theme={null}
DELETE /workflows/{id}
```

Archives the workflow. Existing run history is preserved. Returns `{ "ok": true }`.

## Manually dispatch a run

```http theme={null}
POST /workflows/{id}/runs
```

Dispatches a workflow run outside its schedule. Useful for CI validation after a deploy or for kicking off a regression run from your own tooling.

**Request body (all optional)**

| Field            | Description                                                                |
| ---------------- | -------------------------------------------------------------------------- |
| `reason`         | Human-readable label for the run trigger. Shown in the dashboard.          |
| `baselineRunId`  | Run ID to use as the comparison baseline.                                  |
| `idempotencyKey` | Deduplicates retries — Armature returns the existing run for the same key. |
| `forceNewRun`    | Bypass dedup and force a new dispatch.                                     |
| `testerModelIds` | Override the workflow's configured models for this run.                    |
| `testerTargets`  | Override per-target `{ modelId, skillMode, skillVersionId }`.              |

**Example**

```bash theme={null}
curl https://your-org.armature.app/api/armature/v1/workflows/wf_…/runs \
  -H "Authorization: Bearer amt_<key-id>_<secret>" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "post-deploy smoke test",
    "idempotencyKey": "deploy-abc123"
  }'
```

The response (`202 Accepted`) includes the dispatched run IDs. Poll them with [`GET /runs/{id}`](/rest-api/runs) until they reach a terminal state.

## Related

* [Workflow overview](/workflows/overview) — concepts behind workflows, schedules, and criteria.
* [Authoring workflows](/workflows/authoring) — guidance on prompts, criteria, and tester targets.
* [Inspect runs](/rest-api/runs) — pull results back from dispatched runs.