REST API

The Reeflect REST API provides language-agnostic access to memory capabilities through standard HTTP requests. This is ideal for integrating with any programming language or framework.

Authentication

The REST API uses API keys for authentication. Include your API key in the Authorization header with all requests:

curl -X GET https://api.reeflect.ai/v1/memories \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

API Endpoints

Memories

Endpoint	Method	Description
/v1/memories	POST	Create a new memory
/v1/memories/:id	GET	Retrieve a memory by ID
/v1/memories/:id	PATCH	Update a memory
/v1/memories/:id	DELETE	Delete a memory
/v1/memories/query	POST	Query memories by filter criteria
/v1/memories/search	POST	Search memories by semantic similarity
/v1/memories/batch	POST	Batch create/update/delete memories

Utility Endpoints

Endpoint	Method	Description
/v1/enhance	POST	Enhance a prompt with relevant memories
/v1/extract	POST	Extract memories from conversation
/v1/reason	POST	Reason using relevant memories
/v1/contradictions	POST	Detect contradictions in new information

Request Examples

Create a Memory

curl -X POST https://api.reeflect.ai/v1/memories \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "The user prefers dark mode in all applications.",
    "namespace": "user_preferences",
    "importance": 0.8,
    "tags": ["ui", "theme", "preference"]
  }'

Response:

{
  "id": "mem_1a2b3c4d5e6f",
  "content": "The user prefers dark mode in all applications.",
  "namespace": "user_preferences",
  "importance": 0.8,
  "tags": ["ui", "theme", "preference"],
  "created_at": "2025-04-11T14:32:15.123Z",
  "updated_at": "2025-04-11T14:32:15.123Z"
}

Search Memories

curl -X POST https://api.reeflect.ai/v1/memories/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What theme does the user prefer?",
    "namespace": "user_preferences",
    "limit": 5,
    "min_similarity": 0.5
  }'

Response:

{
  "results": [
    {
      "memory": {
        "id": "mem_1a2b3c4d5e6f",
        "content": "The user prefers dark mode in all applications.",
        "namespace": "user_preferences",
        "importance": 0.8,
        "tags": ["ui", "theme", "preference"],
        "created_at": "2025-04-11T14:32:15.123Z",
        "updated_at": "2025-04-11T14:32:15.123Z"
      },
      "similarity": 0.92
    },
    {
      "memory": {
        "id": "mem_2b3c4d5e6f7g",
        "content": "The user prefers a high contrast color scheme.",
        "namespace": "user_preferences",
        "importance": 0.7,
        "tags": ["ui", "colors", "preference"],
        "created_at": "2025-04-10T09:14:22.456Z",
        "updated_at": "2025-04-10T09:14:22.456Z"
      },
      "similarity": 0.78
    }
  ]
}

Enhance a Prompt

curl -X POST https://api.reeflect.ai/v1/enhance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "What theme should I use for the dashboard?",
    "namespace": "user_preferences",
    "max_memories": 3,
    "max_tokens": 800
  }'

Response:

{
  "enhanced_prompt": "Relevant context from memory:\n- The user prefers dark mode in all applications.\n- The user prefers a high contrast color scheme.\n- The user prefers sans-serif fonts.\n\nWith that context in mind, please address: What theme should I use for the dashboard?",
  "included_memories": [
    "mem_1a2b3c4d5e6f",
    "mem_2b3c4d5e6f7g",
    "mem_3c4d5e6f7g8h"
  ],
  "token_count": 62
}

Reason Using Memories

curl -X POST https://api.reeflect.ai/v1/reason \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What kind of dashboard design would this user prefer?",
    "namespace": "user_preferences",
    "max_memories": 5,
    "instruction": "Focus on UI preferences, color choices, and theme preferences."
  }'

Response:

{
  "answer": "Based on the user's preferences, they would prefer a dashboard with a dark mode interface, high contrast colors (particularly between text and background), and sans-serif fonts. The layout should be clean and minimalist with clear visual hierarchy.",
  "confidence": 0.89,
  "memories_used": [
    "mem_1a2b3c4d5e6f",
    "mem_2b3c4d5e6f7g",
    "mem_3c4d5e6f7g8h",
    "mem_4d5e6f7g8h9i"
  ]
}

API Reference

For complete OpenAPI/Swagger documentation of all REST API endpoints, parameters, and responses, please refer to the full REST API reference.

Rate Limits

The REST API enforces rate limits to ensure fair usage and system stability:

Plan	Rate Limit
Free	10 requests per minute
Pro	60 requests per minute
Enterprise	Custom limits

If you exceed your rate limit, the API will return a 429 Too Many Requests response with a Retry-After header indicating when you can resume making requests.

Versioning

The API uses a versioned URL path (e.g., /v1/memories) to ensure backwards compatibility as the API evolves. Major changes that might break existing integrations will be released under a new version path.

Error Handling

The API uses standard HTTP status codes and returns detailed error information in the response body:

{
  "error": {
    "code": "invalid_request",
    "message": "The request was unacceptable, often due to missing a required parameter.",
    "param": "namespace",
    "details": "The namespace parameter is required for search operations."
  }
}

Next Steps

Learn how to use the REST API in specific scenarios:

• Chat Integration
• Enterprise Setup
• Migration Guide