HTTP API

Nines provides a tenant-scoped HTTP API for SLOs, critical user journeys and reviewed intent workflows. This guide covers common endpoints. The pre-release API can change. The versioned OpenAPI contract describes the core SLO, reviewed intent workflow and Datadog/New Relic native-result/catalog/draft operations listed in that file; other endpoints and complete resource schemas are not yet covered. It is OpenAPI 3.1.1, contract version 0.1.0-alpha.2. Nines does not yet provide Swagger UI.

Authentication and tenant scope

Use your Nines server URL, an authorized API key and the tenant ID selected by your administrator. Membership and roles are enforced by the server; a tenant header alone does not grant access. Keep credentials in a secret manager and use HTTPS outside loopback.

# Set NINES_URL, NINES_TENANT and NINES_API_KEY in your environment.
curl --fail-with-body \
  -H "Authorization: Bearer $NINES_API_KEY" \
  -H "X-Nines-Tenant: $NINES_TENANT" \
  "$NINES_URL/api/slos"

See identity and tenants for SSO, sessions and roles. Provider credentials and Mimir organization mappings are trusted server configuration, separate from the Nines tenant header.

SLOs and critical user journeys

Validate, plan and apply YAML

POST /api/resources/validate checks a versioned YAML resource. POST /api/resources/plan plans it against the selected tenant. Both use Content-Type: application/yaml. Validation does not prove telemetry exists or rules are active.

curl --fail-with-body -X POST \
  -H "Authorization: Bearer $NINES_API_KEY" \
  -H "X-Nines-Tenant: $NINES_TENANT" \
  -H "Content-Type: application/yaml" \
  --data-binary @examples/request-success.slo.yaml \
  "$NINES_URL/api/resources/plan"

After review and authorization, POST /api/resources/apply accepts the YAML and requires a quoted If-Match revision; "0" creates a resource. Use the current revision for edits and review the new state after a conflict. Applying can trigger owner-configured automatic rule delivery; it does not prove rule evaluation or SLI health. See SLO editing and automatic deployment.

Agent workflows and audit

Each workflow operation has version, digest and authorization requirements. See headless workflows and approval and rollback. The Go client provides typed calls; MCP describes agent tools.

Contract versioning and limits

The contract source is versioned separately from the YAML resource API version nines.dev/v1alpha1. Existing HTTP routes are not URL-versioned. The specification documents the bearer-token integration profile; browser sessions have separate CSRF requirements. Read the spec's path list rather than assuming it covers every server endpoint. Some response and manifest objects deliberately remain open until their full schemas are specified; server validation remains authoritative.

Contract tests check documented routes, references and key request and response fields against the server's Go types. Expand the specification and those tests together when adding coverage or changing a documented contract. A future stable release needs a published compatibility and deprecation policy and complete schema/endpoint coverage.

Native provider SLOs

These read-only operations use the configured Datadog or New Relic native destination, not client-selected credentials or routes. They are included in the versioned contract.

• GET /api/slos/{id}/native-results?from=RFC3339&to=RFC3339: read the exact published current revision. Past, whole-second ranges are limited to 31 days. New Relic clips inward to complete buckets; returned from/to show the effective range. The response is independent from Nines measurements, with nullable attainment/budget, history, provenance and limitations.
• GET /api/connections/{connection}/native-slos: bounded vendor catalog. New Relic is restricted to the configured associated entity/account; Datadog to the configured credential scope. Catalogs exceeding their bounds fail rather than claim completeness.
• GET /api/connections/{connection}/native-slo-draft?nativeID=...&name=...&project=...&service=...: prepare YAML for a new experimental Nines SLO. This does not save, adopt, synchronize or modify the vendor SLO. Review through the normal plan/apply workflow. Alerts, corrections, notifications and vendor ownership are not imported.

Datadog, New Relic, VictoriaMetrics, Dash0 and Google Cloud share the Nines resource API; there is no separate public API namespace per vendor. The provider capability guide describes query languages, native publication and supported subsets. Connection management and rule plan/apply operations are not yet fully covered by the partial OpenAPI contract.

See native results and reviewed import for CLI examples and supported subsets.

Remote agent transport

The optional OAuth-protected remote MCP adapter is a separate process/endpoint, not /mcp on the Nines HTTP API server. It reuses these tenant-scoped resource endpoints with distinct server-held credentials per client/user. JSON-RPC framing follows MCP; the versioned RemoteMCP configuration schema is separate from this partial OpenAPI contract.

Burn-window duration inputs

Versioned YAML resources accept shortWindow: 5m and longWindow: 1h in burn-rate policies. JSON resource input accepts the same strings. Legacy numeric shortWindowSeconds and longWindowSeconds remain accepted, with exactly one representation per window. Runtime JSON responses continue to return numeric seconds. See measurement duration syntax.