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
/api/memory/queryStore a new message and retrieve relevant context from past conversations.
Request Body
sessionIdUnique identifier for the conversation or user. Used to segment memories.
messageThe user message or conversation text to store and use for retrieval.
pineconeKeyYour Pinecone API key (stored in dashboard or passed per-request).
pineconeIndexThe name of your Pinecone index where memories are stored.
llmApiKeyAPI 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
successIndicates whether the request was successful.
contextFormatted context string with retrieved memories, including relevance scores and timestamps.
summaryAI-generated summary of the context (if llmApiKey provided and enabled in settings).
messageIdUnique identifier for the stored message.
retrievedCountNumber of relevant memories retrieved from past conversations.
usageUsage statistics for the current billing period.
currentMonth: Queries used this monthlimit: Total queries allowed per monthremaining: Queries remaining this monthplan: Current subscription planCode 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.
Missing required fields or invalid parameters.
{
"success": false,
"error": "Missing required field: sessionId"
}Invalid or missing API key.
{
"success": false,
"error": "Invalid API key"
}Monthly query limit exceeded.
{
"success": false,
"error": "Monthly query limit exceeded. Please upgrade your plan.",
"usage": {
"currentMonth": 10000,
"limit": 10000,
"remaining": 0,
"plan": "pro"
}
}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:
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
- ✓ 100 queries/month
- ✓ All features
- ✓ Multi-provider support
- ✓ Dashboard access
Pro
- ✓ 10,000 queries/month
- ✓ All features
- ✓ Priority support
- ✓ Advanced analytics
Enterprise
- ✓ 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.