Skip to main content

API Conventions

This page documents API conventions that help you integrate safely and debug issues quickly.

For endpoint-specific details, use the API Reference.

Base URL and versioning​

  • Base URL (production): https://app.orqio.io/public
  • Versioning: Orqio endpoints are versioned under /api/v1

Content types​

  • Requests and responses are JSON unless documented otherwise in the API reference.
  • For JSON requests, send Content-Type: application/json.

Authentication headers​

Customer-facing API endpoints use API key authentication:

  • x-api-key: pk_...
  • Authorization: Bearer pk_...

See Authentication.

Correlation and request IDs​

Orqio includes a request identifier in responses:

  • Response header: X-Request-Id

You can also send your own correlation identifier:

  • Request header: x-correlation-id

Recommendation:

  1. Generate a UUID per incoming request in your system.
  2. Send it as x-correlation-id to Orqio.
  3. Log both your correlation ID and the returned X-Request-Id for support/debugging.

Organization/workspace context​

Customer-facing endpoints express context in the URL (for example, /orgs/{orgId}/workspaces/{workspaceId}/...). Use the API reference as the source of truth for each endpoint’s required path parameters.

Status codes (general guidance)​

The API reference is authoritative, but as a baseline:

  • 2xx: success
  • 4xx: request/credential issue (client-side)
  • 5xx: transient server-side issue (retry with backoff)

If you receive 429 Too Many Requests, slow down and retry with exponential backoff.