{"openapi":"3.1.0","info":{"title":"DreamThreads Dream Interpretation API","version":"1.1.0","summary":"Context-aware dream analysis and structured dream parsing","description":"A context-aware dream interpretation and structured dream parsing API. Outputs are reflective—not diagnostic, predictive, or a substitute for professional care.","termsOfService":"https://mydreamthreads.xyz/terms","license":{"name":"Proprietary; use subject to DreamThreads terms","url":"https://mydreamthreads.xyz/terms"},"contact":{"name":"DreamThreads API","email":"rahim@mydreamthreads.xyz","url":"https://mydreamthreads.xyz/dream-interpretation-api"},"x-logo":{"url":"https://mydreamthreads.xyz/icon.svg","backgroundColor":"#11111c","altText":"DreamThreads crescent moon"}},"externalDocs":{"description":"Dream interpretation API guide and access request","url":"https://mydreamthreads.xyz/dream-interpretation-api"},"servers":[{"url":"https://mydreamthreads.xyz/api/v1/dreamgraph","description":"Production"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Dream interpretation","description":"Generate a tentative, context-aware dream reflection with a factor trace and provenance."},{"name":"Dream parsing","description":"Turn dream text into structured entities, emotions, actions, agency, threat, outcome, and recurrence."}],"paths":{"/health":{"get":{"tags":["Dream parsing"],"security":[],"operationId":"getDreamGraphHealth","summary":"Check DreamGraph API availability","description":"Use this unauthenticated liveness endpoint before an integration test or when diagnosing connectivity. A 200 response confirms that the DreamGraph API edge is reachable; it does not validate a partner key or guarantee that an upstream interpretation model is available.","responses":{"200":{"description":"DreamGraph API edge is reachable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"},"example":{"data":{"status":"ok","service":"dreamgraph","documentation":"https://mydreamthreads.xyz/dream-interpretation-api"},"request_id":"health-request-123","version":"v1"}}}},"500":{"$ref":"#/components/responses/InternalFailure"}}}},"/public/parse":{"post":{"tags":["Dream parsing"],"security":[],"operationId":"parseDreamPublicly","summary":"Parse a dream for free without an API key","description":"Send one UTF-8 dream narrative of 1–6,000 characters plus an optional recurrence hint. No authentication is required. Use this endpoint when an agent or prototype needs structured features—entities, actions, emotions, agency, threat, outcome, sensory cues, and recurrence—without generating an interpretation. Dream text is processed in memory and is not stored or added to the contribution corpus. Limited to 12 requests per minute and 100 per day per client.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicParseRequest"},"example":{"text":"I watched a snake in my garden. I felt peaceful."}}}},"responses":{"200":{"description":"Dream parsed without storing its text","headers":{"RateLimit-Limit":{"description":"Maximum requests in the active rate-limit window.","schema":{"type":"integer","format":"int32","minimum":1,"maximum":100,"example":12}},"RateLimit-Remaining":{"description":"Requests remaining in the active rate-limit window.","schema":{"type":"integer","format":"int32","minimum":0,"maximum":100,"example":11}},"RateLimit-Reset":{"description":"Unix timestamp in seconds when the active window resets.","schema":{"type":"integer","format":"int64","minimum":0,"maximum":9999999999,"example":1786635600}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicParseResponse"},"example":{"data":{"structured_dream":{"schemaVersion":"structured-dream-v1","parserVersion":"dream-parser-rules-v1.0.0","dreamGraphVersion":"dreamgraph-v0.1.0","entities":[],"actors":[],"locations":[],"actions":[{"type":"observation","confidence":0.9}],"emotions":[{"label":"calm","valence":"positive","intensity":"medium","explicitlyNegated":false}],"agency":{"level":"low","mode":"passive_observation","evidence":"dreamer watched without intervening"},"threat":{"present":false,"level":"low","basis":"low fear or positive emotional response"},"outcome":{"status":"unresolved","valence":"unknown"},"sensory":{"sound":"quiet"},"recurrence":{"known":false,"frequency":null},"wakingContext":{"supplied":false},"physiologicalContext":{"supplied":false,"cues":[]},"unknownConcepts":[]},"timing":{"parser_latency_ms":2},"privacy":{"dream_text_stored":false,"contribution_created":false},"upgrade":{"interpretation_api":"https://mydreamthreads.xyz/dream-interpretation-api#request-access"}},"request_id":"public-request-123","version":"v1"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableDream"},"429":{"$ref":"#/components/responses/RateLimited"},"500":{"$ref":"#/components/responses/InternalFailure"}}}},"/interpret":{"post":{"tags":["Dream interpretation"],"operationId":"interpretDream","summary":"Generate a context-aware dream interpretation","description":"Requires a reviewed DreamThreads partner bearer key. Send one UTF-8 dream narrative of 1–6,000 characters and, when available, a short interpretive lens plus waking-life or physiological context. Use this endpoint only when a user wants a tentative reflection; use parseDream when structured extraction is sufficient. The response contains the reflection, symbols, an open question, a factor-level reason trace, provenance, diagnostics, timing, and an attributed DreamThreads deep link. Output is reflective—not diagnostic, predictive, or a fixed statement of meaning.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/InterpretRequest"},"example":{"text":"I watched a snake in my garden. I felt peaceful.","waking_context":"I recently started caring for a garden."}}}},"responses":{"200":{"description":"Interpretation completed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InterpretResponse"},"example":{"data":{"interpretation":{"essence":"The dream may be holding change and attention together without treating either as a threat.","symbols":[{"symbol":"snake","note":"Because you felt peaceful, the snake may point toward alertness or change rather than danger."}],"reading":"The garden places the image in something you actively tend. Your calm response matters: it weakens a simple threat reading. The dream may be exploring how you relate to a change that asks for attention without requiring panic.","question":"What change are you willing to observe before deciding what it means?","reasonTrace":[{"factor":"emotion","value":"peaceful","effect":"weakens threat-first readings"}],"provenance":[],"dreamgraphVersion":"dreamgraph-v0.1.0","parserVersion":"dream-parser-rules-v1.0.0","engineVersion":"dreamgraph-interpretation-v1"},"diagnostic":{"unsupportedCount":0},"timing":{"parserLatencyMs":2,"totalLatencyMs":680},"attribution":{"provider":"DreamThreads","deep_link":"https://mydreamthreads.xyz/?utm_source=partner&utm_medium=api"}},"request_id":"partner-request-123","version":"v1"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"429":{"$ref":"#/components/responses/RateLimited"},"502":{"$ref":"#/components/responses/UpstreamFailure"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}},"/parse":{"post":{"tags":["Dream parsing"],"operationId":"parseDream","summary":"Parse a dream into structured context","description":"Requires a reviewed DreamThreads partner bearer key. Send one UTF-8 dream narrative of 1–6,000 characters plus optional waking-life, physiological, or recurrence context. Use this endpoint for downstream indexing, journaling, research, routing, or analytics when a user-facing interpretation is not needed. The response returns structured entities, actors, locations, actions, emotions, agency, threat, outcome, sensory cues, recurrence, context flags, parser version, and timing; it does not generate a meaning claim.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParseRequest"},"example":{"text":"I watched a snake in my garden. I felt peaceful."}}}},"responses":{"200":{"description":"Dream parsed into structured context","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ParseResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"413":{"$ref":"#/components/responses/PayloadTooLarge"},"422":{"$ref":"#/components/responses/UnprocessableDream"},"429":{"$ref":"#/components/responses/RateLimited"},"503":{"$ref":"#/components/responses/ServiceUnavailable"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"DreamThreads partner API key"}},"schemas":{"InterpretRequest":{"type":"object","description":"Inputs for a context-aware, tentative dream reflection.","additionalProperties":false,"required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":6000,"description":"Dream text. Keep the key server-side and obtain appropriate user consent before transmitting personal content."},"lens":{"type":"string","maxLength":80,"description":"Optional interpretive emphasis, such as emotional processing or recurring patterns.","example":"emotional processing"},"waking_context":{"type":"string","maxLength":2000,"description":"Optional waking-life context supplied by the dreamer; omit rather than infer it.","example":"I recently started caring for a garden."},"physiological_context":{"type":"string","maxLength":1000,"description":"Optional sleep, health, medication, or physical context explicitly supplied by the dreamer.","example":"I woke briefly before the dream."}}},"ParseRequest":{"type":"object","description":"Inputs for authenticated structured dream extraction without a generated interpretation.","additionalProperties":false,"required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":6000,"description":"UTF-8 dream narrative to parse.","example":"I watched a snake in my garden. I felt peaceful."},"waking_context":{"type":"string","maxLength":2000,"description":"Optional waking-life context supplied by the dreamer.","example":"I recently started caring for a garden."},"physiological_context":{"type":"string","maxLength":1000,"description":"Optional physiological or sleep context supplied by the dreamer.","example":"I woke briefly before the dream."},"recurrence":{"type":["boolean","string"],"description":"Whether the dream recurs, or a short user-supplied frequency label.","example":"monthly"}}},"PublicParseRequest":{"type":"object","description":"Inputs for the bounded no-key parser. Submitted text is processed in memory and is not stored.","additionalProperties":false,"required":["text"],"properties":{"text":{"type":"string","minLength":1,"maxLength":6000,"description":"UTF-8 dream narrative. It is processed in memory and is not stored or contributed.","example":"I watched a snake in my garden. I felt peaceful."},"recurrence":{"type":["boolean","string"],"description":"Optional user-supplied recurrence hint; the service does not infer frequency from missing context.","example":false}}},"Error":{"type":"object","description":"RFC 9457 Problem Details response with backward-compatible DreamThreads error fields.","additionalProperties":false,"required":["type","title","status","detail","instance","error","request_id","version"],"properties":{"type":{"type":"string","format":"uri","description":"Stable URI identifying the machine-readable problem type.","example":"https://mydreamthreads.xyz/problems/invalid-dream"},"title":{"type":"string","description":"Short, human-readable summary of the problem class.","example":"DreamThreads API request failed"},"status":{"type":"integer","format":"int32","minimum":400,"maximum":599,"description":"HTTP status code returned for this occurrence.","example":400},"detail":{"type":"string","description":"Human-readable explanation specific to this occurrence.","example":"Dream text must contain 1-6000 characters."},"instance":{"type":"string","format":"uri","description":"Request-specific problem occurrence identifier.","example":"https://mydreamthreads.xyz/problems/requests/example-request-123"},"error":{"type":"object","description":"Backward-compatible DreamThreads error object.","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code.","example":"invalid_dream"},"message":{"type":"string","description":"Human-readable error message.","example":"Dream text must contain 1-6000 characters."}}},"request_id":{"type":"string","description":"Correlation identifier echoed from X-Request-ID or generated by DreamThreads.","example":"example-request-123"},"version":{"type":"string","description":"DreamThreads API envelope version.","example":"v1"}}},"HealthResponse":{"type":"object","description":"Standard success envelope returned by the unauthenticated liveness endpoint.","additionalProperties":false,"required":["data","request_id","version"],"properties":{"data":{"type":"object","description":"Current DreamGraph API edge status.","additionalProperties":false,"required":["status","service","documentation"],"properties":{"status":{"type":"string","enum":["ok"],"description":"Liveness state of the API edge.","example":"ok"},"service":{"type":"string","const":"dreamgraph","description":"Stable service identifier.","example":"dreamgraph"},"documentation":{"type":"string","format":"uri","description":"Canonical human-readable API documentation.","example":"https://mydreamthreads.xyz/dream-interpretation-api"}}},"request_id":{"type":"string","description":"Request correlation identifier.","example":"health-request-123"},"version":{"type":"string","description":"DreamThreads API envelope version.","example":"v1"}}},"Interpretation":{"type":"object","description":"Tentative reflection and transparent factors used to produce it.","required":["essence","symbols","reading","question","reasonTrace","provenance"],"properties":{"essence":{"type":"string","description":"One-sentence tentative synthesis, written with uncertainty rather than certainty.","example":"The dream may be holding change and attention together without treating either as a threat."},"symbols":{"type":"array","description":"Context-qualified observations about prominent dream elements.","items":{"type":"object","additionalProperties":false,"required":["symbol","note"],"properties":{"symbol":{"type":"string","description":"Dream element as it appeared in the narrative.","example":"snake"},"note":{"type":"string","description":"Tentative note qualified by the dream's context and emotion.","example":"Because you felt peaceful, the snake may point toward alertness or change rather than danger."}}}},"reading":{"type":"string","description":"Longer reflective synthesis grounded in the supplied narrative and context.","example":"Your calm response weakens a simple threat reading and may invite attention before judgment."},"question":{"type":"string","description":"Open-ended reflection question; never a diagnosis or prediction.","example":"What change are you willing to observe before deciding what it means?"},"reasonTrace":{"type":"array","description":"Factors that materially changed or constrained the reading.","items":{"type":"object","additionalProperties":true,"description":"One factor, its observed value, and its effect on the reading."}},"provenance":{"type":"array","description":"Reviewed source or DreamGraph claim references used in the response.","items":{"type":"object","additionalProperties":true,"description":"Typed provenance record for a supporting claim."}},"dreamgraphVersion":{"type":"string","description":"DreamGraph knowledge version used for this response.","example":"dreamgraph-v0.1.0"},"parserVersion":{"type":"string","description":"Structured parser version used for this response.","example":"dream-parser-rules-v1.0.0"},"engineVersion":{"type":"string","description":"Interpretation engine version used for this response.","example":"dreamgraph-interpretation-v1"}}},"InterpretResponse":{"type":"object","description":"Standard success envelope for a completed context-aware reflection.","additionalProperties":false,"required":["data","request_id","version"],"properties":{"data":{"type":"object","description":"Interpretation result, diagnostics, latency, and required attribution.","additionalProperties":false,"required":["interpretation","diagnostic","timing","attribution"],"properties":{"interpretation":{"$ref":"#/components/schemas/Interpretation"},"diagnostic":{"type":"object","additionalProperties":true,"description":"Quality diagnostics, including unsupported-assertion counts when available."},"timing":{"type":"object","additionalProperties":true,"description":"Parser and end-to-end latency measurements in milliseconds."},"attribution":{"type":"object","description":"Attribution that integrations must preserve.","additionalProperties":false,"required":["provider","deep_link"],"properties":{"provider":{"type":"string","const":"DreamThreads","description":"Required provider credit.","example":"DreamThreads"},"deep_link":{"type":"string","format":"uri","description":"Request-attributed DreamThreads return link.","example":"https://mydreamthreads.xyz/?utm_source=partner&utm_medium=api"}}}}},"request_id":{"type":"string","description":"Request correlation identifier.","example":"partner-request-123"},"version":{"type":"string","description":"DreamThreads API envelope version.","example":"v1"}}},"ParseResponse":{"type":"object","description":"Standard success envelope for authenticated structured dream extraction.","additionalProperties":false,"required":["data","request_id","version"],"properties":{"data":{"type":"object","description":"Structured extraction and parser timing.","additionalProperties":false,"required":["structured_dream","timing"],"properties":{"structured_dream":{"type":"object","additionalProperties":true,"description":"Versioned structured dream containing observed features; no generated meaning claim is included."},"timing":{"type":"object","description":"Parser latency measurement.","additionalProperties":false,"required":["parser_latency_ms"],"properties":{"parser_latency_ms":{"type":"integer","format":"int32","minimum":0,"maximum":3600000,"description":"Server-side parsing time in milliseconds.","example":2}}}}},"request_id":{"type":"string","description":"Request correlation identifier.","example":"partner-request-123"},"version":{"type":"string","description":"DreamThreads API envelope version.","example":"v1"}}},"PublicParseResponse":{"type":"object","description":"Standard success envelope for no-key structured dream extraction.","additionalProperties":false,"required":["data","request_id","version"],"properties":{"data":{"type":"object","description":"Structured extraction, timing, privacy guarantees, and partner upgrade link.","additionalProperties":false,"required":["structured_dream","timing","privacy","upgrade"],"properties":{"structured_dream":{"type":"object","additionalProperties":true,"description":"Versioned structured dream containing observed features; no generated meaning claim is included."},"timing":{"type":"object","description":"Parser latency measurement.","additionalProperties":false,"required":["parser_latency_ms"],"properties":{"parser_latency_ms":{"type":"integer","format":"int32","minimum":0,"maximum":3600000,"description":"Server-side parsing time in milliseconds.","example":2}}},"privacy":{"type":"object","description":"Machine-readable guarantees for the public parser request.","additionalProperties":false,"required":["dream_text_stored","contribution_created"],"properties":{"dream_text_stored":{"type":"boolean","const":false,"description":"Always false: submitted dream text is not persisted.","example":false},"contribution_created":{"type":"boolean","const":false,"description":"Always false: the request does not create a DreamGraph contribution.","example":false}}},"upgrade":{"type":"object","description":"Where a reviewed integration can request context-aware interpretation access.","additionalProperties":false,"required":["interpretation_api"],"properties":{"interpretation_api":{"type":"string","format":"uri","description":"Canonical partner access request URL.","example":"https://mydreamthreads.xyz/dream-interpretation-api#request-access"}}}}},"request_id":{"type":"string","description":"Request correlation identifier.","example":"public-request-123"},"version":{"type":"string","description":"DreamThreads API envelope version.","example":"v1"}}}},"responses":{"BadRequest":{"description":"The JSON body or dream input is invalid.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"https://mydreamthreads.xyz/problems/invalid_dream","title":"DreamThreads API request failed","status":400,"detail":"Dream text must contain 1-6000 characters.","instance":"https://mydreamthreads.xyz/problems/requests/example-request-123","error":{"code":"invalid_dream","message":"Dream text must contain 1-6000 characters."},"request_id":"example-request-123","version":"v1"}}}},"Unauthorized":{"description":"The partner key is missing, invalid, or inactive.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"https://mydreamthreads.xyz/problems/invalid_api_key","title":"DreamThreads API request failed","status":401,"detail":"A valid DreamThreads API key is required.","instance":"https://mydreamthreads.xyz/problems/requests/example-request-123","error":{"code":"invalid_api_key","message":"A valid DreamThreads API key is required."},"request_id":"example-request-123","version":"v1"}}}},"RateLimited":{"description":"The active client or partner request quota is exhausted.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"https://mydreamthreads.xyz/problems/rate_limit_exceeded","title":"DreamThreads API request failed","status":429,"detail":"The active request quota is exhausted.","instance":"https://mydreamthreads.xyz/problems/requests/example-request-123","error":{"code":"rate_limit_exceeded","message":"The active request quota is exhausted."},"request_id":"example-request-123","version":"v1"}}}},"PayloadTooLarge":{"description":"The HTTP request body exceeds the service limit.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"https://mydreamthreads.xyz/problems/payload_too_large","title":"DreamThreads API request failed","status":413,"detail":"Request payload is too large.","instance":"https://mydreamthreads.xyz/problems/requests/example-request-123","error":{"code":"payload_too_large","message":"Request payload is too large."},"request_id":"example-request-123","version":"v1"}}}},"UnprocessableDream":{"description":"The dream narrative passed validation but could not be parsed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"https://mydreamthreads.xyz/problems/parse_failed","title":"DreamThreads API request failed","status":422,"detail":"The dream narrative could not be parsed.","instance":"https://mydreamthreads.xyz/problems/requests/example-request-123","error":{"code":"parse_failed","message":"The dream narrative could not be parsed."},"request_id":"example-request-123","version":"v1"}}}},"UpstreamFailure":{"description":"The interpretation model or supporting upstream service failed.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"https://mydreamthreads.xyz/problems/interpretation_failed","title":"DreamThreads API request failed","status":502,"detail":"Interpretation failed.","instance":"https://mydreamthreads.xyz/problems/requests/example-request-123","error":{"code":"interpretation_failed","message":"Interpretation failed."},"request_id":"example-request-123","version":"v1"}}}},"ServiceUnavailable":{"description":"The requested DreamGraph capability is temporarily unavailable or disabled.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"https://mydreamthreads.xyz/problems/feature_disabled","title":"DreamThreads API request failed","status":503,"detail":"DreamGraph external API is not enabled.","instance":"https://mydreamthreads.xyz/problems/requests/example-request-123","error":{"code":"feature_disabled","message":"DreamGraph external API is not enabled."},"request_id":"example-request-123","version":"v1"}}}},"InternalFailure":{"description":"The DreamGraph API edge encountered an unexpected internal error.","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"type":"https://mydreamthreads.xyz/problems/internal_error","title":"DreamThreads API request failed","status":500,"detail":"An unexpected internal error occurred.","instance":"https://mydreamthreads.xyz/problems/requests/example-request-123","error":{"code":"internal_error","message":"An unexpected internal error occurred."},"request_id":"example-request-123","version":"v1"}}}}}}}