# Dream Interpretation API, what to build and how to call it

> Ship a dream journal, a symbol lookup tool, or an AI dream-interpretation chatbot in under 15 minutes. Thousands of symbols included.

`dream meaning` is among the highest-volume spiritual searches on Google. Every "what does it mean to dream about X" page maps to a single endpoint here. Roxy ships 2500+ dream symbols with psychological and spiritual interpretations, searchable, browsable A to Z.

## What you can build

- Dream journal apps that tag entries with symbols and show meanings
- Symbol lookup tools (pure content SEO surface)
- AI dream-interpretation chatbots
- Daily dream-symbol widgets for journaling apps

## Prerequisites

1. A Roxy API key. Get one on the [pricing page](/pricing).
2. Nothing else. Content is pure GET.

## Install


### npm
```bash
npm install @roxyapi/sdk
```

### Python
```bash
pip install roxy-sdk
```

### PHP
```bash
composer require roxyapi/sdk
```

Set the API key once at SDK construction. Detailed setup in [SDK install + usage](/docs/sdk).

## Call the endpoint

The #1 dream call is symbol lookup. Kebab-case IDs like `water`, `teeth-falling-out`, `being-chased`. Pick a language.


### curl
```bash
curl "https://roxyapi.com/api/v2/dreams/symbols/water" \
  -H "X-API-Key: $ROXY_API_KEY"
```

### TypeScript SDK
```typescript
import { createRoxy } from '@roxyapi/sdk';

const roxy = createRoxy(process.env.ROXY_API_KEY!);

const { data } = await roxy.dreams.getDreamSymbol({
  path: { id: 'water' },
});

console.log(data.name);
console.log(data.meaning);
```

### Python SDK
```python
import os
from roxy_sdk import create_roxy

roxy = create_roxy(os.environ['ROXY_API_KEY'])

symbol = roxy.dreams.get_dream_symbol(id='water')
print(symbol['name'])
print(symbol['meaning'])
```

### PHP SDK
```php
<?php

use function RoxyAPI\Sdk\createRoxy;

$roxy = createRoxy(getenv('ROXY_API_KEY'));

$symbol = $roxy->dreams->getDreamSymbol(id: 'water');
echo $symbol['name'];
echo $symbol['meaning'];
```

### MCP
```bash
claude mcp add-json --scope user roxy-dreams '{"type":"http","url":"https://roxyapi.com/mcp/dreams","headers":{"X-API-Key":"YOUR_KEY"}}'
```

Then ask Claude, "what does dreaming about water mean?" The agent calls the symbol tool and returns the interpretation. Full setup for Cursor, Claude Desktop, Antigravity, and other clients: [MCP guide](/docs/mcp).

Response:

```json
{
  "id": "water",
  "name": "Water",
  "letter": "w",
  "meaning": "Water in dreams represents your emotional state and subconscious mind..."
}
```

## Render the result

Use the generic `<roxy-data>` renderer from [`@roxyapi/ui`](/docs/ui), exposed in React as `RoxyData`. It accepts any RoxyAPI response and lays out the JSON for you, no per-field markup. Pass the unwrapped symbol `data` straight in.

```tsx
'use client';
import { RoxyData } from '@roxyapi/ui-react';
import type { GetDreamsSymbolsByIdResponse } from '@roxyapi/sdk';

export function DreamSymbol({ data }: { data: GetDreamsSymbolsByIdResponse }) {
  return <RoxyData data={data} />;
}
```

`data` is the unwrapped SDK response (`const { data } = await roxy.dreams.getDreamSymbol(...)`), typed by `GetDreamsSymbolsByIdResponse` from `@roxyapi/sdk`. The renderer surfaces the `name` and `meaning` fields without bespoke code.

## Ship the rest

### Search and browse

[`GET /dreams/symbols`](/api-reference#tag/dreams/GET/dreams/symbols) returns a paginated list. Pass `q=flying` for keyword matches, `letter=a` for the A index, `limit` and `offset` for pagination.

### Daily dream symbol

[`POST /dreams/daily`](/api-reference#tag/dreams/POST/dreams/daily) returns a symbol-of-the-day with an optional `seed` for per-user determinism.

See the full list at the [Dreams API reference](/api-reference#tag/dreams).

## Ready-made starter

The [/starters/dreams-starter-app](/starters/dreams-starter-app) starter ships a working Dream interpretation app you can clone, white-label, and deploy in 30 minutes. MIT licensed. For the render layer, see the component catalog in [@roxyapi/ui](/docs/ui).

## Gotchas

- **Symbol IDs are kebab-case.** `teeth-falling-out`, not `teethFallingOut` or `teeth_falling_out`.
- **Dreams content is English-only.** Unlike other domains, translations are not yet shipped.
- **The search endpoint returns summaries.** Each result has `id`, `name`, and `letter`. Fetch [`/dreams/symbols/{id}`](/api-reference#tag/dreams/GET/dreams/symbols/{id}) for the full meaning.
- **The daily endpoint is seeded.** Same `(seed, date)` returns the same symbol (deterministic for notifications).

## What to build next

For an AI dream-interpretation chatbot, the [AI chatbot tutorial](/docs/tutorials/ai-chatbot) shows MCP wiring across domains. For typed access, the [SDK guide](/docs/sdk) covers search parameters.