Skip to content
OWOX Data Marts

OpenAPI and Swagger UI

OWOX Data Marts exposes OpenAPI specifications and Swagger UI for the HTTP API.

For OWOX Data Marts Cloud at https://app.owox.com, API documentation is available at:

For a self-managed OWOX Data Marts deployment at https://your-owox.example.com, use:

  • https://your-owox.example.com/api/openapi.json
  • https://your-owox.example.com/api/openapi.yaml
  • https://your-owox.example.com/api/swagger-ui

Use OpenAPI and Swagger UI to inspect available endpoints, request schemas, and response schemas.

Relationship to other API tools

Section titled “Relationship to other API tools”
  • Use owox-ctl when you want JSON terminal commands for automation or AI agents.
  • Use @owox/api-client when you build TypeScript or JavaScript integrations.
  • Use OpenAPI and Swagger UI when you need to inspect or integrate with the raw HTTP API directly.

Authenticated API requests require API key-based authentication. Start with API Keys before calling protected endpoints.

Raw HTTP API contract

Section titled “Raw HTTP API contract”

Raw HTTP API requests do not send the copied owox_key_... value directly. owox-ctl and @owox/api-client parse that value and perform the token exchange automatically.

If you integrate with the HTTP API directly, parse the copied API key value first:

  1. Remove the owox_key_ prefix.
  2. Base64url-decode the remaining value.
  3. Parse the decoded JSON object.
  4. Read apiOrigin, apiKeyId, and apiKeySecret.

Exchange the API Key ID and API Key Secret for an access token:

POST /api/auth/api-keys/exchange
Content-Type: application/json
X-OWOX-Api-Key-Id: <apiKeyId>


{
  "apiKeySecret": "<apiKeySecret>"
}

Send this request to the decoded apiOrigin, for example https://app.owox.com/api/auth/api-keys/exchange.

The response contains an access token:

{
  "accessToken": "<accessToken>"
}

Use that access token when calling protected endpoints:

GET /api/external/http-data/data-marts/<dataMartId>.ndjson
x-owox-authorization: Bearer <accessToken>
X-OWOX-Api-Key-Id: <apiKeyId>

Keep X-OWOX-Api-Key-Id on protected requests that use an access token created from an API key. The server binds API-key access tokens to their API Key ID.

The HTTP Data API can also stream a saved report’s data — applying the report’s stored filters, aggregations, date buckets, and sorting — instead of a Data Mart’s raw output. Pass an optional limit query parameter to cap rows:

GET /api/external/http-data/reports/<reportId>.ndjson
x-owox-authorization: Bearer <accessToken>
X-OWOX-Api-Key-Id: <apiKeyId>

Both endpoints return an x-owox-run-id response header identifying the created run; use it to look up the run (and its executed query) through the run history endpoint.

Compatibility

Section titled “Compatibility”

The same client and OWOX Data Marts server version is supported. Different versions are best effort.