Report App API

Report App API for programatic and 3rd-party access to a single organization's reporting data using a long-lived report app key.

A report app key grants a 3rd-party program or AI agent read-only access to everything an organization exposes (schema, reports, experiments, chats, query results and history) plus the ability to run queries. Keys are bound to exactly one organization and one user, and are denied access to every endpoint that is not explicitly listed below.

Report app keys are created, listed and deleted by a logged-in organization user through the report app key management endpoints (see Managing Report App Keys below). This page covers how a key authenticates and which endpoints it may call.

API Endpoint

All calls are made on the standard report endpoint:

https://report-api-prod.data-cortex.com/

Authentication

A report app key authenticates the request. Present the key using one of the following, in order of precedence:

• X-Report-App-Key header (preferred)
• report_app_key query parameter
• report_app_key body property

GET /api/1/org/:org_id/schema
X-Report-App-Key: <report_app_key>

The key is bound to a single organization. The org_id in the request path must match the organization the key belongs to.

Notes

• Report app keys are read-only except for the query-creation endpoints listed below.
• A key never has organization-admin or super-admin rights; admin endpoints always reject keys.
• Queries created by a report app key cannot expire sooner than the key's configured min_expire_secs, so cached results stay valid for at least that long.
• Each successful call updates the key's last_used timestamp.

Responses

403 Forbidden

err - string - "no_org_access" - The key is missing, invalid, or not bound to the requested organization.

Get Report App Info

Return the identity of the report app key itself: the organization it is bound to and its name. This is the only endpoint that does not require org_id in the path, so a key holder can use it to discover which organization the key belongs to.

GET /api/1/report_app

Request Arguments

None (authenticated by the report app key).

Responses

200 OK

org_id - number - Organization ID the key is bound to.

report_app_name - string - Name of the report app key.

403 Forbidden

err - string - "no_org_access" - The key is missing or invalid.

Run Query

Submit a SQL query for the organization. Identical queries are coalesced and cached; clients should long poll for the result.

POST /api/1/org/:org_id/query

Request Arguments

org_id - number - Organization ID (path)

sql - string - SQL query string

idempotent_key - string - Client-generated unique key (UUID) used to deduplicate submissions.

expire_datetime - string - optional - ISO datetime when this query should expire. Used to cache subsequent identical requests. For report app keys this is raised to at least the key's min_expire_secs in the future.

Responses

201 Created

query_id - number - Query ID to poll for the result.

409 Conflict

err - string - "duplicate_query" - A query with the same idempotent_key already exists.

Get Query

Retrieve the status and result of a query. Set long_poll to wait for completion.

GET /api/1/org/:org_id/query/:query_id

Request Arguments

org_id - number - Organization ID (path)

query_id - number - Query ID (path)

long_poll - boolean - optional - When true, the request blocks until the query completes or the server times out. Resubmit the identical request on a gateway timeout.

Responses

200 OK

query_id - number - Query ID

org_id - number - Organization ID

sql - string - SQL query that was run

create_ts - string - ISO datetime when the query was created

is_done - boolean - Whether the query has finished

result - object - Result object, NULL until the query succeeds

• keys - list of string - Column keys of the result

• value_arrays - list of list of values - Result rows; elements are strings or numbers

error - object - Error detail from the analytic store, NULL when successful

report_app_name - string - Name of the report app key that created the query, NULL when the query was created by a user.

404 Not Found

Query not found for that organization.

Query History

List the most recent user-requested queries for the organization (up to 100).

GET /api/1/org/:org_id/query/history

Request Arguments

org_id - number - Organization ID (path)

search - string - optional - Filters on the requester display name or the SQL text.

Responses

200 OK

query_list - list of objects - List of queries

• query_id - number - Query ID

• sql - string - SQL query that was run

• create_ts - string - ISO datetime when the query was created

• org_id - number - Organization ID

• org_name - string - Organization name

• display_name - string - Requester display name (falls back to email)

• report_app_name - string - Name of the report app key that created the query, NULL for user-created queries.

Download Query CSV

Get a temporary signed URL to download the query result as CSV.

GET /api/1/org/:org_id/query/:query_id/csv_download

Request Arguments

org_id - number - Organization ID (path)

query_id - number - Query ID (path)

Responses

200 OK

url - string - Signed URL for the CSV download.

412 Precondition Failed

err - string - "no_csv" - The query has no CSV result available.

404 Not Found

Query not found for that organization.

Run Report Query

Run a saved report by ID, substituting any report parameters.

POST /api/1/org/:org_id/report/:report_id/query

Request Arguments

org_id - number - Organization ID (path)

report_id - number - Report ID (path)

parameters - object - Report parameter values (keyed by parameter name) substituted into the saved report's SQL template. Required, may be an empty object for reports without parameters.

