Spitfirev0.62.2 · What's new

Version: 0.62.2This documentation is for Spitfire 0.62.2.

API reference

This page covers using Spitfire's own HTTP API from your scripts and tools: authentication, picking a workspace, pagination and the error format. Everything the web UI, the mobile app and the CLI do goes through this API.

Opening the API reference

  • User menu → API reference (open In Spitfire: /api/docs): every endpoint by topic, the role each one needs and whether an API token may call it.
  • The machine-readable document: https://<your-spitfire-address>/api/v1/openapi.json (OpenAPI 3.1, no sign-in needed). Give this address to Postman, Insomnia or a client code generator.

On the reference page, Try it out sends the request with your session: reading is safe, but a request that writes (deleting a test, starting a run) really happens.

Authentication

Every request carries an Authorization: Bearer <token> header. Two kinds of token work:

Token Where from What it can do
Session token POST /api/v1/auth/login (then POST /api/v1/auth/mfa when two-step verification is on); short-lived, renewed with POST /api/v1/auth/refresh Everything the user's role allows
API token (sfpat_…) User menu → API tokens (details) Every read (GET) endpoint (except the API token list and session-only endpoints) and only these writes: start and stop a run, validate and plan a scenario, start, stop and continue a comparative run, claim the PR comment repository, announce a deploy, planned maintenance

An API token works with its owner's current role and groups. Managing tokens, users, settings and editing tests need a session; called with a token they answer 403 api_token_scope. In the reference, every endpoint shows x-spitfire-access (the role it needs: public, user, workspace-admin, installation-admin) and x-spitfire-api-token (whether a token may call it).

bash
curl -s -H "Authorization: Bearer $SPITFIRE_TOKEN" \
  "https://spitfire.example.com/api/v1/runs?status=failed&pageSize=10"

curl -s -X POST -H "Authorization: Bearer $SPITFIRE_TOKEN" -H "Content-Type: application/json" \
  -d '{"note": "nightly", "tags": ["ci"]}' \
  "https://spitfire.example.com/api/v1/tests/<test-id>/runs"

Workspace: requests act in the user's current workspace. For another one, send the X-Spitfire-Workspace: <id or name> header (or ?workspace=).

SCIM (/scim/v2) takes its own token and answers in SCIM's format; setting it up is in User provisioning with SCIM.

Answers and errors

Every JSON answer under /api/v1 comes in the same envelope:

json
{ "success": true, "data": { }, "msg": "", "traceId": "4bf92f3577b34da6a3ce929d0e0e4736" }

On an error, success is false and error carries a stable code (bad_request, unauthorized, forbidden, api_token_scope, not_found, conflict, too_many_attempts, internal…), a message and sometimes details. A 5xx also carries a requestId: quote it to support. An unknown address under /api/v1 is a 404 in the same envelope.

Reports (HTML/PDF), CSV exports, the live run stream (server-sent events) and shared links don't use the envelope; the reference names each one's content type.

Pagination

Paged lists (tests, runs, comparative runs, the audit log, system events) take page (from 1) and pageSize (default 25, at most 200); the envelope adds total and totalPages. Other lists come in full.

Limits

Sign-in, password reset and SSO endpoints are rate limited per address (429 too_many_attempts). Request bodies are JSON (UTF-8), at most 8 MB unless stated otherwise.