Getting Started with Rekor

Rekor gives AI agents a persistent, structured place to store and query data — without migrations, infrastructure setup, or schema design upfront. Agents define their own schemas at runtime and start writing immediately.

Three Primitives

Everything in Rekor is built on three concepts:

Primitive	What it is
Collection	A JSON Schema defining a record type. Created at runtime — no migrations.
Record	A JSON document conforming to a collection's schema. Upsert by external ID for idempotency.
Relationship	A typed, directed link between two records with optional metadata. Queryable in any direction.

5-Minute Tutorial

This walkthrough creates a workspace, defines a schema, writes records, links them with a relationship, and queries the result.

1. Install and authenticate

npm install -g @rekor/cli
rekor login

2. Create a workspace and preview environment

All schema changes happen in preview first, then get promoted to production.

rekor workspaces create crm --name "CRM"
rekor workspaces create-preview crm --name "setup"

3. Define collections in preview

rekor collections upsert contacts \
  --workspace crm--setup \
  --name "Contacts" \
  --schema '{
    "type": "object",
    "required": ["name"],
    "properties": {
      "name": { "type": "string" },
      "email": { "type": "string" },
      "company": { "type": "string" }
    }
  }'

rekor collections upsert deals \
  --workspace crm--setup \
  --name "Deals" \
  --schema '{
    "type": "object",
    "required": ["title", "value"],
    "properties": {
      "title": { "type": "string" },
      "value": { "type": "number" },
      "stage": { "type": "string" }
    }
  }'

4. Promote to production

rekor workspaces promote crm --from crm--setup --dry-run
rekor workspaces promote crm --from crm--setup

5. Write records

rekor records upsert contacts --workspace crm \
  --external-id "c_001" --source crm \
  --data '{"name": "Jane Doe", "email": "jane@acme.com", "company": "Acme"}'

rekor records upsert deals --workspace crm \
  --external-id "d_001" --source crm \
  --data '{"title": "Enterprise Plan", "value": 50000, "stage": "negotiation"}'

6. Link records with a relationship

rekor relationships upsert --workspace crm \
  --rel-type "owns" \
  --source-collection contacts --source-id c_001 \
  --target-collection deals --target-id d_001

7. Query and traverse

# SQL query
rekor sql "SELECT data.title.:String as deal, CAST(data.value, 'Float64') as value FROM records FINAL WHERE workspace_id = {workspace_id:String} AND collection = 'deals' AND CAST(data.value, 'Float64') >= 10000 AND deleted = false ORDER BY value DESC" --workspace crm

# Aggregate
rekor sql "SELECT sum(CAST(data.value, 'Float64')) as pipeline_total FROM records FINAL WHERE workspace_id = {workspace_id:String} AND collection = 'deals' AND deleted = false" --workspace crm

# Traverse relationships
rekor relationships query --workspace crm \
  --collection contacts --record-id c_001 \
  --rel-type owns --direction outgoing

Interfaces

Three ways to interact with Rekor — all backed by the same API.

MCP Tools

Eleven MCP tools that AI agents use to manage workspaces, collections, records, relationships, and more. An agent typically starts with manage_workspace(list) to discover context.

Tool	Description
batch_operations	Execute multiple record, relationship, and collection operations atomically. All operations succeed or all fail. Use for transactions, multi-entity writes, or any case where consistency between operations is required. Max 1,000 operations.
manage_attachment	Manage file attachments on records. Filenames can include paths for folder structure (e.g. 'docs/guide.md', 'src/index.ts'). Upload returns a presigned URL — the agent uploads bytes directly.
manage_collection	Manage collection schemas. Actions: upsert, get, list, delete. Use list to discover what collections exist in a workspace.
manage_hook	Manage inbound webhook endpoints. Hooks accept Record-format JSON and upsert through the normal write path.
manage_record	Create, read, update, delete, or cancel individual records. Uses PUT for upsert. Supply external_id (and optional external_source) for idempotent writes from external systems — the internal UUID is auto-generated. Use record_id (internal UUID) for get/delete/cancel or to update a known record. Records may be archived (_archived: true in response) — archived records are read-only and cannot be upserted, but can be cancelled or deleted.
manage_relationship	Create, read, update, or delete relationships between records. Relationships are typed, directed links with optional metadata.
manage_trigger	Manage outbound triggers. Triggers fire HTTP POST to a URL when records or relationships change.
manage_workspace	Manage workspaces. Actions: create, get, list, delete, create_preview, list_previews. Start here to discover existing workspaces before operating. Note: schema changes (collections, triggers, hooks) can only be made in preview workspaces. Use create_preview to create a preview from a production workspace, then promote via CLI.
provider_adapter	Convert between LLM provider tool formats (openai, anthropic, google, mcp) and Record collections. Actions: import_tools (create collections from tool definitions), export_tools (export collections as tool definitions), import_tool_call (create a record from a tool call in provider format).
query_relationships	Query relationships for a specific record. Find related records by type and direction.
sql_query	Execute a read-only SQL query against workspace data. Tables: records, relationships, collections, workspaces, operations_log. Always include workspace_id = {workspace_id:String} and deleted = false in WHERE. Use FINAL after table name.

CLI Commands

The Rekor CLI (@rekor/cli) provides a complete command-line interface.

npm install -g @rekor/cli
rekor login

Command	Description
rekor attachments	Manage record attachments
rekor batch	Execute atomic batch operations (up to 1,000 operations)
rekor collections	Manage collections
rekor endpoints	Manage MCP Factory endpoints
rekor hooks	Manage inbound webhook endpoints
rekor login	Authenticate with Rekor
rekor logout	Remove stored authentication credentials
rekor providers	Import/export tool definitions between LLM providers and Record collections
rekor query-relationships	Query related records
rekor records	Manage records
rekor relationships	Manage relationships between records
rekor sql	Execute a read-only SQL query against workspace data
rekor tokens	Manage API tokens
rekor triggers	Manage outbound triggers
rekor workspaces	Manage workspaces

REST API

All endpoints accept and return JSON. Base URL:

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

Authenticate with a Bearer token in the Authorization header.

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

Integrations

Connect external systems, compose operations, and adapt to different AI providers.

Next Steps

• Skill — load Rekor's skill into any AI agent so it can use the CLI as its data layer.
• Environments — understand preview and production workspaces before deploying.
• Query — SQL queries, cross-workspace queries, filter DSL, sorting, and aggregation.
• Access Control — set up scoped API keys and organizations.