API conventions

Three things worth knowing before you hit the wrong wall.

Error envelope

Every non-2xx response uses the same shape:

{
  "error": {
    "code": "missing_scope",
    "message": "api key is missing required scope 'notes:write'",
    "details": {
      "required": ["notes:write"],
      "missing": ["notes:write"]
    }
  }
}

code is machine-readable (missing_scope, validation_error, http_error), message is human-readable, details depends on the error type.

Idempotency-Key

Mutating requests (POST/PUT/PATCH/DELETE) on /api/v1/ accept an Idempotency-Key header. The server caches the response for 24 h keyed on (token-hash, key) — when an AI agent retries after a timeout, it gets back the cached response instead of double-creating.

curl -X POST https://api.nevios.io/api/v1/notes \
  -H "Authorization: Bearer $NEVIOS_KEY" \
  -H "X-Workspace-Id: ..." \
  -H "Idempotency-Key: stable-id-abc123" \
  -d '{"title": "..."}'

Replays carry an Idempotent-Replay: true header in the response.

Versioning

/api/v1/ is a stable URL space. Additive changes (new fields, new endpoints) ship any time — your code should ignore unknown fields. Breaking changes go under /api/v2/, and v1 stays live until an explicit sunset (90 days notice via the Sunset header).

Pagination

Listing endpoints (/api/v1/notes, /api/v1/invoices, …) accept:

• limit — items to return (max 200)
• offset — where to continue
• or cursor (preferred) — opaque token from the previous response

Response is {records, next_cursor}. When next_cursor is missing you've reached the end.