Cloud API

REST API reference for https://api.agentrecall.cloud (port 8700).

Authentication

All requests require an API key in the Authorization header:

Authorization: Bearer ark_your_api_key

Getting an API Key

API keys are generated from the dashboard. They start with ark_ and are bound to a specific agent.

When you use an API key, the agent_id is automatically inferred — you don't need to pass it in requests.

JWT Auth (Dashboard)

Dashboard sessions use JWT tokens. When using JWT auth, you must pass agent_id explicitly in requests.

Rate Limiting

Endpoints

POST /v1/memories

Store a new memory.

// With API key (agent_id is automatic)
{
  "content": "The user prefers dark mode",
  "category": "preferences",
  "metadata": { "source": "chat" },
  "importance": 0.8
}

// With JWT auth (agent_id required)
{
  "content": "The user prefers dark mode",
  "agent_id": "my-agent",
  "category": "preferences"
}

GET /v1/memories

List memories with optional filters.

// With API key — no agent_id needed
GET /v1/memories?category=preferences&limit=20

// With JWT auth — agent_id required
GET /v1/memories?agent_id=my-agent&category=preferences&limit=20

GET /v1/memories/:id

Get a single memory by ID.

PUT /v1/memories/:id

Update a memory's content, category, or metadata.

{
  "content": "Updated memory content",
  "category": "updated_category",
  "metadata": { "updated": true }
}

DELETE /v1/memories/:id

Delete a memory and its graph connections.

POST /v1/recall

Semantic search across memories.

// With API key (agent_id is automatic)
{
  "query": "what are the user's preferences?",
  "category": "preferences",
  "limit": 10
}

// With JWT auth (agent_id required)
{
  "query": "what are the user's preferences?",
  "agent_id": "my-agent",
  "limit": 10
}

POST /v1/skip

Store a memory without AI processing (skip enrichment).

{
  "content": "Raw content without AI processing"
}

POST /v1/traverse

Traverse the knowledge graph.

{
  "entity": "User",
  "depth": 3
}

GET /v1/agents

List all agents and their memory counts.

GET /v1/agents/:id/stats

Get statistics for a specific agent (memory count, categories, last activity).

POST /v1/api-keys

Create a new API key for an agent.

{
  "name": "production-key",
  "agent_id": "my-agent-id"
}

Returns the full key once. Store it securely.

GET /v1/api-keys

List all API keys for the authenticated user.

DELETE /v1/api-keys/:id

Revoke an API key.

GET /v1/billing/usage

Get current billing period usage.

GET /v1/billing/plan

Get current plan details (free/pro, limits, expiry).

Error Responses

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Too many requests. Please retry after 60s.",
    "retry_after": 60
  }
}