Skip to main content
The Firedrill API coordinates simulations and controlled Tools. Your application, agent, model keys, and runner stay yours. Creating a batch queues work; it does not launch your application inside Firedrill. Use the native TypeScript or Python client for simulate(...) and automatic runner coordination. Use the HTTP API when you need a language-independent integration or exact resource reads.

​
Start with discovery

The API origin is https://api.firedrill.run. Authenticated requests use a Firedrill bearer credential. In automation, store it as FIREDRILL_TOKEN.
Discovery returns supported recipe versions, capabilities, authoring schema IDs, resource bounds, and recovery guidance. Check each operation’s authorized value, then inspect /v1/context for your current principal and scope restrictions. Discovery does not grant permission or reserve capacity. Read the schema you need through GET /v1/discovery/schemas/{schemaId}. Its sha256 identifies the complete root schema. Use pointer for an RFC 6901 subtree and the prior sha256 to detect a changed contract. Structural validation does not replace cross-field validation, authorization, or recipe preview.

​
Select a project and environment

GET /v1/projects returns the projects and logical environments available to your credential. Creating a project with POST /v1/projects also creates its Default environment; use the returned IDs together. Keep that selection explicit:
  • Scoped mutations carry projectId and environmentId in their documented body.
  • Tool reads and actions use the documented project/environment query parameters.
  • Run and batch reads by ID can enforce your selection with all three headers below.
The service echoes a confirmed read selection. A retained resource outside that selection returns 409 FD_SELECTED_SCOPE_CONFLICT; it does not silently switch environments. These headers never expand credential authority. The native clients send and verify them for selected run and batch reads.

​
Coordinate a simulation

Tools, checks, semantic assessment, and a CI gate are optional. A Tool-free, observation-only simulation is valid. A seed controls supported surroundings; it does not promise identical model output or reset your application’s state. Saved scenarios are immutable retained revisions of repository-authored files. Comparisons read recorded batches; reassessment creates another assessment over frozen evidence without another target execution. Scenario recommendations rank your supplied candidates without generating scenarios or running the target. Check discovery and the returned assessment/recommendation state before relying on evaluator availability. Jev provider scores remain fractional values on a 0–4 scale, separate from ordinal levels and exact checks. They are not calibrated success probabilities. Missing evidence and evaluator failure are not low-quality agent outcomes.

​
Recover exact intent

Operations marked with Idempotency-Key require a saved key for one logical action. Reuse the key with identical input after an uncertain response. Changed input conflicts; choosing another key can create another action. A request timeout means the caller stopped waiting, not that accepted work was cancelled. Preserve the SDK journal or CLI operation ID. For API integrations, retain the original scope, request body, key, and returned resource IDs. Use the documented recovery read where one exists: catalog acquisitions and scenario recommendations support reads by key; instance creation and selected Tool lifecycle actions support /v1/service-requests/by-key. Other keyed operations recover by exact replay and retained history. Tool connection secrets are not repeated on replay: inspect and revoke the exact connection before deliberately issuing a replacement.

​
Read evidence without repeating work

List endpoints use bounded pages. Treat each cursor as opaque and return it with the same scope and filters. Numeric Tool-history cursors and opaque run/batch cursors are different contracts; use the type documented for that endpoint. Artifact metadata distinguishes pending from available. Download real captures through the authenticated artifact content route, not a direct storage URL. A declared screenshot is not an uploaded screenshot. Large retained values use digest-pinned continuation reads; absence is not a fabricated observation.

​
Errors

Errors carry a machine-readable code, a repair direction, and a request ID:
Validation errors can include error.validation; other failures can include safe error.details. Preserve requestId when reporting a problem. Do not blindly retry invalid input, expired authority, stale epochs, or an idempotency conflict. Capacity and evaluator availability remain separate from target execution and quality. See Authentication for sign-in, CI credentials, and target-facing Tool grants. The endpoint reference covers the documented JSON workflows; discover Tool-native HTTP routes and MCP operations from the selected Tool rather than assuming a universal vendor API.