API overview
Entrepot’s management API is spec-first: api/openapi.yaml in the server
repository is the contract, and the server handlers, the Go client and the UI
types are generated from it. Every server serves:
| URL | What |
|---|---|
/api/v1/… |
the management API |
/api/docs |
Swagger UI for the running server |
/api/openapi.yaml |
the spec of the running server |
This site renders the same spec in the API reference.
Package clients (pip, npm, docker, …) don’t use this API: they talk to the
format endpoints under /repository/<name>/ and /v2/. See Using
repositories.
Authentication
Section titled “Authentication”Send a token as a bearer token:
curl -H "Authorization: Bearer $ENTREPOT_TOKEN" https://entrepot.example.com/api/v1/meAccepted tokens: an Entrepot API token (ent_…), an OIDC access token from
the configured provider, or a GitLab CI/CD id_token. Basic auth with any
username and the token as password also works. See
Authentication.
Without credentials, requests are anonymous: GET /api/v1/system/info,
GET /api/v1/me and reads of anonymously readable repositories work.
Browser sessions and CSRF
Section titled “Browser sessions and CSRF”The UI authenticates with the entrepot_session cookie. State-changing
requests (anything but GET, HEAD, OPTIONS) that authenticate with the
cookie must send:
X-Entrepot-CSRF: 1Otherwise they are rejected with 403 {"code":"csrf"}. A cross-site page
can’t add the header without a CORS preflight, which Entrepot never allows.
Requests with a bearer token don’t need the header.
Requests and responses
Section titled “Requests and responses”- JSON in, JSON out (
Content-Type: application/json). The exceptions are uploads (multipart/form-data) and downloads (application/octet-stream). - Objects have stable names (repositories, blob stores, roles, policies, scanners, rules) or server-assigned IDs (tokens, role bindings, waivers, components, assets).
POSTcreates (201),PUTreplaces all mutable fields (send the complete object),DELETEreturns204.- Immutable fields — a repository’s
format,kindandblobStore, a blob store’stype— can’t be changed; recreate the object instead. - Write-only secrets — proxy passwords, S3 secret keys, scanner secrets, imported signing keys — are accepted but never returned.
- Every repository in a response carries
permissions: the actions the caller may perform on it.
Errors
Section titled “Errors”Errors are JSON with a machine-readable code and a human message:
{"code": "in_use", "message": "…"}| Status | code |
Typical cause |
|---|---|---|
400 |
bad_request, invalid |
validation failed, malformed body |
401 |
unauthorized, invalid_token, … |
missing or invalid credentials |
403 |
forbidden, csrf |
not permitted; cookie request without X-Entrepot-CSRF |
404 |
not_found |
doesn’t exist — or you can’t read it (repository names aren’t disclosed) |
409 |
conflict, in_use |
already exists / redeploy refused; still referenced (a blob store, scanner, cleanup policy or routing rule in use) |
500 |
internal |
server error (logged) |
Pagination
Section titled “Pagination”List endpoints take limit (1–1000) and one of three cursors:
| Endpoints | Paging |
|---|---|
GET /search, GET /repositories/{name}/components |
limit + offset |
GET /repositories/{name}/assets |
limit + after; the response is {"items": […], "next": "…"} — pass next as after |
GET /audit-events, GET /activity |
limit + before (the smallest id you have), newest first |
GET /audit-events and GET /activity also take from/to time filters and
format=csv for exports.
Endpoint groups
Section titled “Endpoint groups”| Tag | Endpoints |
|---|---|
| system | /system/info, /me, /maintenance/gc, /audit-events |
| blob-stores | /blob-stores[/{name}] |
| repositories | /repositories[/{name}], …/assets, …/browse, …/signing-key[/rotate] |
| components | …/components, …/upload, /assets/{id}[/content], /components/{id}, /search |
| security | /tokens, /service-accounts[/{name}/tokens], /users, /roles, /role-bindings, /gitlab-trust-policies |
| scanning | /scanners[/{name}/test], /components/{id}/scan[s], /scan-jobs, /waivers |
| cleanup | /cleanup-policies[/{name}/preview], /repositories/{name}/cleanup |
| routing | /routing-rules[/{name}/test] |
| metrics | /metrics/overview, /repositories/{name}/metrics, /activity |
Next: curl recipes for common tasks, the Go client, or the full API reference.