Purple Hub API Documentation

Health Check

GET /health

Health check endpoint (no authentication required)

Memory Operations

POST /api/v1/add

Add memories (supports Mem0-compatible and structured formats). Requires write scope.

Confidentiality Scopes: All memories require entity_id and optionally scope. Valid scopes: private (default), group, tenant, public. See Confidentiality Scopes for details.

Request Body:

{
  "messages": [
    {"role": "user", "content": "User prefers dark mode UI"}
  ],
  "user_id": "user_123",
  "entity_id": "customer_456",  // Required
  "scope": "private",            // Optional, defaults to "private"
  "context_id": "ctx_123",        // Optional, auto-generated if omitted
  "episode_id": "ep_456",         // Optional, auto-generated if omitted
  "agent_id": "agent_789",        // Optional
  "dimensions": {                  // Optional
    "topics": ["ui", "preferences"],
    "tags": ["user-pref"],
    "entities": ["user"]
  },
  "metadata": {                    // Optional
    "source": "web"
  }
}

Request Fields:

messages (array, required): Array of message objects with role and content
user_id (string, required): User identifier
entity_id (string, required): Entity identifier (non-empty string)
scope (string, optional): Confidentiality scope. Valid values: private, group, tenant, public. Defaults to private
context_id (string, optional): Context identifier. Auto-generated if omitted
episode_id (string, optional): Episode identifier. Auto-generated if omitted
agent_id (string, optional): Agent identifier
dimensions (object, optional): Dimension filters (topics, tags, entities)
metadata (object, optional): Additional metadata

Response (200 OK):

{
  "success": true,
  "data": {
    "memories": [
      {
        "id": "interaction-uuid",
        "memory": "User prefers dark mode UI",
        "user_id": "user_123",
        "context_id": "ctx_123",
        "episode_id": "ep_456",
        "created_at": "2024-01-15T10:30:00Z",
        "summary": "User prefers dark mode UI"
      }
    ],
    "summary_status": "ready"
  },
  "purple_hub": {
    "context_id": "ctx_123",
    "episode_id": "ep_456",
    "interaction_ids": ["interaction-uuid"],
    "structure_level": "structured",
    "auto_upgraded": false
  }
}

Contexts

POST /api/v1/contexts

Create a new context. Requires admin scope.

Request Body:

{
  "id": "ctx_123",
  "name": "Customer Support Context",
  "description": "Context for customer support interactions",
  "entity_id": "customer_456",    // Required
  "scope": "private",             // Optional, defaults to "private"
  "metadata": {                    // Optional
    "department": "support"
  }
}

Request Fields:

id (string, required): Context identifier
name (string, required): Context name
entity_id (string, required): Entity identifier (non-empty string)
description (string, optional): Context description
scope (string, optional): Confidentiality scope. Defaults to private
metadata (object, optional): Additional metadata
tenant_id (string, optional): Ignored - tenant_id is set from auth context

GET /api/v1/contexts

List all contexts

GET /api/v1/contexts/{contextID}

Get a specific context

PUT /api/v1/contexts/{contextID}

Update a context

DELETE /api/v1/contexts/{contextID}

Delete a context (cascades to episodes and interactions)

Episodes

POST /api/v1/contexts/{contextID}/episodes

Create a new episode within a context

GET /api/v1/contexts/{contextID}/episodes

List episodes for a context

GET /api/v1/contexts/{contextID}/episodes/{episodeID}

Get a specific episode

PUT /api/v1/contexts/{contextID}/episodes/{episodeID}

Update an episode

DELETE /api/v1/contexts/{contextID}/episodes/{episodeID}

Delete an episode (cascades to interactions)

Interactions

POST /api/v1/episodes/{episodeID}/interactions

Create a new interaction within an episode

GET /api/v1/episodes/{episodeID}/interactions

List interactions for an episode

GET /api/v1/interactions/{interactionID}

Get a specific interaction

DELETE /api/v1/interactions/{interactionID}

Delete an interaction

POST /api/v1/interactions/batch

Batch create interactions

DELETE /api/v1/interactions/batch

Batch delete interactions

Search

POST /api/v1/search/semantic

Semantic search using embeddings. Requires read scope.

Scope Filtering: Search results are filtered by exact (tenant_id, entity_id, scope) match. Only memories matching all three criteria are returned.

Request Body:

{
  "query": "user preferences",
  "entity_id": "customer_456",    // Required
  "scope": "private",             // Optional, defaults to "private"
  "topics": ["ui", "preferences"], // Optional: additional semantic search terms
  "top_k": 10,                    // Optional, default: 10, max: 100
  "include_recent": 50,           // Optional, default: 50, max: 200
  "limit": 10                     // Optional, default: 10, max: 100
}

Request Fields:

query (string, required): Search query text
entity_id (string, required): Entity identifier (non-empty string)
scope (string, optional): Scope to search within. Valid values: private, group, tenant, public. Defaults to private
topics (array, optional): Additional semantic search terms
top_k (integer, optional): Number of semantic results. Default: 10, Max: 100
include_recent (integer, optional): Number of recent interactions to include. Default: 50, Max: 200
limit (integer, optional): Total results limit. Default: 10, Max: 100

Response (200 OK):

{
  "success": true,
  "data": {
    "results": [
      {
        "interaction_id": "interaction-uuid",
        "score": 0.85,
        "distance": 12,
        "content": "User prefers dark mode UI",
        "role": "user",
        "context_id": "ctx_123",
        "episode_id": "ep_456",
        "timestamp": "2024-01-15T10:30:00Z"
      }
    ],
    "total": 1
  }
}

POST /api/v1/search/hybrid

Hybrid search combining semantic search with dimension filters. Requires read scope.

Request Body:

