API reference · Edition 2026
The atlas, as JSON.
Compute Atlas exposes a small HTTP+JSON API over the open dataset. Reads are public and unauthenticated; the data returned carries the same CC-BY license as the site.
§ Reading the data
Public reads
No authentication is required, and every response carries an open CORS header (Access-Control-Allow-Origin: *) so the data can be fetched directly from the browser.
| Endpoint | Description |
|---|---|
| GET /api/facilities | All facilities. Optional filters: state, type, operator, status, q — each accepts a comma-separated list or repeated params; unrecognized tokens are ignored rather than rejected. Returns { count, facilities }. |
| GET /api/facilities/{id} | One facility by id. 404 if the id isn't found. |
| GET /api/stats | Aggregate dataset figures: { count, states, operationalMw, plannedMw, underConstructionMw }. |
| GET /api/schema | The JSON Schema of a facility record, derived from the underlying Zod schema. |
The record shape is documented as a live JSON Schema at /api/schema, generated directly from the same Zod schema that validates writes — it can’t drift out of sync with the data.
§ Examples
curl examples
curl https://www.compute-atlas.com/api/facilities?state=TX
curl https://www.compute-atlas.com/api/facilities?type=data_center&status=operational
curl https://www.compute-atlas.com/api/facilities/{id}
curl https://www.compute-atlas.com/api/stats§ Writing the data
Admin writes
Creating, updating, and deleting facility records requires an admin bearer token: Authorization: Bearer <token>. These are operator endpoints, not public write access.
| Endpoint | Description |
|---|---|
| POST /api/facilities | Create a facility. 201 on success, 400 on a schema-invalid body, 409 on a duplicate id. |
| PATCH /api/facilities/{id} | Partially update a facility. 200 on success, 400 on a schema-invalid body, 404 if the id isn't found. |
| DELETE /api/facilities/{id} | Delete a facility. 200 on success, 404 if the id isn't found. |
§ Provenance
Submissions: discovered, staged, reviewed
Nothing is auto-published. A candidate record — whether a new facility or an update to an existing one — is first staged as a pending submission with its provenance attached, then reviewed by a person before it is promoted to a live record. The submissions API is how that staging happens. Every submissions endpoint — including the GET list — requires an admin bearer token; the queue is not public, since it feeds the same human-gated review process used internally. This is deliberately slower than auto-ingestion — the atlas optimizes for accuracy over count.
| Endpoint | Description |
|---|---|
| POST /api/submissions | Stage a candidate for review: { kind: "create" | "update", targetFacilityId?, payload, provenance }. targetFacilityId is required when kind is "update". |
| GET /api/submissions?status=pending | Admin-only. List staged submissions, optionally filtered by review status. |
| POST /api/submissions/{id}/approve | Validate a pending submission and promote it to a live facility. |
| POST /api/submissions/{id}/reject | Reject a pending submission: { reason }. |