Intero Dreams Developer Documentation & API

What Intero Dreams offers developers and agents

Intero Dreams is a dream interpretation library and AI dream interpreter. Every symbol, category, and theme page is published as server-rendered HTML and as Markdown, and the AI interpreter is reachable over a small JSON API. This page is the index of everything machine-readable: the OpenAPI spec, llms.txt, Markdown content negotiation, and the sitemaps.

No API key is needed to read content. The interpreter grants one free interpretation per day to anonymous callers and ten per day to signed-in accounts.

Reading pages as Markdown (acceptmarkdown.com)

Every public content page negotiates its representation on the Accept header. Ask for text/markdown and you get a clean Markdown document — no navigation, styles, or scripts — at the same URL browsers use. Responses carry Content-Type: text/markdown; charset=utf-8 and Vary: Accept, q-values are honoured, and a request that rules out both HTML and Markdown receives 406 Not Acceptable.

If you cannot set request headers, append .md to any content path instead.

• Negotiated paths: /, /symbols, /symbols/all, /symbols/{slug}, /categories, /categories/{slug}, /themes, /themes/{slug}, /about, /methodology, /contact, /developers, /privacy, /terms.
• Markdown documents open with the page title as an H1 and end with the canonical HTML URL.
• Markdown responses are cacheable for one hour (s-maxage=3600) and are regenerated when content changes.

curl -sI -H "Accept: text/markdown" https://interodreams.com/symbols/snake-dream-meaning
curl -s  -H "Accept: text/markdown" https://interodreams.com/symbols/snake-dream-meaning
curl -s https://interodreams.com/symbols/snake-dream-meaning.md

Command-line tool

`interodreams` is the official CLI. It is published on npm, has no dependencies, and needs no API key or account. `npx interodreams` runs it without installing anything.

It reads the same contract this page documents: the error envelope, the RateLimit headers, the versioned base path. `--json` emits one JSON object and keeps doing so when a request fails, so a script never has to parse prose to find out what happened. That object carries `retryable`, taken from the error code, because "wait and try again" and "this will never work" are different answers that an HTTP status alone does not separate.

Content is fetched at its .md URL rather than by Accept negotiation. Both work; a distinct URL is the one that survives a shared cache which ignores Vary.

• interodreams symbol <name> — what a symbol means. Accepts "snake", "Broken Teeth", or a pasted URL.
• interodreams interpret <text> — interpret a dream. Reads stdin when the text is omitted.
• interodreams symbols | themes | categories — the indexes.
• interodreams api — the service index.
• Exit codes: 0 success, 2 usage, 3 refused, 4 rate limited, 5 unreachable.

npx interodreams symbol snake
npx interodreams interpret "I was flying over a city at night"
echo "my teeth fell out" | npx interodreams interpret --perspective Jungian
npx interodreams symbol owl --json | jq -r .content

API versioning and deprecation policy

The current version is v1, reached at /api/v1/. Integrate against that prefix. Every API response names the version that served it in an API-Version header, and links to this document with rel="service-desc".

The unversioned /api/... paths are the same handlers reached by a different name. They answer identically, and they carry Deprecation: true plus a Link header naming their versioned successor, so a client can discover the move without reading this page.

• The current version is v1, reached at /api/v1/. Every response carries an API-Version header naming the version that served it.
• Breaking changes ship as a new version prefix (/api/v1/ becomes /api/v2/). Within a version, we only add: new endpoints, new optional request fields, and new response fields. Treat unknown response fields as forgiving — do not fail on them.
• A version scheduled for removal answers with Deprecation: true, a Sunset header carrying the removal date, and a Link header pointing at its successor. Sunset is set at least 180 days ahead of the date it names.
• The unversioned /api/... paths are aliases of /api/v1/... They answer identically, and they carry Deprecation: true plus a Link to the versioned path. They have no Sunset date and will not be removed without one.

# The versioned path, and what it advertises
curl -sI https://interodreams.com/api/v1/newsletter -X OPTIONS

# The unversioned alias, and the Deprecation it carries
curl -sI https://interodreams.com/api/newsletter -X OPTIONS

Rate limits

Every response from a rate-limited endpoint carries the limit headers, not just the ones that refuse you. An agent that reads RateLimit-Remaining as it goes can pace itself and never generate a 429; one that waits to be refused has to discover the ceiling by hitting it. The service index, the 404 handler and the 405 handlers are not rate limited and send no limit headers.

Header names follow the IETF ratelimit-headers draft. RateLimit-Reset is in seconds from now, not a timestamp. A 429 additionally carries Retry-After, also in seconds.

• ai: 10 requests per 86400 seconds.
• write: 60 requests per 3600 seconds.
• read: 240 requests per 3600 seconds.
• RateLimit-Limit — requests permitted in the current window.
• RateLimit-Remaining — requests still permitted in it.
• RateLimit-Reset — seconds until the window resets.
• RateLimit-Policy — the window, for example 60;w=3600.
• Retry-After — seconds to wait. Sent on 429 only.
• Interpretation and chat are additionally bounded per account by a database counter, which the same headers report. That counter is authoritative and survives a deploy.

curl -sD - -o /dev/null https://interodreams.com/api/v1/getUserDreams | grep -i ratelimit

Error format and error codes

