Use the Zyra API

Step 1 — Generate an API key

Open Settings → API Keys → New key. Give it a descriptive name (ci-deploy-prod, terraform-staging) and click Create.

The full key is shown once, in the form zyra_sk_<random>. Copy it now. Zyra stores only a SHA-256 hash plus the first 18 characters as a display prefix (see backend/app/routers/api_keys.py). You cannot retrieve the full key again — if you lose it, revoke the row and create a new one.

Limits: 10 active keys per user. Revoking a key is a soft delete (is_active=false) and takes effect immediately.

Step 2 — Authenticate your request

Every API call carries an Authorization header. Both JWT bearer tokens (from /api/v1/auth/login) and zyra_sk_* API keys are accepted:

curl https://app.getzyra.io/api/v1/devices \
  -H "Authorization: Bearer zyra_sk_xxxxxxxxxxxxxxxx"

For shell scripts, export the key once and reference $ZYRA_API_KEY in every subsequent call.

The canonical endpoints

Every router is mounted under /api/v1/. The ones you reach for most often:

• Auth — /api/v1/auth — login, refresh, password reset, SSO entry
• Organizations — /api/v1/organizations — profile, members, settings
• Devices — /api/v1/devices — list / register / approve / remove Compute Nodes
• Virtual Servers — /api/v1/virtual-servers — create / start / stop / resize / terminate
• Jobs — /api/v1/ml/jobs, /api/v1/inference, /api/v1/fine-tuning/jobs
• Webhooks — /api/v1/webhooks/endpoints (see Chapter 2)
• Invoices — /api/v1/invoices — list / fetch / download PDF
• SLA — /api/v1/sla — alert rules and breach history
• Monitoring — /api/v1/monitoring — fleet-wide alerts

Full machine-readable spec is at https://app.getzyra.io/openapi.json.

Pagination

List endpoints accept offset (default 0) and limit (default 50, max 200). Responses include total so you can compute remaining pages.

Response shape

Successful responses follow the standard envelope:

{
  "success": true,
  "data": { "id": "vs_...", "status": "running" },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-05-21T10:00:00Z" }
}

Errors return success: false with a structured error block carrying code, message, details, and request_id. Always log the request ID — it lets Zyra support trace the call end-to-end.

Rate limits

Every endpoint has a SlowAPI limiter; the defaults you'll hit most often are 5/min for create operations, 30/min for reads, and 100/min for high-volume operations like SCIM. Hitting the limit returns HTTP 429 with a Retry-After header. Back off and retry — don't burst.

The CLI

A first-party CLI binary is [VERIFY: not yet shipped — tracked behind the "first paying customer" founder-issue]. Until then, any HTTPie / curl wrapper works. A community Python SDK lives under /api/v1/sdk discovery endpoints.

What just happened

You created a key, hit the API with it, learned where every important endpoint lives, and saw the response shape. The next chapters use the same key for webhooks, audit log export, and CI/CD recipes.

Troubleshooting

• 401 Unauthorized. Either the header is missing the Bearer prefix or the key has been revoked.
• 429 Too Many Requests. You hit a per-endpoint rate limit. Read the Retry-After header.
• 403 Forbidden. The key works but the user lacks the role (see Stage 3, Chapter 5).