API overview

The ConsciousLab API is organised around REST. It accepts JSON request bodies, returns JSON, and uses standard HTTP verbs and status codes. Real-time streams use WebSocket and server-sent events. Institutional trading uses FIX 4.4.

Base URLs

The automatic base URL routes to your workspace's region. Use the regional URL if you need guarantees about where requests terminate.

Versioning

The major version is in the path. Within v1 we add fields and endpoints but never remove or rename them. Breaking changes ship in a new major version with at least 12 months of overlap. Subscribe to the changelog to hear about additions.

Pagination

List endpoints use cursor pagination:

curl "https://api.consciouslab.xyz/v1/payments/invoices?limit=50&status=open" \
  -H "Authorization: Bearer $CL_API_KEY"

{
  "data": [{ "id": "inv_2049", "number": "INV-2049", "status": "open" }],
  "next_cursor": "c_eyJpZCI6Imludl8yMDAxIn0",
  "has_more": true
}

Pass cursor=<next_cursor> to fetch the next page. limit defaults to 25 and accepts up to 200.

Idempotency

Every POST accepts an Idempotency-Key header. If you retry a request with the same key within 24 hours, you get the original response instead of a second side effect. The TypeScript SDK sets this header for you.

curl https://api.consciouslab.xyz/v1/payments/refunds \
  -H "Authorization: Bearer $CL_API_KEY" \
  -H "Idempotency-Key: 9c2b0d4e-rfd-0193" \
  -d invoice=inv_2049 -d amount=182.40

Rate limits

Event ingest has its own limits; see Events. Every response includes RateLimit-Remaining and RateLimit-Reset headers. Exceeding the limit returns 429 with a Retry-After header in seconds.

Errors

Errors use conventional status codes and a consistent body:

{
  "error": {
    "code": "validation_failed",
    "message": "amount must be greater than 0",
    "field": "amount",
    "request_id": "req_01J9ZRB2K7"
  }
}

Include the request_id when you contact support.