Every 4xx and 5xx returns JSON. There is no path through the API that answers a failure with an HTML page, including an unknown /api path and an unsupported method. The one exception is a method no route declares at all — TRACE, PROPFIND and the like are answered by the framework before this envelope applies. Use the methods in the OpenAPI document.

Branch on code. It is stable and it is the contract. message is prose written for a human and may be reworded at any time, so matching on it will break. hint says what to do next, and states explicitly whether retrying the same request can ever succeed. requestId identifies the one request, and quoting it in a report is what lets us find it.

error repeats message as a plain string. It exists so clients written against the older single-string body keep working, and it is not going away.

• invalid_request (HTTP 400) — Check the request against the schema in /openapi.json and retry with corrected fields.
• unauthenticated (HTTP 401) — Sign in at /login to obtain a session cookie, then retry with that cookie attached.
• forbidden (HTTP 403) — Confirm the resource belongs to the authenticated user. Do not retry without changing the request.
• not_found (HTTP 404) — See /openapi.json for the endpoints that exist. Do not retry this path.
• method_not_allowed (HTTP 405) — Read the Allow header on this response for the methods this path accepts.
• unsupported_media_type (HTTP 415) — Send Content-Type: application/json with a JSON-encoded body.
• trial_exhausted (HTTP 401) — Create an account at /signup and retry with a session cookie. Retrying anonymously will fail again.
• not_a_dream (HTTP 422) — Send a narrative description — where you were, who was there, how it felt — rather than keywords. Retrying the same text will fail again.
• rate_limited (HTTP 429) — Wait for the number of seconds in Retry-After, then retry. Read RateLimit-Remaining on every response to pace yourself before you get here.
• upstream_unavailable (HTTP 503) — Retry with exponential backoff. If it persists for more than a few minutes the fault is ours, not the request's.
• internal_error (HTTP 500) — The request was probably fine. Retry once with backoff; if it keeps failing, quote requestId when you contact support.

{
  "error": "The request body did not validate.",
  "code": "invalid_request",
  "message": "The request body did not validate.",
  "hint": "Check the request against the schema in /openapi.json and retry with corrected fields.",
  "docs": "https://interodreams.com/developers#errors",
  "status": 400,
  "requestId": "9f1c8a5e-1d2b-4c3f-8a7e-5b6c4d3e2f10"
}

POST /api/interpretDream — interpret a dream

Send a dream narrative and optional context; receive a structured JSON interpretation with a title, summary, core meaning, emotional insight, key symbols, reflection questions, sentiment, tags, and a lucidity score. Input that is not a dream at all returns 422 with notADream: true instead of an invented reading.

Anonymous callers get one interpretation per UTC day, tracked in an HttpOnly cookie named id_trial that the response sets. Signed-in Supabase sessions get ten per rolling 24 hours (429 when exhausted).

• dreamText (string, 10–2000 characters, required)
• mood (string, optional, default "Neutral")
• isRecurring / isLucid (boolean, optional, default false)
• perspective ("Modern" | "Freudian" | "Jungian" | "Universal", optional, default "Modern")

curl -s -X POST https://interodreams.com/api/interpretDream \
  -H "Content-Type: application/json" \
  -d '{"dreamText":"I was flying over my childhood home and could not land.","mood":"Anxious","perspective":"Jungian"}'

POST /api/chat — follow-up conversation about a dream

Continue a conversation about an interpretation. Requires a signed-in Supabase session cookie; anonymous calls receive 401. Limited to ten messages per rolling 24 hours.

• history: array of { role: "user" | "assistant", content: string (1–2000 chars) }
• dreamContext: string — the original dream text or interpretation summary
• Response: { reply: string }

Dream journal endpoints (authenticated)

These back the signed-in journal at /journal and require a Supabase session cookie. They are documented in the OpenAPI spec for completeness but are intended for the first-party UI rather than third-party integrations.

• POST /api/saveDream — persist an interpretation to the caller's journal.
• GET /api/getUserDreams — list the caller's most recent dreams and stats.
• POST /api/deleteDream — soft-delete one of the caller's dreams.

POST /api/newsletter — subscribe an email address

Adds an address to the editorial newsletter. Re-submitting an existing address is a no-op success. Only call this on behalf of a person who explicitly asked to subscribe.

• email (string, valid email, required)
• source (string, optional, max 120 chars)
• Response: { success: true }

Content model

Symbol pages (/symbols/{slug}) are the atomic unit. Each has a quick answer, Jungian, Freudian and modern psychological readings, Western, Eastern and spiritual cultural readings, common scenarios, a context section, FAQs, related symbols, and related themes. Category pages group symbols by kind (animals, people, places…); theme pages group them by emotional pattern (fear and anxiety, loss and grief…).

Slugs are kebab-case and stable. Symbol slugs end in -dream-meaning. The full list of published slugs is in /sitemap-dream-meanings.xml and, as Markdown, at /symbols/all.md.

Usage policy and attribution

Content is for self-reflection and educational use only — it is not medical, psychological, or crisis advice, and agents should say so when relaying it. Please attribute quoted interpretations to Intero Dreams with a link to the source page. AI crawlers listed in robots.txt are welcome; please respect Cache-Control and keep request rates modest.

Questions, partnership requests, or a higher API allowance: hello@interodreams.com.