Skip to content

REST API

Ampora's REST API is the same surface the UI uses. Every UI action goes through it, so anything you can do in the UI you can do via the API.

Base URL

https://AMPORA_HOST/api/...

Authentication

Two flavours, depending on the caller:

Operator (OIDC)

Send a Bearer token issued by the configured OIDC provider:

Authorization: Bearer <id-or-access-token>

The token must contain the role claim Ampora is configured to read. The OIDC provider must be the same one Ampora trusts via Authentication:Oidc:Authority.

Service-to-service (PAT)

For automation, issue a Personal Access Token from Settings → Tokens → API tokens (Admin only). The token format is amp-pat.<base32>.<crc>.

Authorization: Bearer amp-pat.XXX.YYY

PATs carry a role and an optional set of allowed endpoints. Audit trails record the PAT name on every call.

Catalogue (selected)

A non-exhaustive map of the most-used endpoints:

Method Path Purpose
GET /api/agents List agents (with filters)
GET /api/agents/{id} Agent detail
POST /api/agents/{id}/move Move to a different group
POST /api/agents/{id}/revoke-cert Revoke the agent's mTLS leaf
GET /api/configurations List configurations
POST /api/configurations Create configuration container
POST /api/configurations/{id}/versions Save a draft version
POST /api/configurations/{id}/versions/{version}/publish Publish
GET /api/configurations/{id}/versions/{version} Get a version
GET /api/configurations/{id}/versions/compare Diff two versions
GET /api/groups List groups
POST /api/groups Create group
POST /api/groups/{id}/members Add member
DELETE /api/groups/{id} Soft-delete
GET /api/rollouts List rollouts
POST /api/rollouts Create rollout
POST /api/rollouts/{id}/start Start
POST /api/rollouts/{id}/pause Pause
POST /api/rollouts/{id}/resume Resume
POST /api/rollouts/{id}/abort Abort
POST /api/rollouts/{id}/rollback Rollback
GET /api/audit/events Audit log
GET /api/policies List policies
POST /api/policies Create custom policy
POST /api/policies/{id}/approve Approve a draft
GET /api/git-sources List GitOps sources
POST /api/git-sources Register a new source
POST /api/git-sources/{id}/sync Force sweep
POST /api/git/webhook/{sourceId} Inbound Git webhook
GET /api/federation/peers List federation peers
POST /api/federation/peers Create peer
GET /api/federation/agents Federated agents (cross-peer)
GET /api/federation/ping Liveness for inbound peer
POST /api/federation/handover/redeem Redeem handover token
POST /api/federation/rollouts Create federated rollout
GET /api/tokens List bootstrap tokens
POST /api/tokens Issue bootstrap token
POST /api/tokens/{id}/revoke Revoke
POST /api/tokens/pools/{id}/issue Pool-issued token

The full OpenAPI document is served at GET /api/openapi.json (auth required) and rendered at GET /swagger in development.

Pagination and filtering

List endpoints accept:

  • limit (default 50, max 1000),
  • offset or cursor,
  • entity-specific filters as query parameters.

Responses include X-Total-Count and a Link header with rel="next" when applicable.

Concurrency

Mutating endpoints on Configuration, Rollout, Group, Policy and Tenant use ETags / RowVersion for optimistic concurrency:

  • GET returns ETag: <hex>.
  • PUT / POST accept If-Match: <etag>. Mismatch returns 412.

The UI handles this transparently; CLI scripts should respect it.

Errors

Errors are JSON of the form:

{
  "type": "https://docs.ampora.io/errors/policy-denied",
  "title": "Policy denied the push",
  "status": 422,
  "detail": "Policy 'no-debug-in-prod' returned false for agent abc-...",
  "instance": "/api/rollouts/123/start"
}

Standard problem-details (RFC 7807). The type URL points back into this docs site for the matching narrative page.

Live updates (REST clients)

For real-time progress, subscribe to the SignalR hub at wss://AMPORA_HOST/hubs/live-updates. The wire format is JSON envelopes; your client picks which event types to subscribe to.