Reference

API

Every endpoint, with the fields it takes and what it returns.

Base URL https://api.useblackforge.com/v1. JSON in and out. Send your key as Authorization: Bearer bf_live_.... Every response has an x-request-id header. The limit is 300 requests a minute per key.

Endpoints

Method and path	Does
`POST /jobs`	Start a job
`GET /jobs`	List your team's jobs, newest first, 50 per page
`GET /jobs/{id}`	One job, with stage, result, GPUs and cost so far
`POST /jobs/{id}/stop`	Stop a job in any stage
`GET /jobs/{id}/logs`	Logs. Add ?follow=true for a server sent event stream
`GET /jobs/{id}/heat`	Heat samples for the job's GPUs
`POST /sessions`	Start a shell or notebook session
`GET /forges`	Forges, free GPUs and wait estimates per plan
`GET /forges/{id}/heat`	Heat samples for a whole forge
`GET /bank`	Hour bank blocks and balances
`GET /usage`	Billed seconds by plan, forge and day. ?month=2026-09
`GET /ledger/{month}`	A forge's monthly heat ledger
`GET /incidents`	The incident log

POST /jobs

Fields are listed on Jobs. Returns 201 with the job, or 422 naming the field that is wrong.

curl https://api.useblackforge.com/v1/jobs \
  -H "Authorization: Bearer $BF_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "ghcr.io/yourlab/train:latest",
    "command": ["torchrun", "--nproc-per-node=8", "train.py"],
    "gpus": 8,
    "plan": "bank",
    "limit": "2d",
    "tags": { "project": "tide-7b" }
  }'

The job object

{
  "id": "job_2a4k1",
  "forge": "f1",
  "plan": "bank",
  "stage": "strike",
  "result": null,
  "gpus": ["gpu0", "gpu1", "gpu2", "gpu3", "gpu4", "gpu5", "gpu6", "gpu7"],
  "node": "a",
  "queue_ahead": null,
  "started_at": "2026-10-21T08:14:02Z",
  "ended_at": null,
  "billed_seconds": 92160,
  "cost_usd": 79.10,
  "tags": { "project": "tide-7b" }
}

stage is queue, heat, strike or quench. result stays null until the job ends, then is one of succeeded, failed, stopped, preempted or hardware. billed_seconds counts GPU seconds, so 8 GPUs for one hour is 28,800.

GET /forges

{
  "forges": [{
    "id": "f1", "region": "is-south", "gpu": "b200-180gb", "gpus": 16,
    "free": { "strike": 5, "ember": 9 },
    "wait_minutes": { "strike": 0, "ember": 2 },
    "anvils": 1
  }]
}

Pagination

List endpoints return next. Pass it back as ?after= to get the next page. A missing next means you have everything.

Errors

See Errors for every code.

API

#Endpoints

#POST /jobs

#The job object

#GET /forges

#Pagination