> ## 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.

# Armature REST API for agent-driven workflow operations

> Connect any HTTP client to Armature to manage MCP sources, create and dispatch workflows, inspect runs, and query MCP usage insights — over a versioned REST API.

The Armature REST API gives any HTTP client — your build pipeline, an internal back office, or an autonomous agent that prefers OpenAPI over MCP — programmatic access to the same surface the Armature dashboard uses. Every endpoint is mounted under `/api/armature/v1/`, authenticates with an Armature API key, scopes data to that key's organization, and enforces the role the key was created under.

Use the REST API when you want to:

* Register MCP sources from infrastructure-as-code or onboarding scripts
* Create, update, archive, and manually dispatch workflows from CI
* Pull workflow run history, traces, evaluations, and tool calls into your own data store
* Read MCP usage insights — topics, failed searches, and session traces — into BI or alerting tools

If you are building an MCP-native client, see the [MCP API](/mcp-api/overview) instead. Both surfaces share the same API keys, roles, and underlying data.

## Base URL

Your Armature REST API base URL is your dashboard URL with `/api/armature/v1` appended:

```
https://your-org.armature.app/api/armature/v1
```

Replace `your-org` with your Armature organization slug. Every example in this section uses placeholder values — substitute your own host and key.

## Surfaces

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/rest-api/authentication">
    Send your Armature API key as a bearer token. Roles are enforced per request.
  </Card>

  <Card title="MCP sources" icon="server" href="/rest-api/mcp-servers">
    List the connected MCP sources for your organization and register new ones.
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/rest-api/workflows">
    Create, update, archive, and manually dispatch workflows.
  </Card>

  <Card title="Runs" icon="play" href="/rest-api/runs">
    Search runs, pull full traces, evaluation evidence, and tool-call history.
  </Card>

  <Card title="Insights" icon="chart-line" href="/rest-api/insights">
    Read MCP usage topics, failed search clusters, and session traces.
  </Card>

  <Card title="OpenAPI spec" icon="file-code" href="/rest-api/openapi">
    Fetch the live OpenAPI 3.0 document to generate clients or import into tools.
  </Card>
</CardGroup>

## Request and response format

All endpoints accept and return JSON. Send `Content-Type: application/json` on requests with a body. Successful responses use standard HTTP status codes — `200 OK` for reads, `201 Created` for resource creation, `202 Accepted` for queued dispatches.

Errors return a JSON object with an `error` field:

```json theme={null}
{
  "error": {
    "code": "feature_disabled",
    "message": "MCP Analytics is not enabled for this organization"
  }
}
```

Common status codes:

| Status | Meaning                                                                                 |
| ------ | --------------------------------------------------------------------------------------- |
| `400`  | Validation failed. The `error.message` and any `details` describe the invalid field.    |
| `401`  | The API key is missing, malformed, or revoked.                                          |
| `403`  | The key's role does not have permission for this operation, or the feature is disabled. |
| `404`  | The resource does not exist or is not visible to your organization.                     |

## OpenAPI spec

The live OpenAPI 3.0 document is served at `/api/armature/v1/openapi`. It is the source of truth for paths, parameters, and response schemas, and can be fed directly into client generators or API tooling. See [OpenAPI spec](/rest-api/openapi) for details.

## Related

* [Create an API key](/settings/api-keys) — generate a bearer token for the REST and MCP APIs.
* [MCP API overview](/mcp-api/overview) — the agent-facing MCP surface backed by the same key.