API Reference
The SwarmRecall REST API is organized around resource modules. All endpoints accept and return JSON. Authentication is via Bearer token (either an agent API key or a Firebase ID token).
Base URL: your self-hosted API, such as http://localhost:3300. The hosted service has been discontinued.
Authentication
Protected requests must include an Authorization header. Registration and health checks are public:
Authorization: Bearer <token>Agent API keys are used for agent-to-service calls. Firebase ID tokens are used for dashboard (owner) calls.
Registration
Agent self-registration and claim flow.
POST /api/v1/register
Register a new agent. No auth required.
| Field | Type | Description |
|---|---|---|
name | string | Display name for the agent |
Response: agentId, apiKey, claimToken
POST /api/v1/claim
Claim an agent. Requires Firebase ID token.
| Field | Type | Description |
|---|---|---|
claimToken | string | The claim code from agent registration |
Response: agentId, agentName
Memory
Store and retrieve agent memories with semantic search.
POST /api/v1/memory
Store a memory. Requires agent API key and a category: fact, preference, decision, context, or session_summary.
| Field | Type | Description |
|---|---|---|
content | string | The memory content to store (up to 10,000 characters) |
category | string | Required: fact, preference, decision, context, or session_summary |
importance | number | Optional. 0 to 1 (default 0.5) |
tags | string[] | Optional. Tags for filtering |
metadata | object | Optional. Arbitrary key-value metadata |
GET /api/v1/memory/search?q=<query>
Semantic search across memories. Requires agent API key.
| Param | Type | Description |
|---|---|---|
q | string | Search query |
limit | number | Optional. Max results, 1 to 100 (default 10) |
minScore | number | Optional. Minimum relevance score, 0 to 1 (default 0.3) |
GET /api/v1/memory/:id
Get a specific memory by ID.
DELETE /api/v1/memory/:id
Archive a memory. Archived memories are hidden from search and lists unless you pass includeArchived=true.
Knowledge
Entity and relationship graph management.
POST /api/v1/knowledge/entities
Create an entity. Update an existing one with PATCH /api/v1/knowledge/entities/:id.
| Field | Type | Description |
|---|---|---|
name | string | Entity name |
type | string | Case-sensitive entity type (e.g. "Person", "Project", "Note") |
properties | object | Optional. Entity properties |
POST /api/v1/knowledge/relations
Create a relationship between entities.
| Field | Type | Description |
|---|---|---|
fromEntityId | string | Source entity ID |
toEntityId | string | Target entity ID |
relation | string | Relationship type (e.g. "knows", "uses") |
GET /api/v1/knowledge/entities
List all entities. Supports ?type= filter.
GET /api/v1/knowledge/entities/:id
Get entity with its relations.
GET /api/v1/knowledge/search?q=<query>
Search across entities and relations.
Learnings
Pattern extraction and distilled insights.
POST /api/v1/learnings
Log a learning. Requires summary and category.
| Field | Type | Description |
|---|---|---|
summary | string | The learning summary (required) |
category | string | Required: correction, insight, knowledge_gap, best_practice, error, or feature_request |
priority | string | Optional: low, medium, high, or critical |
GET /api/v1/learnings
List learnings. Supports ?category= and ?limit= filters.
GET /api/v1/learnings/search?q=<query>
Semantic search across learnings.
Skills
Agent skill registry.
POST /api/v1/skills
Register a skill. Only name is required.
| Field | Type | Description |
|---|---|---|
name | string | Skill name |
description | string | Optional. What the skill does |
source | string | Optional. Where the skill came from, such as a ClawHub slug or git URL |
version | string | Optional. Semantic version |
config | object | Optional. Arbitrary skill configuration |
GET /api/v1/skills
List all skills for the agent.
GET /api/v1/skills/:id
Get a specific skill.
DELETE /api/v1/skills/:id
Remove a skill.
Owners
Owner (dashboard user) management. Requires Firebase token.
GET /api/v1/owners/me
Get the current owner profile.
GET /api/v1/agents
List all agents owned by the current user.
Agents
Agent management endpoints.
GET /api/v1/agents/:id
Get agent details. Requires owner token.
PATCH /api/v1/agents/:id
Update agent settings. Requires owner token.
DELETE /api/v1/agents/:id
Archive an agent and disable its keys. Requires owner token.
API Keys
Manage API keys. Requires Firebase token.
POST /api/v1/api-keys
Create a new API key. Supply agentId and scopes (for example ["memory.read", "memory.write"]); name is required.
| Field | Type | Description |
|---|---|---|
name | string | Display name for the key |
agentId | string | Required. UUID of an agent owned by the current user |
scopes | string[] | Required. At least one of memory, knowledge, learnings, skills, pools, or dream with .read or .write |
expiresAt | string | Optional. ISO 8601 expiry date-time |
GET /api/v1/api-keys
List all API keys.
DELETE /api/v1/api-keys/:id
Revoke an API key.