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