Skip to main content

Overview

The Memtrace REST API provides a simple HTTP interface for storing and querying memories.

Base URL​

http://localhost:9100

Change the host and port via configuration. See Configuration.

Authentication​

All API endpoints (except /health and /ready) require authentication via API key.

API Key Header​

x-api-key: mtk_...

Or use the Authorization header with Bearer scheme:

Authorization: Bearer mtk_...

Getting Your API Key​

On first run, Memtrace prints your admin API key:

FIRST RUN: Save your admin API key (shown only once)
API Key: mtk_...

Save this key — it's shown only once.

Response Formats​

All responses are JSON.

Success Response​

{
  "memory_id": "abc123",
  "agent_id": "my_agent",
  "content": "Crawled example.com",
  "time": "2026-02-13T10:30:00Z"
}

Error Response​

{
  "error": "invalid_request",
  "message": "agent_id is required"
}

Common Status Codes​

CodeDescription
200Success
201Created
400Bad request (validation error)
401Unauthorized (missing or invalid API key)
404Not found
500Internal server error

Rate Limits​

No rate limits by default. Configure rate limiting at the reverse proxy level (nginx, Caddy, etc.) if needed.

Time Formats​

Time values can be specified in two formats:

Relative Time​

Human-readable relative time strings:

  • 2h — 2 hours ago
  • 30m — 30 minutes ago
  • 7d — 7 days ago
  • 1w — 1 week ago

Absolute Time​

ISO 8601 timestamps:

2026-02-13T10:30:00Z

Pagination​

List endpoints support pagination:

ParamTypeDescription
limitintMax results per page (default 100, max 1000)
offsetintNumber of results to skip

Response includes pagination metadata:

{
  "memories": [...],
  "count": 42,
  "has_more": true
}

Health Checks​

GET /health​

Returns service status. No auth required.

curl http://localhost:9100/health

Response:

{
  "status": "ok",
  "service": "memtrace",
  "uptime": "2h30m15s"
}

GET /ready​

Checks Arc connectivity. No auth required.

curl http://localhost:9100/ready

Response:

{
  "status": "ready",
  "arc": "connected"
}

Example Requests​

cURL​

curl -X POST http://localhost:9100/api/v1/memories \
  -H "x-api-key: mtk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "my_agent",
    "content": "Crawled https://example.com",
    "memory_type": "episodic"
  }'

Python​

import requests

headers = {
    "x-api-key": "mtk_...",
    "Content-Type": "application/json"
}

data = {
    "agent_id": "my_agent",
    "content": "Crawled https://example.com",
    "memory_type": "episodic"
}

response = requests.post(
    "http://localhost:9100/api/v1/memories",
    headers=headers,
    json=data
)

JavaScript​

const response = await fetch('http://localhost:9100/api/v1/memories', {
  method: 'POST',
  headers: {
    'x-api-key': 'mtk_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    agent_id: 'my_agent',
    content: 'Crawled https://example.com',
    memory_type: 'episodic'
  })
});

const data = await response.json();

Next Steps​