REST API

Use predictable resource URLs, cursor pagination, and explicit error responses.

Request conventions#

The reference API uses HTTPS and JSON. Resource URLs start with /v1. Send an Accept: application/json header and a bearer token with the minimum required scopes.

curl "https://api.universe.example/v1/services?limit=20" \
  -H "Authorization: Bearer ${DU_TOKEN}" \
  -H "Accept: application/json"

{
  "items": [{"name": "catalog", "status": "ready", "replicas": 2}],
  "nextCursor": null
}

Cursor pagination#

Parameter	Type	Behavior
`limit`	integer	1–100 results; default 20
`cursor`	string	Opaque cursor from the previous response
`label`	string	Optional exact label filter

Keep filters unchanged while following a cursor. A cursor is a continuation marker, not a stable page number.

Errors and retries#

{
  "error": {
    "code": "resource_conflict",
    "message": "The service revision has changed.",
    "requestId": "req_example_204"
  }
}

Retry transient 429 and 503 responses with bounded exponential backoff. Respect Retry-After when present. Resolve validation and permission errors before retrying.