API overview

The Ironhide API is a plain HTTPS + JSON interface to everything the CLI and the GitHub Action do: register an agent, drive it through behavioral and adversarial episodes from inside your own CI, and read the verdict on what it actually did. There is no SDK requirement, any HTTP client works.

Ironhide is inbound-only. Your real agent runs pre-production inside your own CI/CD; your pipeline pulls each episode, drives your agent locally, and submits the trajectory for grading. Ironhide never calls out to your infrastructure, and there is no endpoint for you to host or expose.

Base URL#

All endpoints in this reference are relative to:

https://ironhideai.com

Every request and response body is JSON (Content-Type: application/json).

Authentication#

Ironhide uses bearer API keys. There are two kinds:

• The agent token (wk_live_...). Issued once when you register an agent and used for everything that agent does: driving episodes, reading its verdicts, its plan and usage. This is the token your CI holds — the CLI and the GitHub Action read it from the IRONHIDE_API_KEY environment variable.
• The account owner key (wk_owner_...). Issued once when you create an account. It authenticates account-level actions — including registering new agents — and can act on any agent the account owns, so a logged-in owner does not have to juggle each agent's key.

Send whichever key applies in the standard Authorization header:

Authorization: Bearer wk_live_...

How agent tokens work:

• Issued once, at registration. POST /agents returns the token exactly once, in the api_key field of the registration response. Tokens look like wk_live_ followed by 48 hex characters.
• Stored hashed. Ironhide keeps only a SHA-256 hash of the token and verifies presented tokens with a constant-time comparison. A lost token cannot be recovered, only rotated: PATCH /agents/{agent_id} with "rotate_api_key": true returns a fresh one (again, exactly once).
• Scoped to one agent. A token authenticates requests for the agent it was issued to: its episodes, its verdicts, its plan and usage. The owning account's owner key is also accepted on those routes.
• One open path. The built-in demo agent, agent_id default, needs no key at all, so a no-signup demo works with zero friction.

A first authenticated request#

The usage endpoint is a good connectivity check: it is small, read-only, and exercises the same auth path as everything else.

curl https://ironhideai.com/agents/agt_1a2b3c/usage \
  -H "Authorization: Bearer wk_live_YOUR_KEY"

{
  "agent_id": "agt_1a2b3c",
  "runs_used": 4,
  "run_quota": 100,
  "runs_remaining": 96,
  "subscription_status": "trialing",
  "plan": { "id": "developer", "name": "Developer" }
}

The error envelope#

Every API error returns a single, uniform body:

{
  "error": {
    "code": "unauthorized",
    "message": "This endpoint requires this agent's API key.",
    "hint": "Send Authorization: Bearer <api_key> ..."
  }
}

Validation failures (HTTP 422) use the same envelope with code: "validation_error" and the offending field named in the message.

Common status codes across the API:

What this reference covers#

This reference documents the customer-facing surface:

• Agents: register a CI agent, verify it, manage its token, data rights, plan, and usage.
• CI & episodes: the inbound surface your pipeline drives — list the episodes your agent can run, pull a manifest, step an executable world, submit a trajectory for grading, and gate a release.
• Verdicts: the verdict on what your agent did — pass/fail, severity, why, and evidence.