API conventions

ReportPlane separates the public Management API, the private interactive console API, and runtime origins while keeping a common JSON response envelope.

Origins#

• Public Management API: https://app.reportplane.com/management/v1
• Interactive console: private session endpoints used only by the ReportPlane web application
• Ingest runtime: https://ingest.reportplane.com
• Query runtime: https://query.reportplane.com

Authentication#

The public Management API uses scoped rp_mgmt_... Management Tokens. The interactive console API uses the signed-in user's session JWT and is not the supported machine-automation contract. Runtime endpoints use ingest/query clients, runtime API Keys, JWT, mTLS, and configured policy combinations.

Browser access#

The canonical POST /ingest and POST /query runtime endpoints accept cross-origin browser requests from any origin. Their preflight responses allow Authorization and Content-Type; runtime cookies and credentialed CORS are not supported. The caller must still present a valid runtime credential and passes the same capability, resource, network, schema/filter, quota and usage checks as every non-browser client.

This public CORS boundary does not include Console, Management, internal, discovery, WebSocket, public Dataset or share endpoints. Those surfaces retain their existing exact-origin or protocol-specific policy.

Success envelope#

{
  "error": false,
  "data": {}
}

Error envelope#

{
  "error": true,
  "message": "validation explanation"
}

error is a JSON boolean. Older examples that show null for a successful error field do not match the canonical response writer.

JSON and content types#

Send Content-Type: application/json for JSON management and query requests. HTTP ingest also accepts application/x-ndjson and application/ndjson.

IDs, names, and keys#

Resource IDs are stable internal references. Display names help people. Data-model and Analytics API keys are stable runtime-facing identifiers where the endpoint supports them.

Do not assume a display name is globally unique across workspaces or projects.

List scoping#

Many Management API list endpoints require project_id as a query parameter. The backend verifies both the Management Token's workspace/project restriction and the token owner's current access.

Dates and time#

Use UTC RFC 3339 timestamps such as 2026-08-02T12:00:00Z unless an endpoint explicitly documents a different numeric representation.