Skip to main content
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. All requests require an API key; write operations require editor, admin, or owner.

​
List workflows

GET /workflows
Returns active production workflows for your organization. Query parameters
ParameterDescription
categoryOne or more category slugs. Comma-separated values are accepted.
categorySlugAlternative single-slug filter.
curl https://your-org.armature.app/api/armature/v1/workflows \
  -H "Authorization: Bearer amt_<key-id>_<secret>"

​
Get a workflow

GET /workflows/{id}
Returns the full workflow record, including its current version and schedule.

​
Create a workflow

POST /workflows
Creates a production workflow and queues its initial dispatch window. Requires editor, admin, or owner. Request body
FieldTypeRequiredDescription
namestringyesWorkflow name.
mcpServerIdUUIDyesID of the MCP source to test.
testerPromptstringyesPrompt the tester agent runs against the source.
descriptionstring—Short description shown in the dashboard.
defaultMcpAuthProfileIdUUID—Default auth profile for the source.
testerModelIdstring—Single tester model.
testerModelIdsstring[]—Multiple tester models to fan out across.
testerTargetsobject[]—{ modelId, skillMode, skillVersionId } per target.
criteriaobject[]—{ criterionText, isRequired } evaluation criteria.
scheduleobject—Schedule config (omit for manual-only).
limits, retryPolicy, toolPolicy, metadataobject—Execution policy overrides.
Example 
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) 
{
  "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

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

DELETE /workflows/{id}
Archives the workflow. Existing run history is preserved. Returns { "ok": true }.

​
Manually dispatch a run

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)
FieldDescription
reasonHuman-readable label for the run trigger. Shown in the dashboard.
baselineRunIdRun ID to use as the comparison baseline.
idempotencyKeyDeduplicates retries — Armature returns the existing run for the same key.
forceNewRunBypass dedup and force a new dispatch.
testerModelIdsOverride the workflow’s configured models for this run.
testerTargetsOverride per-target { modelId, skillMode, skillVersionId }.
Example 
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} until they reach a terminal state.