API Reference

Magneteco exposes a RESTful API for all memory operations. All endpoints require authentication via API key.

Base URL

https://api.magneteco.io/v1

Or your self-hosted URL.

Authentication

Include API key in header:

Authorization: Bearer <your-api-key>

Endpoints

Endpoint	Method	Purpose
`/memorize`	POST	Store content in memory
`/retrieve`	POST	Query memory for context
`/events`	POST	Track structured events
`/webhooks/:source`	POST	Receive external webhooks
`/context/:appId/:userId`	GET	Get all summaries
`/categories/:appId/:userId`	GET	List available categories
`/entities/:appId/:userId`	GET	List known entities
`/forget`	POST	GDPR deletion
`/health`	GET	Service health check

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid request body",
    "details": {
      "field": "userId",
      "issue": "Required field missing"
    }
  }
}

Error Codes

Code	HTTP Status	Description
`UNAUTHORIZED`	401	Invalid or missing API key
`FORBIDDEN`	403	API key lacks required permissions
`NOT_FOUND`	404	Resource not found
`VALIDATION_ERROR`	400	Invalid request body
`RATE_LIMITED`	429	Too many requests
`INTERNAL_ERROR`	500	Server error
`SERVICE_UNAVAILABLE`	503	Dependency unavailable

Rate Limits

Endpoint	Limit
`POST /memorize`	100/min per app
`POST /retrieve`	200/min per app
`POST /events`	500/min per app
`POST /webhooks/*`	1000/min per source
`GET /*`	500/min per app

Rate limit headers included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1705330800

Pagination

List endpoints support cursor-based pagination:

# First page
curl "https://api.magneteco.io/v1/entities/tanda/user-123?limit=20"

# Next page
curl "https://api.magneteco.io/v1/entities/tanda/user-123?limit=20&cursor=eyJpZCI6MTIzfQ"

Response includes pagination info:

{
  "data": [...],
  "pagination": {
    "total": 150,
    "limit": 20,
    "hasMore": true,
    "nextCursor": "eyJpZCI6MTQzfQ"
  }
}

API Reference

On this page