HTTP API

REST over HTTPS at /api/v1 on your instance. Everything the CLI does, the API does.

Authentication

Send an API token as a bearer token. Create one with vulcan token create or in Forge under Profile → My API tokens.

$ curl -H "Authorization: Bearer $VULCAN_TOKEN" \
    https://vulcan.example.com/api/v1/projects

Projects

GET /projects

Projects in the token’s organisation, most recently built first.

{
  "items": [
    {
      "id": "prj_9f3ka2",
      "name": "payments-api",
      "organisation": "acme",
      "last_build": { "number": 247, "status": "success" }
    }
  ],
  "total": 12
}

GET /projects/{id}

One project, including workflows and default pool.

Builds

POST /projects/{id}/builds

Trigger a build. Body: workflow (required), ref (defaults to the default branch head).

$ curl -X POST -H "Authorization: Bearer $VULCAN_TOKEN" \
    -d '{"workflow": "ci", "ref": "main"}' \
    https://vulcan.example.com/api/v1/projects/prj_9f3ka2/builds
{ "id": "bld_x71m0c", "number": 248, "status": "pending" }

GET /builds/{id}

Build detail: status, timing, and the phase/step tree with per-step statuses.

GET /builds/{id}/steps/{name}/log

Raw step log as text/plain. Add ?follow=true to stream while running.

DELETE /builds/{id}

Cancel a pending or running build. Completed builds return 409.

Errors

Errors are JSON with a stable code and a human-readable message:

{ "code": "forbidden", "message": "token lacks builds:write on prj_9f3ka2" }

Status	Code	Meaning
401	unauthorised	Missing, expired, or revoked token.
403	forbidden	Token is valid but lacks the required grant.
404	not_found	Resource does not exist or is outside the token’s organisation.
422	invalid	Body failed validation; message names the field.
429	rate_limited	Too many requests; see below.

Rate limits

600 requests per minute per token. Every response carries X-RateLimit-Remaining and X-RateLimit-Reset; 429 responses add Retry-After in seconds.