API Documentation

Complete API reference with code examples

Quick Start

The InstantRecall API provides a single endpoint for storing and retrieving memory. Send a message, get back relevant context from past conversations.

Base URL: https://instantrecall.ai/api

Authentication

Authenticate using your InstantRecall API key in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Get your API key from your dashboard after signing up.

Memory Query Endpoint

POST/api/memory/query

Store a new message and retrieve relevant context from past conversations.

Request Body

sessionId
stringrequired

Unique identifier for the conversation or user. Used to segment memories.

message
stringrequired

The user message or conversation text to store and use for retrieval.

pineconeKey
stringrequired

Your Pinecone API key (stored in dashboard or passed per-request).

pineconeIndex
stringrequired

The name of your Pinecone index where memories are stored.

llmApiKey
stringoptional

API key for OpenAI, Anthropic, or xAI. Required if you want automatic summarization of context.

Response

{
  "success": true,
  "context": "Previous conversation context:\n[1] (95% relevant, 2m ago): User asked about project timeline\n[2] (87% relevant, 5m ago): Discussed Q1 deliverables",
  "summary": "The user previously inquired about project timelines and Q1 deliverables.",
  "messageId": "msg-abc123xyz",
  "retrievedCount": 2,
  "usage": {
    "currentMonth": 47,
    "limit": 10000,
    "remaining": 9953,
    "plan": "pro"
  }
}

Response Fields

success
boolean

Indicates whether the request was successful.

context
string

Formatted context string with retrieved memories, including relevance scores and timestamps.

summary
string | null

AI-generated summary of the context (if llmApiKey provided and enabled in settings).

messageId
string

Unique identifier for the stored message.

retrievedCount
number

Number of relevant memories retrieved from past conversations.

usage
object

Usage statistics for the current billing period.

currentMonth: Queries used this month
limit: Total queries allowed per month
remaining: Queries remaining this month
plan: Current subscription plan

Code Examples

// Node.js / JavaScript Example
const axios = require('axios');

async function queryMemory(sessionId, message) {
  try {
    const response = await axios.post(
      'https://instantrecall.ai/api/memory/query',
      {
        sessionId: sessionId,
        message: message,
        pineconeKey: process.env.PINECONE_API_KEY,
        pineconeIndex: 'my-memory-index',
        llmApiKey: process.env.OPENAI_API_KEY // Optional
      },
      {
        headers: {
          'Authorization': `Bearer ${process.env.INSTANTRECALL_API_KEY}`,
          'Content-Type': 'application/json'
        }
      }
    );

    const { context, summary, retrievedCount } = response.data;
    
    
    return response.data;
  } catch (error) {
    console.error('Error querying memory:', error.response?.data || error.message);
    throw error;
  }
}

// Usage
queryMemory('user-123', 'What did we discuss about the project?');

Error Handling

The API returns standard HTTP status codes and JSON error responses.

400Bad Request

Missing required fields or invalid parameters.

{
  "success": false,
  "error": "Missing required field: sessionId"
}
401Unauthorized

Invalid or missing API key.

{
  "success": false,
  "error": "Invalid API key"
}
429Rate Limit Exceeded

Monthly query limit exceeded.

{
  "success": false,
  "error": "Monthly query limit exceeded. Please upgrade your plan.",
  "usage": {
    "currentMonth": 10000,
    "limit": 10000,
    "remaining": 0,
    "plan": "pro"
  }
}
500Internal Server Error

Something went wrong on our end. Please try again or contact support.

{
  "success": false,
  "error": "Internal server error. Please try again later."
}

Advanced Usage

Customizing Memory Settings

Adjust memory retrieval behavior from your dashboard's "Memory Settings" panel:

  • Top K Results: Number of memories to retrieve (default: 5)
  • Relevance Threshold: Minimum similarity score (0-1, default: 0.7)
  • Summarization: Enable/disable AI summarization
  • AI Provider: Choose OpenAI, Claude, or Grok
  • Model: Select specific model (e.g., GPT-4, Claude Sonnet)
  • Temperature: Control randomness in summarization (0-2)
  • Max Tokens: Limit summary length (1-500)

Session Management Best Practices

Organize memories effectively with thoughtful session IDs:

user-123 - All conversations for a single user
conversation-abc-xyz - Specific conversation thread
support-ticket-789 - Customer support context
project-alpha-user-456 - Project-specific user context

Working with Large Contexts

When dealing with extensive conversation histories:

  • Increase "Top K Results" to retrieve more memories (up to 20)
  • Lower the relevance threshold to capture broader context
  • Use summarization to condense large contexts into digestible summaries
  • Consider splitting very long conversations into multiple sessions

Rate Limits & Pricing

Free

$0/mo
  • ✓ 100 queries/month
  • ✓ All features
  • ✓ Multi-provider support
  • ✓ Dashboard access

Pro

$29/mo
  • ✓ 10,000 queries/month
  • ✓ All features
  • ✓ Priority support
  • ✓ Advanced analytics

Enterprise

Custom
  • ✓ Unlimited queries
  • ✓ Custom SLA
  • ✓ Dedicated support
  • ✓ On-premise options

All plans include encryption, full API access, and multi-provider support.

Support & Resources

Need help? We're here for you.

📧 Email Support

support@instantrecall.ai

📚 Documentation

How It Works Guide

Ready to Build?

Get your API key and start adding memory to your AI application