Chat

This endpoint provides an AI-powered chat interface that can reference and understand your saved memories. It supports streaming responses and maintains conversation context.

POST /api/chat

Request Body

{
  // Array of previous messages in the conversation
  messages: Array<{
    role: "user" | "assistant" | "system",
    content: string | Array<{
      type: "text" | "image" | "file",
      text?: string,
      image?: string,
      data?: string
    }>,
    annotations?: any[],
    experimental_attachments?: any[]
  }>,
  
  // Optional thread ID for continuing a conversation
  threadId?: string
}

Field Descriptions

Field	Type	Required	Description
`messages`	array	Yes	Array of message objects representing the conversation history
`messages[].role`	string	Yes	Role of the message sender (“user”, “assistant”, or “system”)
`messages[].content`	string \| array	Yes	Message content, either as plain text or structured content
`messages[].annotations`	array	No	Additional metadata or annotations for the message
`messages[].experimental_attachments`	array	No	Experimental support for file attachments
`threadId`	string	No	ID of an existing conversation thread to continue

Response

The endpoint returns a streaming response with chunks of the AI’s reply. The response includes:

Text content streamed as it’s generated
Context annotations with relevant memories
Thread management information

Headers

Header	Description
`Supermemory-Thread-Uuid`	Unique identifier for the conversation thread
`Content-Type`	`text/x-unknown`
`content-encoding`	`identity`
`transfer-encoding`	`chunked`

Stream Format

The response is streamed as text chunks with special annotations for context:

{
  text: string,           // The AI's response text
  annotations?: {         // Optional context from your memories
    similarity: number,   // Relevance score (0-1)
    id: string,          // Document ID
    content: string,     // Document content
    type: string,        // Content type
    url: string,         // Source URL
    title: string,       // Document title
    description?: string,// Document description
    ogImage?: string,    // Open Graph image URL
    createdAt: string,   // ISO timestamp
    updatedAt?: string   // ISO timestamp
  }[]
}

Error Responses

400 Bad Request

{
  "error": "Invalid prompt - please rephrase your message"
}

401 Unauthorized

{
  "error": "Unauthorized"
}

500 Internal Server Error

{
  "error": "An unexpected error occurred",
  "details": "Error details (in development mode)"
}

503 Service Unavailable

{
  "error": "Database connection failed"
}

Features

Memory Context

Automatically searches your saved memories for relevant context
Uses semantic search with cosine similarity
Includes content with similarity score > 0.4
Returns up to 5 most relevant unique documents

Thread Management

Creates new thread if threadId is not provided
Maintains conversation history
Updates thread with new messages automatically

Smart Processing

Filters out empty messages
Supports structured content (text, images, files)
Normalizes similarity scores for better context selection
Implements caching and performance optimizations

Examples

Starting a New Chat

{
  "messages": [
    {
      "role": "user",
      "content": "What do I know about machine learning?"
    }
  ]
}

Continuing a Conversation

{
  "messages": [
    {
      "role": "user",
      "content": "Tell me more about neural networks"
    }
  ],
  "threadId": "chat-123-abc"
}

Using Structured Content

{
  "messages": [
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What's in this image?"
        },
        {
          "type": "image",
          "image": "https://example.com/image.jpg"
        }
      ]
    }
  ]
}

Notes

Authentication is required
Responses are streamed in real-time
Context is automatically injected based on message content
Supports both text and structured content
Thread history is automatically maintained
Performance optimizations include:
- Semantic search caching
- Similarity score normalization
- Unique document deduplication

API Reference Add