API Reference Overview

NullSpend exposes a REST API for cost tracking, budget management, and human-in-the-loop workflows. All endpoints live under https://nullspend.dev/api/.

Authentication

NullSpend uses two authentication modes depending on the endpoint. For key lifecycle and caching details, see Authentication.

API Key (agent/SDK use)

Pass your API key in the X-NullSpend-Key header:

X-NullSpend-Key: ns_live_sk_...

API keys are created in the dashboard and identified by a ns_key_ prefix. The raw key is shown only once at creation. See API Keys API for management endpoints.

Session (dashboard use)

Session-authenticated endpoints require a browser session cookie from the NullSpend dashboard. These endpoints power the dashboard UI and are not callable from external scripts without a valid session.

Endpoint Auth Summary

ID Formats

All NullSpend IDs use the ns_ prefix followed by a type identifier and a UUID:

Error Format

All errors follow a consistent shape:

{
  "error": {
    "code": "machine_readable_code",
    "message": "Human-readable description.",
    "details": null
  }
}

Validation errors include field-level issues in details:

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed.",
    "details": {
      "issues": [
        { "path": ["fieldName"], "message": "Expected number, received string" }
      ]
    }
  }
}

See Error Reference for the full error catalog.

Pagination

List endpoints use cursor-based pagination. The response includes a cursor field — pass it as the cursor query parameter to fetch the next page.

{
  "data": [...],
  "cursor": { "createdAt": "2026-03-15T10:00:00.000Z", "id": "ns_evt_..." }
}

• limit controls page size (default varies by endpoint, max 100)
• cursor is a JSON-encoded object containing createdAt and id
• When cursor is null, there are no more results
• Pagination is forward-only, sorted by createdAt DESC

Rate Limiting

For enforcement order and failure modes, see Rate Limits.

API-key-authenticated endpoints return rate limit headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 97
X-RateLimit-Reset: 1711036800000

When the limit is exceeded, the endpoint returns 429 Too Many Requests with a Retry-After header (in seconds).

Idempotency

POST endpoints that accept API key auth support idempotent requests. Pass an Idempotency-Key header or include idempotencyKey in the request body. Duplicate requests return 200 with the original result instead of creating a new resource.

Versioning

For the version resolution chain and strategy, see Versioning.

Responses include a NullSpend-Version header indicating the API version:

NullSpend-Version: 2026-04-01