Overview
Satori provides a type-safe tRPC API for all memory operations. This API is used internally by the @satori/tools package and can also be called directly for custom integrations.
Base URL
https://api.satori.dev/trpc
Authentication
All API requests require authentication via the x-api-key header:
curl -X POST 'https://api.satori.dev/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 memorymemory.search - Search for relevant memoriesmemory.getAll - Get all memories for a usermemory.getById - Get a specific memory by IDmemory.delete - Delete a memory
Keys Router
Operations for managing API keys (dashboard use):
keys.list - List all API keyskeys.create - Create a new API keykeys.revoke - Revoke an API key
Using tRPC Client
TypeScript/JavaScript
Install the tRPC client:
npm install @trpc/client @satori/server
import { createTRPCClient, httpBatchLink } from '@trpc/client';
import type { AppRouter } from '@satori/server';
const client = createTRPCClient<AppRouter>({
links: [
httpBatchLink({
url: 'https://api.satori.dev/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 Type | Value |
|---|
| Requests per minute | 100 |
| Concurrent requests | 10 |
| Max memories per user | Unlimited |
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
| Code | HTTP Status | Description |
|---|
UNAUTHORIZED | 401 | Invalid or missing API key |
BAD_REQUEST | 400 | Invalid request parameters |
NOT_FOUND | 404 | Resource not found |
TOO_MANY_REQUESTS | 429 | Rate limit exceeded |
INTERNAL_SERVER_ERROR | 500 | Server error |
Example Error Response
{
"error": {
"message": "Unauthorized - Invalid API key",
"code": "UNAUTHORIZED",
"data": {
"code": "UNAUTHORIZED",
"httpStatus": 401,
"path": "memory.add"
}
}
}
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' }),
]);
Health Check
Check API health:
Response:
{
"status": "ok",
"db": "connected",
"timestamp": 1705334400000
}
Next Steps
