REST API

The Rekor REST API provides full access to workspaces, collections, records, relationships, hooks, triggers, and batch operations. All endpoints accept and return JSON. The CLI and MCP server are both thin wrappers over this API.

Base URL

https://api.rekor.pro/v1/{workspace_id}

Most endpoints are scoped to a workspace. Token management and vault endpoints are account-level and don't require a workspace ID.

Authentication

All requests require a Bearer token in the Authorization header:

curl https://api.rekor.pro/v1/my-workspace/collections \
  -H "Authorization: Bearer rec_your_token_here"

Create tokens via the CLI (rekor tokens create) or the POST /v1/tokens endpoint. Each token is scoped by grants — workspace, collection, environment, and permission level. See Access Control for details.

Request and Response Format

All request bodies are JSON. All responses return JSON with one of two shapes:

Success — single resource

{
  "id": "01926f3a-...",
  "collection": "contacts",
  "data": { "name": "Jane Doe", "email": "jane@acme.com" },
  "created_at": "2026-03-25T10:00:00Z",
  "updated_at": "2026-03-25T10:00:00Z"
}

Success — list with pagination

{
  "data": [ ... ],
  "meta": {
    "total": 142,
    "limit": 50,
    "offset": 0
  }
}

Error

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid filter: unknown operator 'foo'",
    "details": [ ... ]
  }
}

Error Codes

HTTP Status	Code	Meaning
400	`VALIDATION_ERROR`	Invalid request body, query params, or filter syntax
401	`UNAUTHORIZED`	Missing or invalid token
403	`FORBIDDEN`	Token lacks required permission or scope
404	`NOT_FOUND`	Resource does not exist
409	`CONFLICT`	Duplicate external_id or version conflict
429	`RATE_LIMITED`	Too many requests — retry after `Retry-After` seconds
500	`INTERNAL_ERROR`	Unexpected server error

Pagination

List and query endpoints accept limit and offset parameters:

Parameter	Default	Maximum
`limit`	50	1,000
`offset`	0	—

The meta.total field in the response tells you the total number of matching records, so you can calculate pages.

# Page 1
GET /v1/crm/records/contacts?limit=50&offset=0

# Page 2
GET /v1/crm/records/contacts?limit=50&offset=50

Upsert Semantics

PUT endpoints are upserts. If a record with the given external_id and external_source exists, it's updated. Otherwise, a new record is created. This makes all writes idempotent — safe to retry without duplicating data.

Endpoints

Section	Description
Workspaces	Workspaces API endpoints
Collections	Collections API endpoints
Records	Records API endpoints
Relationships	Relationships API endpoints
Attachments	Attachments API endpoints
Hooks	Hooks API endpoints
Triggers	Triggers API endpoints
Batch	Batch API endpoints
Providers	Providers API endpoints
Environments	Environments API endpoints