Kovira API v1

01 · URL architecture

Major group before operation

Every externally consumable endpoint follows /v1/{major-group}/{operation-or-resource}. Group names are lowercase and case-sensitive. Canonical examples omit the terminal slash; a single terminal slash is normalized, but nested suffixes and duplicate separators are rejected.

/v1
├── calendar/feeds/        opaque-token iCalendar feeds
├── cis/                   configuration items
├── problems, changes, requests, customers, audit-entries
├── incidents/             incident records and transitions
├── integrations/          provider-signed callbacks
├── l2/                    network observations
├── platform/health        authenticated service liveness
└── scim/v2/               SCIM 2.0 provisioning

02 · Contract conventions

Predictable on the wire

{
  "data": [{ "id": "…" }],
  "meta": { "next_cursor": null }
}

{
  "error": {
    "code": "validation_failed",
    "message": "Invalid input."
  }
}

Customer API authentication

Every customer REST read, write and retry requires an explicit active or trialing workspace subscription and an enabled license plan. Paid licenses and trials must have an unexpired billing period. Explicit active free licenses are accepted. Missing, inactive or expired licensing returns 403 license_required. Keys must be unexpired and unrevoked, and their issuer must remain an active tenant member. Licensing storage failures return 503 and deny access.

Create a tenant-bound key in Workspace Settings → API Keys. Send it on REST calls. Keys are hashed at rest, individually scoped, expirable, and revocable.

CopyAuthorization: Bearer kvr_live_REDACTED

03 · Failure semantics

Errors, limits, and retries

Customer keys receive 60 requests per rolling minute. Responses expose X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. A separate pre-authentication IP limit bounds credential spraying.

04 · System API

Platform

A lightweight liveness resource for load balancers and external monitors. It checks request handling, not downstream dependency health; operational history remains on the public status page.

05 · Customer REST

Incidents

Incident fields and lifecycle transitions are separate. Use the transition resource for status changes; PATCH handles descriptive and assignment fields.

Enums. Status: new, assigned, in_progress, resolved, closed. Priority: p1–p4. Impact and urgency: high, medium, low.

Resolution records restored service and stops SLA timing. Administrative closure records confirmation. Once an incident has been declared major, major_review_required retains its structured review obligation even if the current classification changes. Reopening requires a reason and preserves the original SLA deadlines and breach history.

Use record_response: true when starting work to record the first human response. Assignment and automated dispatch do not record a response. The server stamps the response time and responding identity once, preserving any response breach.

06 · Customer REST

Configuration items

The CMDB list is a unified projection across CI tables. Writes expose a deliberately narrow base shape: type, name, description, status, and customer_id.

Writable types. device, network, service, rack, domain, document, vendor, location, contract, person, group, api, license, software, wan, sla, saas_app, business_service, quote.

Incident/change projections, password records, and integration-managed Entra/Intune records are readable where present but cannot be mutated through generic CI routes.

Generic CI writes support the 18 types listed in OpenAPI. Quotes and other workflow-specific records remain readable through this API; their lifecycle is managed through the corresponding domain workflow.

07 · Customer REST

Layer 2 observations

Read-only operational data produced by VECTOR’s signed ingest pipeline. The public key never receives write access to observation tables.

08 · REST records and audit

Core records and catalog

Incidents, configuration items, problems, changes, requests and customers support GET, POST and PATCH. Each endpoint requires a tenant-bound bearer key with the matching resource scope and an active workspace license. Request type discovery uses requests:read. Audit entries are read-only.

Lists use limit and cursor with data and meta.next_cursor, meta.has_more and meta.total_count. Search matches the title or name. updated_after selects records changed after an RFC 3339 timestamp. Record lists accept customer_id and assignee_id where applicable; use null for unassigned. Keep filters unchanged while following cursors.

POST to a transitions collection applies the record lifecycle. Approvals, resolution evidence, and blackout restrictions remain enforced. Customer status can be set to archived and restored to active through PATCH. Closed records cannot be edited. Request creation requires an enabled catalog type and validated form_data; approvals are recorded through the approval workflow.

GET details and successful record writes return ETag. Supply it as If-Match for every PATCH or lifecycle transition. Missing headers return 428; stale revisions and racing writes return 412. Fetch the latest record before attempting a new mutation.

Use Idempotency-Key on writes. Completed retries retain status, body, Location and ETag for 24 hours. Reuse the original input and If-Match value. Changed input or If-Match, concurrent requests and uncertain outcomes return 409. Authentication and licensing are checked again before a replay.

Comment collections support POST, paginated GET and detail GET. HTML is sanitized. Private notes require the key issuer to have the matching update permission; otherwise they are omitted from lists and return 404 on detail reads. Request catalog field collections return a bounded array of at most 50 definitions.

GET /v1/problems?limit=25&status=analyzing&customer_id=null

PATCH /v1/problems/{id}
Authorization: Bearer kvr_live_REDACTED
Content-Type: application/json
If-Match: "ETAG_FROM_GET"
Idempotency-Key: problem-update-1

{"root_cause":"Configuration error"}

09 · Identity provisioning

SCIM 2.0

Use the dedicated SCIM bearer issued by Kovira. SCIM resource media types and error shapes follow RFC 7644. The product major and SCIM protocol major remain visibly separated in the path.

12 · Provider callbacks

Integrations

These are provider-to-Kovira callbacks. Authentication is provider-specific: Stripe signature, Slack signing secret, or Microsoft Bot Framework identity. Public API bearer keys are not accepted.

13 · Token feeds

Calendar feeds

Do not put feed URLs in logs, analytics, support screenshots, or public documents. Rotate a feed token when it may have been disclosed.

Explore the contract

Interactive API reference

Search every public operation, inspect request and response schemas, and build requests with examples. Credentials stay in memory for this tab.

14 · Working examples

Start with discovery

Copycurl --fail-with-body -H 'Authorization: Bearer kvr_live_REDACTED' https://api.kovira.app/v1

List open high-priority incidents

Copycurl --fail-with-body \
  -H 'Authorization: Bearer kvr_live_REDACTED' \
  'https://api.kovira.app/v1/incidents?status=in_progress&priority=p1&limit=25'

Create an incident

Copycurl --fail-with-body -X POST \
  -H 'Authorization: Bearer kvr_live_REDACTED' \
  -H 'Content-Type: application/json' \
  --data '{"title":"Core switch unreachable","impact":"high","urgency":"high","source":"monitoring"}' \
  https://api.kovira.app/v1/incidents

Continue a cursor page

curl --get \
  -H 'Authorization: Bearer kvr_live_REDACTED' \
  --data-urlencode 'cursor=RETURNED_OPAQUE_CURSOR' \
  https://api.kovira.app/v1/cis

For SDK generation, use the complete public contract at https://api.kovira.app/docs/openapi.yaml.

15 · Lifecycle

Versioning policy

The path major is the compatibility boundary. Additive fields may appear within v1; clients should ignore unknown response fields. Breaking public changes use a new major version.

16 · Integration checklist

Before enabling production traffic

1. Pin the base origin to https://api.kovira.app/v1; do not derive internal /api paths.
2. Grant the smallest required scopes and store keys in a secrets manager.
3. Set connection and response deadlines; retry 429 and transient 5xx with jitter.
4. Only retry mutations when the operation is idempotent or carries a REST Idempotency-Key header.
5. Log X-Request-ID, status, and stable error code—never credentials or calendar tokens.
6. Treat cursors as opaque and validate Kovira-API-Version in integration tests.