# Dream Interpretation API

> Dream interpretation API + hosted MCP for AI agents and developers. Connect Claude Code, Cursor, VS Code in seconds, no local setup. 2,000+ dream symbols with psychological meanings covering animals, objects, emotions, people, scenarios, and abstract concepts. Decode falling dreams, flying dreams, teeth falling out, being chased, water, snakes, and more. Search, browse A-Z, or discover random symbols. Build dream journal apps, AI dream analysis chatbots, sleep tracking features, and wellness platforms. Part of RoxyAPI multi-domain spiritual intelligence.

Ship a dream analysis app with 2,000+ symbols. This weekend.

- Product page: https://roxyapi.com/products/dreams-api
- OpenAPI spec: https://roxyapi.com/api/v2/dreams/openapi.json
- Remote MCP server: https://roxyapi.com/mcp/dreams
- Authentication: `X-API-Key` header on every request
- Pricing: https://roxyapi.com/pricing (all domains included in every plan)

## Stats

- latency: <50ms
- uptime: 99.9%
- endpoints: 5+

## Features

- Complete dream dictionary with 2,000+ symbols covering animals, objects, people, actions, emotions, colors, numbers, and abstract concepts for comprehensive dream analysis
- Psychological interpretations explaining what each symbol represents, why you dream about it, and how it connects to your waking life, relationships, and subconscious mind
- Alphabetical browsing (A-Z) with letter filtering and symbol counts per letter for building dream dictionary interfaces and navigation
- Full-text search across dream symbol names and interpretations to instantly match any dream element, creature, scenario, or emotion
- Random symbol discovery for daily dream insights, symbol of the day features, and interactive exploration experiences in wellness apps
- AI-optimized JSON responses with structured symbol data and interpretations, perfect for MCP-powered dream analysis chatbots and LLM integration

## Use Cases

- Build dream journal apps that interpret entries automatically. Users describe dreams and receive instant psychological insights about recurring symbols like snakes, teeth, flying, and water
- Power AI dream analysis chatbots with MCP. Your OpenAI, Claude, or Gemini agent auto-discovers dream endpoints and delivers conversational dream interpretations
- Create dream dictionary websites and mobile apps with alphabetical browsing, keyword search, random exploration, and 2,000+ symbols with detailed meanings
- Add dream interpretation to sleep tracking apps. Correlate dream themes with sleep quality, stress levels, and daily activities for holistic wellness insights
- Build comprehensive spiritual guidance platforms combining dream analysis with astrology, tarot, numerology, and I-Ching under one API key
- Ship educational psychology platforms teaching dream symbolism, Jungian archetypes, and subconscious mind patterns through interactive dream exploration

## Endpoints

- `GET /api/v2/dreams/symbols` List and search dream symbols
- `GET /api/v2/dreams/symbols/random` Get random dream symbols
- `GET /api/v2/dreams/symbols/letters` Get symbol counts by letter
- `GET /api/v2/dreams/symbols/{id}` Get dream symbol details
- `POST /api/v2/dreams/daily` Get daily dream symbol

### Dream Interpretation (`/dreams/`)
- `GET /dreams/symbols/{id}` — Dream symbol detail (e.g. `flying`, `teeth-falling-out`).
- `GET /dreams/symbols` — Browse catalog.
- `POST /dreams/daily` — Daily dream symbol prompt.

## Example Response

```
GET /api/v2/dreams/symbols/snake
```

```json
{
  "id": "snake",
  "name": "Snake",
  "letter": "s",
  "meaning": "Snakes are one of the oldest dream most misunderstood dream symbols. Depending on how the snake appear, the color, type and charactericts in your dream it will determine if its linked to personal transformation or an enemy. In other cultures dream analysis suggests it is linked to our innate fears, or according to Freud a phallic symbol. If you are bitten by the snake will have a negative connotation attached to it as opposed to seeing it coiled on a rod or eating its own tail."
}
```

## SDK Quick Start

```typescript
// npm install @roxyapi/sdk
import { createRoxy } from '@roxyapi/sdk';
const roxy = createRoxy(process.env.ROXY_API_KEY!);
const { data, error } = await roxy.dreams.getDreamSymbol({ path: { id: 'flying' } });
```

```python
# pip install roxy-sdk
import os
from roxy_sdk import create_roxy
roxy = create_roxy(api_key=os.environ["ROXY_API_KEY"])
result = roxy.dreams.get_dream_symbol(id="flying")
```

```php
// composer require roxyapi/sdk (PHP 8.2+, built on Saloon)
use function RoxyAPI\Sdk\createRoxy;
$roxy = createRoxy(getenv('ROXY_API_KEY'));
$result = $roxy->dreams->getDreamSymbol(id: 'flying');
```

Method names come from OpenAPI `operationId` (camelCase in TS and PHP, snake_case in Python). TS returns `{ data, error, response }` — check `error` first. Python raises `RoxyAPIError`; PHP throws `RoxyApiException` (catch and switch on `$e->errorCode`).

## MCP Tool Naming

Each REST endpoint has a matching MCP tool on `https://roxyapi.com/mcp/dreams`. Tool name convention is `{http_method_lowercase}_{path_with_slashes_as_underscores_kebab_replaced_with_underscores_braces_stripped}`:

```
GET  /dreams/symbols                          -> get_dreams_symbols
GET  /dreams/symbols/random                   -> get_dreams_symbols_random
GET  /dreams/symbols/letters                  -> get_dreams_symbols_letters
```

`tools/list` is free and public (no auth). `tools/call` requires `X-API-Key` (same billing as REST — 1 request per call).

## Field Formats (agent gotchas)

Fields LLMs most often get wrong. Copy the format exactly.

| Field | Format | Good | Bad |
|-------|--------|------|-----|
| Dream symbol `id` | Kebab-case slug | `flying`, `teeth-falling-out`, `water` | Display names with spaces |

**Path hygiene:** no trailing slashes on any endpoint.

## Error Contract

Success returns clean JSON, no wrapper. Errors return `{ "error": string, "code": string }`. Switch on `code` (stable):

- `validation_error` (400, returns `issues[]` with all field errors at once)
- `api_key_required` (401), `invalid_api_key` (401)
- `subscription_inactive` (403), `subscription_not_found` (404)
- `not_found` (404; PATH-routing 404s carry a fuzzy `suggestion` field)
- `rate_limit_exceeded` (429)
- `internal_error` (500)

Do not retry on 4xx. Do retry on 429 and 5xx with exponential backoff.

## Related Surfaces

- **Guide:** [Dreams integration guide](https://roxyapi.com/docs/guides/dreams.md)
- **Starter app:** [Dream Journal App](https://github.com/RoxyAPI/dreams-starter-app) — clone, add an API key, deploy.

## Full Reference

For complete request and response schemas, fetch the OpenAPI spec at https://roxyapi.com/api/v2/dreams/openapi.json. Master agent manifest at https://roxyapi.com/llms.txt. Execution playbook at https://roxyapi.com/AGENTS.md.