REST API Specification

REST

The running service serves Swagger UI at:

http://localhost:18081/docs

The full REST API includes dashboard auth, API key management, meter operations, usage ingestion, usage querying, direct CSV exports, queued export jobs, alerts, system stats, and operational endpoints.

The direct CSV endpoints return files from the request:

• GET /v1/usages/export
• POST /v1/usages/export
• GET /v1/usageevents/export
• POST /v1/usageevents/export

Queued export jobs are available for longer-running bucketed exports:

• POST /v1/exports
• GET /v1/exports
• GET /v1/exports/{id}
• POST /v1/exports/{id}/cancel
• POST /v1/exports/{id}/retry
• GET /v1/exports/{id}/download

Alert rules are available in the full REST API and dashboard:

• POST /v1/alerts/destinations
• GET /v1/alerts/destinations
• PUT /v1/alerts/destinations/{id}
• DELETE /v1/alerts/destinations/{id}
• POST /v1/alerts/destinations/{id}/webhook-secret/rotate
• POST /v1/alerts
• GET /v1/alerts
• GET /v1/alerts/events
• GET /v1/alerts/{id}
• PUT /v1/alerts/{id}
• DELETE /v1/alerts/{id}
• POST /v1/alerts/{id}/evaluate

gRPC

Open Spanner also exposes a gRPC usage ingestion service on OPEN_SPANNER_GRPC_ADDR.

The first gRPC surface is intentionally scoped to trusted backend ingestion:

• CreateUsage
• CreateUsageBulk
• StreamUsage

gRPC clients authenticate with the same API keys used by the REST API. Send the key in request metadata with authorization: Bearer <key>, x-open-spanner-api-key, or x-api-key.

The protobuf schema lives in proto/open_spanner/v1/usage.proto.