REST API Overview

The DataRecs REST API provides full programmatic access to the platform.

Full reference

This page covers the essentials — authentication, validation, errors, and rate limiting. For every endpoint, request/response schema, and field:

• Browse the API Reference right here in these docs, generated from the same committed OpenAPI spec our contract-testing harness checks against shipped core-api — it can’t silently drift out of sync.
• Try it live at /docs — an interactive Swagger UI served directly by the API. Paste your API key in once (top right, “Authorize”) and execute real requests against your own tenant from the browser.

Base URL

https://api.datarecs.io

The API is served at the root of your API host — there is no version path segment. If your tenant is pinned to a specific cell you may also use that cell’s host directly (for example https://api.<your-cell>.datarecs.io); both route to the same API.

Authentication

All requests require a Bearer token in the Authorization header:

curl -H "Authorization: Bearer $DATARECS_API_KEY" \
  https://api.datarecs.io/workspaces

API keys are scoped to your tenant and can be created in the Console or via Terraform. A request may carry either an Authorization: Bearer API key or the session cookie set by the Console — not both; sending both is rejected.

Common endpoints

Method	Path	Description
GET	/workspaces	List workspaces
POST	/workspaces	Create a workspace
GET	/connections	List connections
POST	/connections	Create a connection
GET	/jobs	List reconciliation jobs
POST	/jobs	Create a job
POST	/jobs/{jobId}/runs/trigger?workspaceId={id}	Trigger a job run
GET	/jobs/{jobId}/runs?workspaceId={id}	List run history for a job
GET	/jobs/{jobId}/runs/{runId}?workspaceId={id}	Get a single run

Most job- and run-scoped endpoints require a workspaceId query parameter that identifies the workspace the resource belongs to; the request is rejected with 400 if it is omitted where required.

Request validation

Request bodies and query parameters are strictly validated. Unknown fields are rejected — a body or query string containing a parameter the endpoint does not declare returns 400 Bad Request. Send only the documented fields. Request bodies are also size-bounded (1 MiB by default); an oversized body is rejected.

Error format

Validation and other 4xx/5xx errors use the standard NestJS error shape:

{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}

message may be a string or an array of field-level validation messages. A few endpoints return a typed error body instead — see Limits & Quotas for the QUOTA_EXCEEDED (403) and RATE_LIMITED (429) bodies.

Rate limiting

REST API requests are rate-limited per tenant, as a sustained requests-per-second budget that depends on your plan (Free 5 req/s, Standard 50 req/s). A few endpoints — notably triggering runs and the unauthenticated authentication endpoints — have their own tighter, plan-independent limits.

When you exceed a limit you receive 429 with a Retry-After header (seconds). See Limits & Quotas for the full behaviour and the response body.