Salta ai contenuti
Rokks Docs

API Overview

Questi contenuti non sono ancora disponibili nella tua lingua.

API Overview

Section titled “API Overview”

Summary

Section titled “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

Section titled “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

Section titled “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: tenant-a

Request format

Section titled “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

Section titled “Response format”

Ordinary API wrappers expose a common response envelope:

type ApiResponse = {
  success: boolean;
  status:  number;
  parsedData: unknown | null;
  headers: Record<string, string>;
};

SQL Query Stream v1 is an explicit exception. Its successful response uses Content-Type: application/vnd.rokks.sql-query-stream+json; version=1 and contains length-prefixed JSON records rather than an ApiResponse envelope. 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.

Always check success before using parsedData from an ordinary response. For worker jobs, subscribe to the supported event stream until the 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.

Section titled “Related”