{
  "query": "user preferences",     // Optional if filters provided
  "entity_id": "customer_456",    // Required
  "scope": "private",             // Optional, defaults to "private"
  "filters": [                     // Optional: dimension filters
    {
      "dimension": "agent_id",
      "operator": "eq",
      "values": ["agent_789"]
    },
    {
      "dimension": "topic",
      "operator": "in",
      "values": ["ui", "preferences"]
    }
  ],
  "top_k": 10,                    // Optional, default: 10, max: 100
  "limit": 10                     // Optional, default: 10, max: 100
}

Request Fields:

query (string, optional): Semantic search query. Required if no filters provided
entity_id (string, required): Entity identifier (non-empty string)
scope (string, optional): Scope to search within. Defaults to private
filters (array, optional): Dimension filters. Valid dimensions: agent_id, topic, tag, entity, role, memory_type
top_k (integer, optional): Number of semantic results. Default: 10, Max: 100
limit (integer, optional): Total results limit. Default: 10, Max: 100

Response (200 OK):

{
  "success": true,
  "data": {
    "results": [
      {
        "interaction_id": "interaction-uuid",
        "score": 0.85,
        "distance": 12,
        "content": "User prefers dark mode UI",
        "role": "user",
        "context_id": "ctx_123",
        "episode_id": "ep_456",
        "timestamp": "2024-01-15T10:30:00Z"
      }
    ],
    "total": 1
  }
}

POST /api/v1/search/unified

Unified search for both memory and knowledge simultaneously. Searches run in parallel for optimal latency. Requires read scope.

Request Body:

{
  "query": "artificial intelligence",
  "entity_id": "customer_456",    // Required
  "scope": "private",             // Optional, defaults to "private"
  "search_memory": true,          // Optional, default: true
  "search_knowledge": true,       // Optional, default: false
  "memory_top_k": 20,             // Optional, default: 20, max: 100
  "knowledge_top_k": 10,          // Optional, default: 10, max: 100
  "include_recent": 100,          // Optional, default: 100, max: 200
  "source_filter": "podcast-123"  // Optional: filter knowledge by source ID
}

Request Fields:

query (string, required): Search query text
entity_id (string, required): Entity identifier (non-empty string)
scope (string, optional): Scope to search within. Defaults to private
search_memory (boolean, optional): Search conversational memory. Default: true
search_knowledge (boolean, optional): Search knowledge base. Default: false
memory_top_k (integer, optional): Number of memory results. Default: 20, Max: 100
knowledge_top_k (integer, optional): Number of knowledge results. Default: 10, Max: 100
include_recent (integer, optional): Number of recent interactions to include. Default: 100, Max: 200
source_filter (string, optional): Filter knowledge results by source ID

Response (200 OK):

{
  "success": true,
  "data": {
    "memory_results": [
      {
        "interaction_id": "interaction-uuid",
        "score": 0.85,
        "distance": 12,
        "content": "We discussed AI capabilities",
        "role": "user",
        "context_id": "ctx_123",
        "episode_id": "ep_456",
        "timestamp": "2024-01-15T10:30:00Z"
      }
    ],
    "knowledge_results": [
      {
        "chunk_id": "chunk-uuid",
        "knowledge_id": "knowledge-uuid",
        "score": 0.92,
        "content": "Artificial intelligence is...",
        "metadata": {
          "source_id": "podcast-123",
          "type": "transcript",
          "title": "AI Podcast Episode 1"
        }
      }
    ],
    "total": 2
  }
}

Knowledge Base

The Knowledge Base provides RAG (Retrieval Augmented Generation) capabilities for static documents, separate from conversational memory. Documents are chunked semantically with overlap, embedded, and stored in an optimized RocksDB database. Knowledge can be searched independently or combined with memory search using the unified endpoint.

POST /api/v1/knowledge/search

Search the knowledge base (RAG) for static documents. Requires read scope. Knowledge component must be configured (set PURPLE_HUB_KNOWLEDGE_DATA_DIR).

Request Body:

{
  "query": "artificial intelligence",
  "tenant_id": "system",          // Optional, defaults to "system"
  "top_k": 10,                    // Optional, default: 10, max: 100
  "source_filter": "podcast-123"  // Optional: filter by source ID
}

Request Fields:

query (string, required): Search query text
tenant_id (string, optional): Tenant ID to search. Defaults to "system". Searches tenant-specific knowledge if provided, falls back to system knowledge.
top_k (integer, optional): Number of results. Default: 10, Max: 100
source_filter (string, optional): Filter results by source ID

Response (200 OK):

{
  "success": true,
  "data": {
    "results": [
      {
        "chunk_id": "chunk-uuid",
        "knowledge_id": "knowledge-uuid",
        "score": 0.92,
        "content": "Artificial intelligence is the simulation of human intelligence...",
        "metadata": {
          "source_id": "podcast-123",
          "type": "transcript",
          "title": "AI Podcast Episode 1"
        }
      }
    ],
    "total": 1
  }
}

POST /api/v1/knowledge/batch

Batch ingest documents into the knowledge base. Requires write scope. Knowledge component must be configured.

Request Body:

{
  "documents": [
    {
      "source_id": "doc-1",
      "content": "Full text content here...",
      "metadata": {
        "type": "article",
        "title": "Article Title",
        "author": "Author Name"
      }
    }
  ],
  "tenant_id": "system"  // Optional, defaults to "system"
}

Request Fields:

documents (array, required): Array of document objects
documents[].source_id (string, required): Unique source identifier
documents[].content (string, required): Document text content
documents[].metadata (object, optional): Document metadata (type, title, etc.)
tenant_id (string, optional): Tenant ID for the documents. Defaults to "system"

Response (200 OK):

{
  "success": true,
  "data": {
    "ingested": 1,
    "chunks_created": 5
  }
}