Responses

201 Created

query_id - number - Query ID to poll via Get Query.

404 Not Found

err - string - "report_not_found" - No such report for that organization.

Get Schema

List the tables and columns available to the organization.

GET /api/1/org/:org_id/schema

Request Arguments

org_id - number - Organization ID (path)

Responses

200 OK

table_list - list of objects - Tables available for querying, including their columns.

List Reports

List the saved reports for the organization.

GET /api/1/org/:org_id/report

Request Arguments

org_id - number - Organization ID (path)

Responses

200 OK

report_list - list of objects - Saved reports for the organization.

Report History

List the run history for a saved report.

GET /api/1/org/:org_id/report/:report_id/history

Request Arguments

org_id - number - Organization ID (path)

report_id - number - Report ID (path)

Responses

200 OK

Run history for the requested report.

List Auto Reports

List the auto (scheduled) reports for the organization.

GET /api/1/org/:org_id/auto_report

Request Arguments

org_id - number - Organization ID (path)

Responses

200 OK

auto_report_list - list of objects - Auto reports for the organization.

Query Auto Report

Run an auto report and return a query to poll.

GET /api/1/org/:org_id/auto_report/:auto_report_id/query

Request Arguments

org_id - number - Organization ID (path)

auto_report_id - number - Auto report ID (path)

Responses

200 OK

Query information to poll via Get Query.

Cached Auto Report

Return the most recent cached result for an auto report.

GET /api/1/org/:org_id/auto_report/:auto_report_id/cached

Request Arguments

org_id - number - Organization ID (path)

auto_report_id - number - Auto report ID (path)

Responses

200 OK

The cached auto report result.

List Experiments

List experiments for the organization.

GET /api/1/org/:org_id/experiment

Request Arguments

org_id - number - Organization ID (path)

Responses

200 OK

experiment_list - list of objects - Experiments for the organization.

Get Experiment

Get a single experiment by ID.

GET /api/1/org/:org_id/experiment/:experiment_id

Request Arguments

org_id - number - Organization ID (path)

experiment_id - number - Experiment ID (path)

Responses

200 OK

The requested experiment.

List AI Chats

List AI chats for the organization.

GET /api/1/org/:org_id/ai_chat

Request Arguments

org_id - number - Organization ID (path)

Responses

200 OK

chat_list - list of objects - AI chats for the organization.

Get AI Chat

Get a single AI chat, including its messages.

GET /api/1/org/:org_id/ai_chat/:ai_chat_id

Request Arguments

org_id - number - Organization ID (path)

ai_chat_id - number - AI chat ID (path)

Responses

200 OK

The requested AI chat and messages.

Stream AI Chat

Stream an AI chat response.

GET /api/1/org/:org_id/ai_chat/:ai_chat_id/stream

Request Arguments

org_id - number - Organization ID (path)

ai_chat_id - number - AI chat ID (path)

Responses

200 OK

A streamed AI chat response.

Managing Report App Keys

Report app keys are managed by a logged-in organization user (a normal session_key, see Report Authentication API). These management endpoints do not accept a report app key for authentication. Regular users manage only their own keys; organization admins see all keys in the organization.

List Report App Keys

List the report app keys for the organization.

GET /api/1/org/:org_id/report_app_key

Request Arguments

org_id - number - Organization ID (path)

Responses

200 OK

report_app_key_list - list of objects - Report app keys

• report_app_key - string - The key value

• report_app_name - string - Key name

• min_expire_secs - number - Minimum query expiration in seconds

• create_ts - string - ISO datetime the key was created

• last_used - string - ISO datetime the key was last used, NULL if never used

• user_email - string - Email of the user that owns the key

• user_display_name - string - Display name of the owner (falls back to email)

Create Report App Key

Create a new report app key.

POST /api/1/org/:org_id/report_app_key

Request Arguments

org_id - number - Organization ID (path)

report_app_name - string - Key name (must be unique within the organization)

min_expire_secs - number - optional - Minimum query expiration in seconds. Clamped between 60 and 2592000; defaults to 3600.

Responses

201 Created

report_app_key - string - The generated key value

report_app_name - string - Key name

min_expire_secs - number - Effective minimum query expiration in seconds

400 Bad Request

err - string - "invalid_report_app_name" - The name was empty.

409 Conflict

err - string - "duplicate_report_app_name" - A key with that name already exists.

Delete Report App Key

Delete a report app key.

DELETE /api/1/org/:org_id/report_app_key

Request Arguments

org_id - number - Organization ID (path)

report_app_key - string - The key value to delete

Responses

200 OK

Key deleted.

404 Not Found

err - string - "report_app_key_not_found" - No such key for that organization.