> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usesatori.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Complete reference for the Satori tRPC API

## 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:

```bash theme={null}
curl -X POST 'https://api.usesatori.sh/trpc/memory.add' \
  -H 'x-api-key: sk_satori_...' \
  -H 'Content-Type: application/json'
```

<Warning>
  Never expose your API key in client-side code. Always make API calls from your server.
</Warning>

## 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:

```bash theme={null}
npm install @trpc/client @satori/server
```

Create a typed client:

```typescript theme={null}
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:

```typescript theme={null}
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 |

<Info>
  Rate limits are per API key. Contact support for higher limits.
</Info>

## Error Handling

All API errors follow this format:

```typescript theme={null}
{
  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

```json theme={null}
{
  "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:

```bash theme={null}
GET /trpc/memory.search?input={"userId":"user-123","query":"preferences"}
```

### tRPC Mutations (POST operations)

Mutations use POST requests with JSON body:

```bash theme={null}
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:

```typescript theme={null}
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:

```bash theme={null}
GET /health
```

Response:

```json theme={null}
{
  "status": "ok",
  "db": "connected",
  "timestamp": 1705334400000
}
```

## Next Steps

<CardGroup cols={2}>
  <Card title="Memory Operations" icon="brain" href="/api-reference/memory/add">
    Explore memory management endpoints
  </Card>

  <Card title="API Key Management" icon="key" href="/api-reference/keys/list">
    Learn about key management endpoints
  </Card>

  <Card title="Integration Guide" icon="code" href="/guides/vercel-ai-sdk">
    See the API in action
  </Card>

  <Card title="Direct Client" icon="wrench" href="/guides/direct-client">
    Use the MemoryClient wrapper
  </Card>
</CardGroup>