API Reference

The 9thSense API is a REST API. All requests and responses use JSON unless otherwise noted (file upload endpoints use multipart/form-data; export endpoints return text/csv; report and file endpoints return their native content type).

Base URL

https://api.9thsense.ai

All endpoints are versioned under /v1/.

Versioning

The current API version is v1. All stable endpoints are prefixed /v1/. Breaking changes will be introduced under a new version prefix.

Authentication

Every request (except /healthz, /docs, /openapi.json, /redoc, /metrics) must include a valid API key in the X-Api-Key header:

X-Api-Key: zk_<prefix>_<secret>

See Authentication for full details on key format, scopes, and key management.

Content Types

Pagination

List endpoints accept limit and offset query parameters where applicable.

Endpoints that do not support offset accept only limit.

Rate Limits

Requests are rate-limited at 200 requests per minute per tenant. When the limit is exceeded the gateway returns:

HTTP 429 Too Many Requests

The limit resets on a rolling 60-second window.

Idempotency

Write endpoints (POST, PATCH) support idempotent retries via the Idempotency-Key header. Supply any unique string (UUID recommended). If the same key is replayed within 24 hours the original response is returned without re-executing the operation.

Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000

Error Format

All errors follow a consistent JSON envelope:

{
  "detail": "Human-readable description of the error"
}

Open Paths (No Auth Required)

The following paths bypass authentication entirely:

• GET /healthz
• GET /docs
• GET /openapi.json
• GET /redoc
• GET /metrics