REST Surface

Overview

The self-hosted sovseal deployment exposes a REST API compatible with the client SDKs. This allows you to route replication and synchronization requests to your own infrastructure by changing the base URL.

Base URL Conventions

• Supabase Functions: https://<project-ref>.supabase.co/functions/v1/v2-agent-state
• Docker Compose: http://localhost:8888

Authentication

All endpoints require authentication (unless AUTH_DISABLED=true is set).

Authorization: Bearer <your-api-key>

API Endpoints

1. Add Memories

Extracts and stores facts from a sequence of chat messages.

• Path: POST /v3/memories/add/
• Request Body:

  {
    "messages": [
      {"role": "user", "content": "I live in Berlin and build AI systems."},
      {"role": "assistant", "content": "Got it! I will remember your location and profession."}
    ],
    "user_id": "alice"
  }

• Response: 202 Accepted

  {
    "message": "Memory processing has been queued for background execution",
    "status": "PENDING",
    "event_id": "evt-77b5a88c-9c98-4b77-a8b2-b1c3a64dfab0"
  }

2. Search Memories

Retrieves memories matching a query. Performs hybrid vector and keyword matching.

• Path: POST /v3/memories/search/
• Request Body:

  {
    "query": "where does alice live?",
    "filters": {
      "user_id": "alice"
    },
    "top_k": 5,
    "threshold": 0.1
  }

• Response: 200 OK

  {
    "results": [
      {
        "id": "mem-4d5e6f...",
        "memory": "Alice lives in Berlin",
        "score": 0.88,
        "metadata": {
          "category": "location"
        },
        "created_at": "2026-06-10T11:22:37Z",
        "updated_at": "2026-06-10T11:22:37Z"
      }
    ]
  }

3. List Memories (Paginated)

Fetch all stored memories for a project under specific filters.

• Path: POST /v3/memories/ (or GET /v3/memories/)
• Query Parameters:
  • page: Page index (default: 1).
  • page_size: Items per page (default: 50).
• Request Body:

  {
    "filters": {
      "user_id": "alice"
    }
  }

• Response: 200 OK

  {
    "count": 12,
    "next": "http://localhost:8888/v3/memories/?page=2&page_size=10",
    "previous": null,
    "results": [
      {
        "id": "mem-4d5e6f...",
        "memory": "Alice builds AI systems",
        "metadata": {
          "category": "work"
        },
        "created_at": "2026-06-10T11:20:00Z",
        "updated_at": "2026-06-10T11:20:00Z"
      }
    ]
  }

4. Delete Memory

Remove a specific memory snapshot by ID.

• Path: DELETE /v3/memories/:id/
• Response: 200 OK

  {
    "success": true,
    "message": "Memory deleted successfully"
  }