API Overview

Summary

Use the public application entry point for supported API interactions. Browser clients and external automation should not connect to private service addresses.

Fields / Parameters

Route family	Type	Description
`/auth/*`	Session	Sign-in and session refresh flows.
`/api/doc/*`	Documents and files	Metadata, dashboards, preferences, and stored assets.
`/api/sql/*`	Analytical query	Bounded query and transaction operations against governed analytical data, including the v1 framed result stream currently consumed by Query Workbench.
`/api/ai/*`	AI assistance	Supported assistant and generation requests.
`/api/jobs/*`	Background jobs	Inspect and stream worker jobs; submit or cancel only where the job type’s closed authorization policy permits it.
`/api/sentinel/*`	Alerts	Alert rules, events, and notification testing.
`/api/monitor/*`	Operations	Health, logs, and operational evidence.

Example

Browser requests normally authenticate with the HttpOnly session cookie. This non-browser example uses the supported Bearer-session alternative:

GET /api/jobs/j-7f3a91c2-d4e
Authorization: Bearer <session>
x-env-id: prod
x-tenant-id: tn-019ce6623fbe7905a1b3da30cd32ca68

Request format

Most write requests use JSON. Scope-sensitive requests include environment and tenant context. A long-running operation returns a job id rather than blocking until the work is finished.

SQL Query Stream v1 also receives a JSON request body. It requires Content-Type: application/json and the exact Accept value application/vnd.rokks.sql-query-stream+json; version=1.

Registration is not permission to submit a job. The Worker reconciles the authenticated identity with the environment and tenant headers, then applies a policy for the exact job type. Some authoring jobs are available to tenant members, destructive jobs require a tenant operator, and system-scoped jobs require a system owner and an explicit system scope. An authenticated mesh certificate identifies a service but grants only that service’s exact job-type allowlist. HTTP callers cannot request the internal PHYSICAL phase, and force is operator-only.

Response format

Ordinary routes return route-specific JSON. Check the HTTP status first, then consume only the fields documented for that route. For example, a successful job-detail request returns the job fields directly, together with its steps and current progress detail; an error response instead carries route error fields such as error and, where supplied, code.

The ROKKS browser application wraps many of its own requests in an internal ApiResponse object. That client-side object is not the HTTP wire format and external integrations must not parse responses as { success, status, parsedData, headers }.

SQL Query Stream v1 has its own explicit wire contract. Its successful response uses Content-Type: application/vnd.rokks.sql-query-stream+json; version=1 and contains length-prefixed JSON records rather than ordinary route JSON. A consumer must validate the complete v1 contract and reject EOF without a terminal record. Streamed rows remain provisional and are committed only by a valid complete or truncated terminal.

For worker jobs, subscribe to the supported event stream until the route-specific job status reaches DONE, ERROR, or CANCELLED. Use a single status lookup only to reconcile a stale or disconnected scoped observer; do not implement a polling loop.