## 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: https://api.swarmrecall.ai (production) or http://localhost:3300 (local development)

## Authentication

All requests must include an Authorization header:

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`

Field	Type	Description
`name`	string	Display name for the agent
`platform`	string	Optional. Platform identifier (e.g. "swarmclaw")

Response: agentId, apiKey, claimCode

`POST /api/v1/claim`

Claim an agent. Requires Firebase ID token.

Field	Type	Description
`claimCode`	string	The claim code from agent registration

Response: agentId, ownerId

## Memory

Store and retrieve agent memories with semantic search.

`POST /api/v1/memory`

Store a memory. Requires agent API key.

Field	Type	Description
`content`	string	The memory content to store
`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 (default 10)
`tags`	string	Optional. Comma-separated tag filter

`GET /api/v1/memory/:id`

Get a specific memory by ID.

`DELETE /api/v1/memory/:id`

Delete a specific memory.

## Knowledge

Entity and relationship graph management.

`POST /api/v1/knowledge/entities`

Create or update an entity.

Field	Type	Description
`name`	string	Entity name
`type`	string	Entity type (e.g. "person", "concept")
`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
`type`	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`

Store a learning.

Field	Type	Description
`content`	string	The learning content
`category`	string	Optional. Category (e.g. "success", "failure", "pattern")
`confidence`	number	Optional. Confidence score 0-1

`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`

Field	Type	Description
`name`	string	Skill name
`description`	string	What the skill does
`version`	string	Optional. Semantic version
`schema`	object	Optional. JSON schema for skill parameters

`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/owners/me/agents`

List all agents owned by the current user.

## Agents

Agent management endpoints.

`GET /api/v1/agents/:id`

Get agent details. Requires owner token or agent API key.

`PATCH /api/v1/agents/:id`

Update agent settings. Requires owner token.

`DELETE /api/v1/agents/:id`

Delete an agent and all its data. Requires owner token.

## API Keys

Manage API keys. Requires Firebase token.

`POST /api/v1/api-keys`

Create a new API key.

Field	Type	Description
`name`	string	Display name for the key
`agentId`	string	Optional. Scope to a specific agent

`GET /api/v1/api-keys`

List all API keys.

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

Revoke an API key.