generated: '2026-08-14'
method: searched
source: https://mydreamthreads.xyz/dream-interpretation-api
derived_from: openapi/_original/dreamthreads-dreamgraph-openapi.json
note: >-
  Cross-cutting request/response semantics for the DreamGraph V1 API, read from the developer guide
  and confirmed against the OpenAPI 3.1 contract and one live anonymous call.
authentication:
  style: HTTP bearer
  header: 'Authorization: Bearer <partner key>'
  scope: Applies to POST /interpret and POST /parse only
  keyless_operations: [GET /health, POST /public/parse]
  key_handling: >-
    Keys are hashed at rest, tied to a partner, origin-restricted, rate-limited, pausable and
    rotatable. Partner keys must stay server-side; never place one in browser code.
  see_also: authentication/dreamthreads-authentication.yml
success_envelope:
  shape: '{ data, request_id, version }'
  version_value: v1
  note: All 2xx bodies wrap the payload in `data` and echo `request_id` and the envelope `version`.
error_envelope:
  format: rfc9457
  media_type: application/problem+json
  shape: '{ type, title, status, detail, instance, error{code,message}, request_id, version }'
  backward_compatible: true
  see_also: errors/dreamthreads-problem-types.yml
idempotency:
  supported: false
  request_key_header: null
  note: >-
    No Idempotency-Key header or equivalent is documented or present in the OpenAPI. The write-shaped
    operations are analytic (parse/interpret) rather than state-creating, and the provider states
    dream text is not stored on the public path, so a replay is a fresh computation rather than a
    duplicate record. The two MCP tools carry `idempotentHint: true` annotations, which is a tool
    behaviour hint to agents, not a request-deduplication contract.
request_tracing:
  header: X-Request-ID
  direction: client-supplied, echoed; generated by DreamThreads when absent
  response_header: x-request-id
  body_field: request_id
  problem_field: instance (https://mydreamthreads.xyz/problems/requests/<request_id>)
  observed: true
pagination:
  supported: false
  note: >-
    No collection endpoints in the REST contract; every operation is a single-document analysis or a
    liveness check. The MCP search_dream_concepts tool bounds results with a `limit` (1-12, default 8)
    rather than paginating.
field_expansion:
  supported: false
sparse_fields:
  supported: false
metadata:
  supported: false
versioning:
  scheme: uri-path
  current: v1
  contract_version: 1.1.0
  envelope_version_field: version
  base: https://mydreamthreads.xyz/api/v1/dreamgraph
  see_also: lifecycle/dreamthreads-lifecycle.yml
rate_limit_signaling:
  headers: [RateLimit-Limit, RateLimit-Remaining, RateLimit-Reset, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset]
  reset_format: unix timestamp (seconds)
  exhaustion_status: 429
  retry_after: false
  see_also: rate-limits/dreamthreads-rate-limits.yml
cors:
  public_parser:
    allow_origin: '*'
    allow_methods: [POST, OPTIONS]
    allow_headers: [content-type, x-request-id]
    expose_headers: [x-request-id, ratelimit-limit, ratelimit-remaining, ratelimit-reset, x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset]
    observed: true
  keyed_endpoints: server-side only; partner keys are origin-scoped and must not be used from a browser
caching:
  cache_control: no-store (observed on the public parser)
payload_bounds:
  max_characters_per_dream: 6000
  min_characters_per_dream: 1
  encoding: UTF-8
output_policy:
  note: >-
    A hard editorial convention the provider imposes on consumers: output is reflective, never
    diagnostic, predictive, supernatural, or a fixed statement of meaning. Responses carry an
    `attribution` block with a provider name and a deep link that integrations are expected to
    preserve, and uncertainty language must not be stripped.