API Reference

Authentication

Every request carries a scoped API key in the Authorization header. Keys are environment-bound — a ik_staging_* key cannot write to production. Manage keys in Settings → API Keys or via the Keys endpoint.

Authorization: Bearer ik_prod_b4f2e9c1a7d3…

Errors

Inkvo uses conventional HTTP status codes and returns a JSON body with a machine-readable code and a human message.

Status	Meaning
`400`	Malformed request or invalid payload
`401`	Missing or invalid key
`403`	Key lacks the required scope
`429`	Rate limited — back off using `Retry-After`
`5xx`	Server error — safe to retry with backoff

{
  "error": {
    "code": "scope_required",
    "message": "This key cannot write deploys. Needs deploys:write."
  }
}

Rate limits

Limits are per workspace and scale with your plan. Responses include X-RateLimit-Remaining and X-RateLimit-Reset. Ingest has separate, higher limits documented in the OTLP reference.

Ingest

Prefer OTLP for telemetry. This JSON endpoint exists for environments that can't emit OTLP directly.

POST/v1/ingest/metricsPush a metric sample

curl -X POST https://api.inkvo.dev/v1/ingest/metrics \
  -H "Authorization: Bearer $INKVO_KEY" \
  -d '{"service":"payments-svc","env":"production",
       "name":"checkout.p99","value":12400,"unit":"ms"}'

Deploys

Deploy markers power root-cause correlation. Send one on every release.

POST/v1/deploysRecord a deploy

curl -X POST https://api.inkvo.dev/v1/deploys \
  -H "Authorization: Bearer $INKVO_KEY" \
  -d '{"service":"payments-svc","sha":"3d9a1c","env":"production"}'

# → 201 Created
{ "id": "dep_8f21", "correlated_incidents": [] }

Incidents

Read incidents and their narratives. Requires read:incidents.

GET/v1/incidentsList incidents

curl https://api.inkvo.dev/v1/incidents?env=production&status=open \
  -H "Authorization: Bearer $INKVO_KEY"

GET/v1/incidents/:idFetch one, with narrative

{
  "id": "inc-2847",
  "severity": "sev-1",
  "service": "payments-svc",
  "narrative": "Checkout p99 went 180ms → 12.4s…",
  "confidence": 0.92,
  "correlated_deploy": "3d9a1c"
}

Keys

Manage API keys programmatically. Requires admin:*.

POST/v1/keysCreate a scoped key

curl -X POST https://api.inkvo.dev/v1/keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -d '{"name":"ci-deploys","scopes":["deploys:write"],"env":"production"}'

# the plaintext key is returned exactly once
{ "id": "key_a91f", "secret": "ik_prod_…" }

DELETE/v1/keys/:idRevoke a key