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 document type. Created at runtime — no migrations.
Document	A JSON document conforming to a collection's schema. Upsert by external ID for idempotency.
Relationship	A typed, directed link between two documents with optional metadata. Queryable in any direction.

5-Minute Tutorial

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

1. Install and authenticate

npm install -g @rekor/cli
rekor login

2. Create a database and preview environment

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

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

3. Define collections in preview

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

rekor collections upsert deals \
  --database 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 databases promote crm --from crm--setup --dry-run
rekor databases promote crm --from crm--setup

5. Write documents

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

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

6. Link documents with a relationship

rekor relationships upsert --database 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 documents WHERE database_id = {database_id:String} AND collection = 'deals' AND CAST(data.value, 'Float64') >= 10000 AND deleted = false ORDER BY value DESC" --database crm

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

# Traverse relationships
rekor relationships query --database crm \
  --collection contacts --document-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 databases, collections, documents, relationships, and more. An agent typically starts with manage_database(list) to discover context.

Tool	Description
batch_operations	Execute multiple document, 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 documents. 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 database.
manage_database	Manage databases. Actions: create, get, list, delete, create_preview, list_previews. Start here to discover existing databases before operating. Note: schema changes (collections, triggers, hooks) can only be made in preview databases. Use create_preview to create a preview from a production database, then promote via CLI.
manage_document	Create, read, update, delete, or cancel individual documents. Uses PUT for upsert. Supply external_id (and optional external_source) for idempotent writes from external systems — the internal UUID is auto-generated. Use document_id (internal UUID) for get/delete/cancel or to update a known document. Documents may be archived (_archived: true in response) — archived documents are read-only and cannot be upserted, but can be cancelled or deleted.
manage_hook	Manage inbound webhook endpoints. Hooks accept Record-format JSON and upsert through the normal write path.
manage_relationship	Create, read, update, or delete relationships between documents. Relationships are typed, directed links with optional metadata.
manage_trigger	Manage outbound triggers. Triggers fire HTTP POST to a URL when documents or relationships change.
provider_adapter	Convert between LLM provider tool formats (openai, anthropic, google, mcp) and Document collections. Actions: import_tools (create collections from tool definitions), export_tools (export collections as tool definitions), import_tool_call (create a document from a tool call in provider format).
query_relationships	Query relationships for a specific document. Find related documents by type and direction.
sql_query	Execute a read-only SQL query against database data. Tables: documents, relationships, collections, databases, operations_log. Always include database_id = {database_id:String} and deleted = false in WHERE. Queries return the latest version of each row automatically.

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 document attachments
rekor batch	Execute atomic batch operations (up to 1,000 operations)
rekor collections	Manage collections
rekor databases	Manage databases
rekor debug	Platform-admin debug commands (requires platform:admin grant)
rekor documents	Manage documents
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 documents
rekor relationships	Manage relationships between documents
rekor report-bug	Submit a report to the Rekor triage queue (deduplicated)
rekor sql	Execute a read-only SQL query against database data
rekor status	Show auth, connectivity, and CLI version diagnostics
rekor tokens	Manage API tokens
rekor triggers	Manage outbound triggers
rekor update	Update the Rekor CLI to the latest published version
rekor whoami	Show the authenticated identity

REST API

All endpoints accept and return JSON. Base URL:

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

Authenticate with a Bearer token in the Authorization header.

Section	Description
Databases	Databases API endpoints
Collections	Collections API endpoints
Documents	Documents 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

• Get Started — install the Rekor skill into your agent with one command and have it set everything up for you.
• Skill — read the full skill content used by AI agents to drive Rekor via the CLI.
• Environments — understand preview and production databases before deploying.
• Query — SQL queries, cross-database queries, filter DSL, sorting, and aggregation.
• Access Control — set up scoped API keys and organizations.