Skip to main content
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 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

Authentication

Send your Armature API key as a bearer token. Roles are enforced per request.

MCP sources

List the connected MCP sources for your organization and register new ones.

Workflows

Create, update, archive, and manually dispatch workflows.

Runs

Search runs, pull full traces, evaluation evidence, and tool-call history.

Insights

Read MCP usage topics, failed search clusters, and session traces.

OpenAPI spec

Fetch the live OpenAPI 3.0 document to generate clients or import into tools.

​
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: 
{
  "error": {
    "code": "feature_disabled",
    "message": "MCP Analytics is not enabled for this organization"
  }
}
Common status codes:
StatusMeaning
400Validation failed. The error.message and any details describe the invalid field.
401The API key is missing, malformed, or revoked.
403The key’s role does not have permission for this operation, or the feature is disabled.
404The 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 for details.