Skip to main content

​
Overview

Satori provides a type-safe tRPC API for all memory operations. This API is used internally by the @usesatori/tools package and can also be called directly for custom integrations.

​
Base URL

https://api.usesatori.sh/trpc
For self-hosted deployments, use your own server URL.

​
Authentication

All API requests require authentication via the x-api-key header: 
curl -X POST 'https://api.usesatori.sh/trpc/memory.add' \
  -H 'x-api-key: sk_satori_...' \
  -H 'Content-Type: application/json'
Never expose your API key in client-side code. Always make API calls from your server.

​
API Structure

The Satori API is organized into two main routers:

​
Memory Router

Operations for managing memories:
  • memory.add - Save a new memory
  • memory.search - Search for relevant memories
  • memory.getAll - Get all memories for a user
  • memory.getById - Get a specific memory by ID
  • memory.delete - Delete a memory

​
Keys Router

Operations for managing API keys (dashboard use):
  • keys.list - List all API keys
  • keys.create - Create a new API key
  • keys.revoke - Revoke an API key

​
Using tRPC Client

​
TypeScript/JavaScript

Install the tRPC client: 
npm install @trpc/client @satori/server
Create a typed client: 
import { createTRPCClient, httpBatchLink } from '@trpc/client';
import type { AppRouter } from '@satori/server';

const client = createTRPCClient<AppRouter>({
  links: [
    httpBatchLink({
      url: 'https://api.usesatori.sh/trpc',
      headers() {
        return {
          'x-api-key': process.env.SATORI_API_KEY!,
        };
      },
    }),
  ],
});

// Use with full type safety
const memory = await client.memory.add.mutate({
  userId: 'user-123',
  content: 'User prefers TypeScript',
});

​
React

Use with React Query: 
import { createTRPCReact } from '@trpc/react-query';
import type { AppRouter } from '@satori/server';

export const trpc = createTRPCReact<AppRouter>();

// In your component
function MyComponent() {
  const { data: memories } = trpc.memory.search.useQuery({
    userId: 'user-123',
    query: 'preferences',
  });
  
  return <div>{/* render memories */}</div>;
}

​
Rate Limits

Limit TypeValue
Requests per minute100
Concurrent requests10
Max memories per userUnlimited
Rate limits are per API key. Contact support for higher limits.

​
Error Handling

All API errors follow this format: 
{
  error: {
    message: string;
    code: string;
    data?: {
      code: string;
      httpStatus: number;
      path: string;
    };
  }
}

​
Common Error Codes

CodeHTTP StatusDescription
UNAUTHORIZED401Invalid or missing API key
BAD_REQUEST400Invalid request parameters
NOT_FOUND404Resource not found
TOO_MANY_REQUESTS429Rate limit exceeded
INTERNAL_SERVER_ERROR500Server error

​
Example Error Response

{
  "error": {
    "message": "Unauthorized - Invalid API key",
    "code": "UNAUTHORIZED",
    "data": {
      "code": "UNAUTHORIZED",
      "httpStatus": 401,
      "path": "memory.add"
    }
  }
}

​
Request/Response Format

​
tRPC Queries (GET operations)

Queries use GET requests with query parameters: 
GET /trpc/memory.search?input={"userId":"user-123","query":"preferences"}

​
tRPC Mutations (POST operations)

Mutations use POST requests with JSON body: 
POST /trpc/memory.add
Content-Type: application/json

{
  "userId": "user-123",
  "content": "User prefers TypeScript"
}

​
Batch Requests

tRPC supports batching multiple requests into one HTTP call: 
const [memories, allMemories] = await Promise.all([
  client.memory.search.query({ userId: 'user-123', query: 'preferences' }),
  client.memory.getAll.query({ userId: 'user-123' }),
]);
This sends a single HTTP request with both operations.

​
Health Check

Check API health: 
GET /health
Response: 
{
  "status": "ok",
  "db": "connected",
  "timestamp": 1705334400000
}

​
Next Steps

Memory Operations

Explore memory management endpoints

API Key Management

Learn about key management endpoints

Integration Guide

See the API in action

Direct Client

Use the MemoryClient wrapper