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.

FieldTypeDescription
namestringDisplay name for the agent

Response: agentId, apiKey, claimToken

POST /api/v1/claim

Claim an agent. Requires Firebase ID token.

FieldTypeDescription
claimTokenstringThe 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.

FieldTypeDescription
contentstringThe memory content to store (up to 10,000 characters)
categorystringRequired: fact, preference, decision, context, or session_summary
importancenumberOptional. 0 to 1 (default 0.5)
tagsstring[]Optional. Tags for filtering
metadataobjectOptional. Arbitrary key-value metadata

GET /api/v1/memory/search?q=<query>

Semantic search across memories. Requires agent API key.

ParamTypeDescription
qstringSearch query
limitnumberOptional. Max results, 1 to 100 (default 10)
minScorenumberOptional. 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.

FieldTypeDescription
namestringEntity name
typestringCase-sensitive entity type (e.g. "Person", "Project", "Note")
propertiesobjectOptional. Entity properties

POST /api/v1/knowledge/relations

Create a relationship between entities.

FieldTypeDescription
fromEntityIdstringSource entity ID
toEntityIdstringTarget entity ID
relationstringRelationship 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.

FieldTypeDescription
summarystringThe learning summary (required)
categorystringRequired: correction, insight, knowledge_gap, best_practice, error, or feature_request
prioritystringOptional: 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.

FieldTypeDescription
namestringSkill name
descriptionstringOptional. What the skill does
sourcestringOptional. Where the skill came from, such as a ClawHub slug or git URL
versionstringOptional. Semantic version
configobjectOptional. 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.

FieldTypeDescription
namestringDisplay name for the key
agentIdstringRequired. UUID of an agent owned by the current user
scopesstring[]Required. At least one of memory, knowledge, learnings, skills, pools, or dream with .read or .write
expiresAtstringOptional. ISO 8601 expiry date-time

GET /api/v1/api-keys

List all API keys.

DELETE /api/v1/api-keys/:id

Revoke an API key.