openapi: 3.2.0
info:
  title: DreamThreads Dream Interpretation Dream parsing 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
servers:
- url: https://mydreamthreads.xyz/api/v1/dreamgraph
  description: Production
security:
- bearerAuth: []
tags:
- 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'
  /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:
  schemas:
    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
    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
    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
    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
    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
  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
    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
    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
    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
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: DreamThreads partner API key
externalDocs:
  description: Dream interpretation API guide and access request
  url: https://mydreamthreads.xyz/dream-interpretation-api