Skip to content

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.

Send a token as a bearer token:

Terminal window
curl -H "Authorization: Bearer $ENTREPOT_TOKEN" https://entrepot.example.com/api/v1/me

Accepted 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.

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: 1

Otherwise 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.

  • 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).
  • POST creates (201), PUT replaces all mutable fields (send the complete object), DELETE returns 204.
  • Immutable fields — a repository’s format, kind and blobStore, a blob store’s type — 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 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)

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.

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.