REST API

• Contract version 0.2.1
• Download openapi.yaml
• OpenAPI 3.1. The pages only describe the API; they send no request to it.

Generated from api/openapi.yaml (Myriarch REST API, contract version 0.2.1). Management API of myriarchd (OpAMP based OpenTelemetry Collector fleet management).

REST API used by the myriarch web UI, myrctl and automation.

Conventions

• Base path /api/v1. JSON (UTF-8) request and response bodies; field names are camelCase.
• Timestamps are RFC 3339 in UTC. Durations are Go duration strings ("30s", "5m").
• Hashes are lower-case hex strings (SHA-256 unless stated otherwise).
• Collector versions are given WITHOUT a leading v ("0.162.0"), except package offers.
• Maps and arrays marked as required are never null (empty {} / []).
• Errors use RFC 9457 problem details (application/problem+json, schema Problem) with a stable machine readable code.
• Paginated lists: limit (1..500, default 50) and offset (0..100000) query parameters; response {items, total, limit, offset}. Unpaginated lists: {items}.
• Sorting: sort=<field> ascending, sort=-<field> descending.

Authentication

• Browser: server-side session cookie myriarch_session (OIDC login or dev login); with Secure cookies (the production setting) the cookie is named __Host-myriarch_session. Mutating requests (POST/PUT/PATCH/DELETE) authenticated by the cookie MUST send the header X-CSRF-Token with the value of the myriarch_csrf cookie (also returned by GET /auth/me).
• Automation: Authorization: Bearer myra_... (API token with a fixed role, never higher than the role of its creator; it stops working when the creator is disabled and after the maximum token lifetime auth.apiTokenMaxTtl, default 90 days). No CSRF header needed.
• Request bodies must be application/json (other content types: 415). Sessions have an idle timeout and an absolute maximum age. Repeated failed logins or invalid bearer tokens are rate limited per client address (429 with Retry-After).
• Roles: viewer (read), operator (viewer + operational actions), admin (operator + users, API tokens, enrollment tokens). Each operation lists its permission in x-permission.

Security schemes

Roles and permissions

Every operation names the permission that it needs. The table shows the lowest role that holds each permission; a role also holds the permissions of the roles below it. It is derived from the authorization code of the server, so it cannot drift from it.

Errors

Errors are RFC 9457 problem details with the content type application/problem+json and the type Problem. The member code is a stable, machine-readable error code.

The codes: bad_request, unauthorized, forbidden, not_found, conflict, precondition_failed, validation_failed, too_many_requests, internal, not_implemented, unavailable, csrf_failed.

The responses that many operations share:

Example:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "code": "bad_request",
  "requestId": "string",
  "issues": [
    {
      "severity": "error",
      "code": "unknown_component",
      "message": "string",
      "file": "string",
      "line": 0,
      "path": "service::pipelines::logs",
      "object": "Fleet/edge-nl"
    }
  ]
}

Live updates

GET /events/stream (Server-Sent Events), see operation streamEvents.

Non-REST endpoints

Not part of this document: OpAMP /v1/opamp (WebSocket + HTTP, agents authenticate with Authorization: Bearer myre_... enrollment tokens), /healthz (liveness), /readyz (readiness), /metrics (Prometheus, by default on the separate metrics listener), /licenses (LICENSE and THIRD_PARTY_NOTICES as text/plain, no login).

Operations by tag

The schemas that the operations use are on the page Data types.

About the contract