This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

API guide

The base path is /api/v1. JSON requests should send Content-Type: application/json. Error responses normally contain {"error":"description"}. Unknown build-spec fields and invalid values are rejected.

Authentication modes

Operation	Legacy token mode	Anonymous public mode
Catalog reads	Public	Public, repository details omitted
Build list/detail	Token or session	Public sanitized response
Submit	Token or session	Verified browser, matching Origin, idempotency key
Build logs	Authenticated raw stream	Public sanitized SSE
Cancel	Authenticated route	Owning browser or administrator, matching Origin
Download	Authenticated	Verified browser; private delivery
Administration	Admin token/session	Trusted Authelia identity and group

Legacy clients send Authorization: Bearer TOKEN. Browser sessions support EventSource, which cannot set that header. Public verification does not accept a legacy token as a bypass.

Main routes

Method and path	Purpose
GET /healthz, GET /livez	Process liveness
GET /readyz	Configured dependency readiness
GET /api/v1/godot-versions	Selectable engine versions
GET /api/v1/modules?godot_ref=REF	Compatibility-filtered modules
GET /api/v1/catalog/{id}	Engine catalog snapshot, revision, option schema
GET /api/v1/admission-status	Public admission allowance and queue use
GET, POST /api/v1/human-session	Inspect or establish browser verification
POST /api/v1/builds	Submit a build
GET /api/v1/builds	List builds
GET /api/v1/builds/{id}	Build detail
POST /api/v1/builds/{id}/cancel	Cancel a build
GET /api/v1/builds/{id}/logs	SSE log/progress stream
GET /api/v1/builds/{id}/artifacts/{name}	Download a listed artifact
GET /api/v1/admin/identity	Administrator identity
GET /api/v1/admin/builds/{id}/logs	Raw administrative logs
POST /api/v1/admin/builds/{id}/cancel	Administrative cancellation

The separate gateway also supports artifact HEAD, single-byte-range requests, and checksum retrieval.

Legacy submission example

curl --fail-with-body http://localhost:8080/api/v1/builds \
  -H "Authorization: Bearer $GBB_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"godot_ref":"4.4-stable","platform":"linuxbsd","arch":"x86_64","target":"editor","precision":"single","modules":[]}'

A newly queued build returns 202 with its job object. The engine ref must exist in the server catalog. Use the returned artifact names rather than guessing output filenames.

Public submission and reconnects

Read the selected engine's catalog and submit its godot_version_id and catalog_revision with the build. If supplied, godot_ref must agree with the engine row. Options must match the returned schema; raw SCons arguments and module-ref overrides are rejected.

Use an Idempotency-Key of 16–128 letters, digits, underscores, or hyphens. It is scoped to browser ownership. Retry the same logical submission with the same key; changing its normalized contents returns 409. An accepted retry can recover the original job even after catalog edits. New stale-catalog requests also return 409 and require review.

Public SSE uses event IDs. Reconnect with Last-Event-ID to resume after the last sequence. These events are a closed progress vocabulary rather than compiler output. See public log protocol.

Errors

400 indicates invalid input; 401/403 indicate missing or insufficient access; 404 indicates an unavailable addressed resource; 409 indicates a state, catalog, or idempotency conflict. 410 marks retired legacy authentication endpoints under Authelia. 429 indicates enforcement limits; honor Retry-After. 503 can be a temporary dependency failure or queue/admission unavailability.

Use the detailed legacy API reference for pagination and object examples, supplemented by public configuration, enforcement, and gateway protocol for public-mode behavior. The registered routes are in server.go (internal/httpapi/server.go in the repo).