openapi: 3.2.0
info:
  title: Anthropic Dreams API
servers:
- url: https://api.anthropic.com
tags:
- name: Dreams
paths:
  /v1/dreams/{dream_id}/archive?beta=true:
    post:
      operationId: BetaArchiveDream
      summary: Archive a Dream
      parameters:
      - name: anthropic-version
        in: header
        required: false
        schema:
          type: string
      - name: anthropic-beta
        in: header
        required: false
        schema:
          type: string
          items:
            type: string
          x-stainless-override-schema:
            x-stainless-param: betas
            x-stainless-extend-default: true
            type: array
            description: Optional header to specify the beta version(s) you want to use.
            items:
              $ref: '#/components/schemas/AnthropicBeta'
      - name: dream_id
        in: path
        required: true
        schema:
          type: string
          x-stainless-cli-data-alias: id
        description: Path parameter dream_id
      responses:
        '200':
          description: Successful response (OK)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDream'
        '400':
          description: Invalid argument - The client specified an invalid argument
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '401':
          description: Unauthenticated - The request does not have valid authentication credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '403':
          description: Permission denied - The caller does not have permission to execute the specified operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '404':
          description: Not found - Some requested entity was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '408':
          description: Deadline exceeded - The deadline expired before the operation could complete
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '409':
          description: Custom error status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '412':
          description: Failed precondition - Operation was rejected because the system is not in required state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '413':
          description: Out of range - Operation was attempted past the valid range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '429':
          description: Resource exhausted - Some resource has been exhausted (rate limiting)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '431':
          description: Request header fields too large - Request metadata was too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '499':
          description: Cancelled - The operation was cancelled by the client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '500':
          description: Internal - Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '501':
          description: Unimplemented - The operation is not implemented or supported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '503':
          description: Unavailable - The service is currently unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '504':
          description: Deadline exceeded - Upstream service did not respond in time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
      x-anthropic-beta-required:
      - dreaming-2026-04-21
      tags:
      - Dreams
  /v1/dreams/{dream_id}/cancel?beta=true:
    post:
      operationId: BetaCancelDream
      summary: Cancel a Dream
      parameters:
      - name: anthropic-version
        in: header
        required: false
        schema:
          type: string
      - name: anthropic-beta
        in: header
        required: false
        schema:
          type: string
          items:
            type: string
          x-stainless-override-schema:
            x-stainless-param: betas
            x-stainless-extend-default: true
            type: array
            description: Optional header to specify the beta version(s) you want to use.
            items:
              $ref: '#/components/schemas/AnthropicBeta'
      - name: dream_id
        in: path
        required: true
        schema:
          type: string
          x-stainless-cli-data-alias: id
        description: Path parameter dream_id
      responses:
        '200':
          description: Successful response (OK)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDream'
        '400':
          description: Invalid argument - The client specified an invalid argument
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '401':
          description: Unauthenticated - The request does not have valid authentication credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '403':
          description: Permission denied - The caller does not have permission to execute the specified operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '404':
          description: Not found - Some requested entity was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '408':
          description: Deadline exceeded - The deadline expired before the operation could complete
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '409':
          description: Custom error status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '412':
          description: Failed precondition - Operation was rejected because the system is not in required state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '413':
          description: Out of range - Operation was attempted past the valid range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '429':
          description: Resource exhausted - Some resource has been exhausted (rate limiting)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '431':
          description: Request header fields too large - Request metadata was too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '499':
          description: Cancelled - The operation was cancelled by the client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '500':
          description: Internal - Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '501':
          description: Unimplemented - The operation is not implemented or supported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '503':
          description: Unavailable - The service is currently unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '504':
          description: Deadline exceeded - Upstream service did not respond in time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
      x-anthropic-beta-required:
      - dreaming-2026-04-21
      tags:
      - Dreams
  /v1/dreams/{dream_id}?beta=true:
    get:
      operationId: BetaGetDream
      summary: Get a Dream
      parameters:
      - name: x-api-key
        in: header
        required: false
        schema:
          type: string
      - name: anthropic-version
        in: header
        required: false
        schema:
          type: string
      - name: anthropic-beta
        in: header
        required: false
        schema:
          type: string
          items:
            type: string
          x-stainless-override-schema:
            x-stainless-param: betas
            x-stainless-extend-default: true
            type: array
            description: Optional header to specify the beta version(s) you want to use.
            items:
              $ref: '#/components/schemas/AnthropicBeta'
      - name: dream_id
        in: path
        required: true
        schema:
          type: string
          x-stainless-cli-data-alias: id
        description: Path parameter dream_id
      responses:
        '200':
          description: Successful response (OK)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDream'
        '400':
          description: Invalid argument - The client specified an invalid argument
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '401':
          description: Unauthenticated - The request does not have valid authentication credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '403':
          description: Permission denied - The caller does not have permission to execute the specified operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '404':
          description: Not found - Some requested entity was not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '408':
          description: Deadline exceeded - The deadline expired before the operation could complete
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '409':
          description: Custom error status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '412':
          description: Failed precondition - Operation was rejected because the system is not in required state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '413':
          description: Out of range - Operation was attempted past the valid range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '429':
          description: Resource exhausted - Some resource has been exhausted (rate limiting)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '431':
          description: Request header fields too large - Request metadata was too large
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '499':
          description: Cancelled - The operation was cancelled by the client
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '500':
          description: Internal - Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '501':
          description: Unimplemented - The operation is not implemented or supported
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '503':
          description: Unavailable - The service is currently unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
        '504':
          description: Deadline exceeded - Upstream service did not respond in time
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BetaDreamingErrorResponse'
      x-anthropic-beta-required:
      - dreaming-2026-04-21
      tags:
      - Dreams
components:
  schemas:
    BetaDreamMemoryStoreOutput:
      description: An output memory store the dream writes consolidated memories into.
      type: object
      additionalProperties: false
      required:
      - type
      - memory_store_id
      properties:
        type:
          type: string
          enum:
          - memory_store
        memory_store_id:
          type: string
    BetaDreamStatus:
      type: string
      description: Lifecycle status of a Dream.
      enum:
      - pending
      - running
      - completed
      - failed
      - canceled
    BetaDreamOutput:
      type: object
      discriminator:
        propertyName: type
        mapping:
          memory_store: '#/components/schemas/BetaDreamMemoryStoreOutput'
      oneOf:
      - $ref: '#/components/schemas/BetaDreamMemoryStoreOutput'
    BetaDreamMemoryStoreInput:
      description: 'An input memory store the dream reads from. The dream never mutates this store unless it is also the destination: with output_behavior {type: "update_existing"} the job consolidates this store in place.'
      type: object
      additionalProperties: false
      required:
      - type
      - memory_store_id
      properties:
        type:
          type: string
          enum:
          - memory_store
        memory_store_id:
          type: string
          minLength: 1
    BetaTimestamp:
      description: A timestamp in RFC 3339 format
      type: string
      format: date-time
    BetaDreamInput:
      type: object
      discriminator:
        propertyName: type
        mapping:
          memory_store: '#/components/schemas/BetaDreamMemoryStoreInput'
          sessions: '#/components/schemas/BetaDreamSessionsInput'
      oneOf:
      - $ref: '#/components/schemas/BetaDreamMemoryStoreInput'
      - $ref: '#/components/schemas/BetaDreamSessionsInput'
    BetaOutputBehavior:
      type: object
      discriminator:
        propertyName: type
        mapping:
          create_new: '#/components/schemas/BetaOutputBehaviorCreateNew'
          update_existing: '#/components/schemas/BetaOutputBehaviorUpdateExisting'
      oneOf:
      - $ref: '#/components/schemas/BetaOutputBehaviorCreateNew'
      - $ref: '#/components/schemas/BetaOutputBehaviorUpdateExisting'
    BetaDreamSessionsInput:
      description: Input session transcripts the dream reads.
      type: object
      additionalProperties: false
      required:
      - type
      - session_ids
      properties:
        type:
          type: string
          enum:
          - sessions
        session_ids:
          type: array
          items:
            type: string
    BetaDream:
      description: 'An asynchronous memory-consolidation job that reads a memory store plus a set of session transcripts and writes consolidated memories into an output memory store — a new store by default, or an existing store chosen via output_behavior. The Dreams API is in research preview: the request and response shapes are volatile and may change without the deprecation period that applies to generally-available endpoints.'
      type: object
      additionalProperties: false
      required:
      - type
      - id
      - inputs
      - outputs
      - status
      - created_at
      - ended_at
      - archived_at
      - error
      - model
      - instructions
      - session_id
      - usage
      - output_behavior
      properties:
        type:
          type: string
          enum:
          - dream
        id:
          type: string
        inputs:
          type: array
          items:
            $ref: '#/components/schemas/BetaDreamInput'
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/BetaDreamOutput'
        status:
          $ref: '#/components/schemas/BetaDreamStatus'
        created_at:
          $ref: '#/components/schemas/BetaTimestamp'
        ended_at:
          anyOf:
          - $ref: '#/components/schemas/BetaTimestamp'
          - type: 'null'
        archived_at:
          anyOf:
          - $ref: '#/components/schemas/BetaTimestamp'
          - type: 'null'
        error:
          anyOf:
          - $ref: '#/components/schemas/BetaDreamError'
          - type: 'null'
        model:
          $ref: '#/components/schemas/BetaDreamModelConfig'
        instructions:
          anyOf:
          - type: string
          - type: 'null'
        session_id:
          anyOf:
          - type: string
          - type: 'null'
        usage:
          $ref: '#/components/schemas/BetaDreamUsage'
        output_behavior:
          $ref: '#/components/schemas/BetaOutputBehavior'
    BetaSpeed:
      type: string
      description: Inference speed mode. `fast` provides significantly faster output token generation at premium pricing. Not all models support `fast`; invalid combinations are rejected at create time.
      enum:
      - standard
      - fast
    BetaDreamUsage:
      description: Cumulative token usage for the dream across every pipeline stage.
      type: object
      additionalProperties: false
      required:
      - input_tokens
      - output_tokens
      - cache_read_input_tokens
      - cache_creation_input_tokens
      properties:
        input_tokens:
          description: Total uncached input tokens consumed across every pipeline stage.
          type: integer
          format: int32
        output_tokens:
          description: Total output tokens generated across every pipeline stage.
          type: integer
          format: int32
        cache_read_input_tokens:
          description: Total tokens read from prompt cache.
          type: integer
          format: int32
        cache_creation_input_tokens:
          description: Total tokens used to create prompt-cache entries (sum of all TTL tiers).
          type: integer
          format: int32
    AnthropicBeta:
      anyOf:
      - type: string
      - type: string
        enum:
        - message-batches-2024-09-24
        - prompt-caching-2024-07-31
        - computer-use-2024-10-22
        - computer-use-2025-01-24
        - pdfs-2024-09-25
        - token-counting-2024-11-01
        - token-efficient-tools-2025-02-19
        - output-128k-2025-02-19
        - files-api-2025-04-14
        - mcp-client-2025-04-04
        - mcp-client-2025-11-20
        - dev-full-thinking-2025-05-14
        - interleaved-thinking-2025-05-14
        - code-execution-2025-05-22
        - extended-cache-ttl-2025-04-11
        - context-1m-2025-08-07
        - context-management-2025-06-27
        - model-context-window-exceeded-2025-08-26
        - skills-2025-10-02
        - fast-mode-2026-02-01
        - output-300k-2026-03-24
        - user-profiles-2026-03-24
        - user-profiles-2026-08-18
        - advisor-tool-2026-03-01
        - managed-agents-2026-04-01
        - cache-diagnosis-2026-04-07
        - dreaming-2026-04-21
        - thinking-token-count-2026-05-13
        - server-side-fallback-2026-06-01
        - server-side-fallback-2026-07-01
        - fallback-credit-2026-06-01
        - fallback-credit-2026-07-01
        - agent-memory-2026-07-22
        - mid-conversation-tool-changes-2026-07-01
        - compact-2026-01-12
        - computer-use-2025-11-24
        - mcp-tunnels-2026-06-22
        - structured-outputs-2025-11-13
        - task-budgets-2026-03-13
        - thinking-display-updates-2026-08-18
        - ce-user-management-2026-07-13
        x-stainless-nominal: false
    BetaOutputBehaviorUpdateExisting:
      description: The job writes the consolidated memories into this existing memory store instead of creating one. In EAP the store must be the job's own memory_store input, so the job consolidates the store in place.
      type: object
      additionalProperties: false
      required:
      - type
      - memory_store_id
      properties:
        type:
          type: string
          enum:
          - update_existing
        memory_store_id:
          type: string
          minLength: 1
    BetaDreamModelConfig:
      description: Model identifier and configuration applied to every pipeline stage. Same wire shape as the Agents API ModelConfig.
      type: object
      additionalProperties: false
      required:
      - id
      properties:
        id:
          description: Model identifier, e.g. "claude-opus-5". 1-256 characters.
          type: string
          minLength: 1
          maxLength: 256
        speed:
          description: Inference speed mode. Defaults to `standard`.
          allOf:
          - $ref: '#/components/schemas/BetaSpeed'
          x-anthropic-beta-required:
          - managed-agents-2026-04-01
          - fast-mode-2026-02-01
    BetaDreamingErrorResponse:
      type: object
      required:
      - type
      - error
      properties:
        type:
          type: string
          const: error
          description: Always "error" for error responses
        error:
          type: object
          discriminator:
            propertyName: type
            mapping:
              conflict_error: '#/components/schemas/BetaTargetStoreHeldError'
          oneOf:
          - $ref: '#/components/schemas/BetaTargetStoreHeldError'
    BetaDreamError:
      description: Failure detail for a Dream whose `status` is `failed`.
      type: object
      additionalProperties: false
      required:
      - type
      - message
      properties:
        type:
          type: string
        message:
          type: string
    BetaOutputBehaviorCreateNew:
      description: 'The default destination: the job creates a new output memory store as a clone of the memory_store input and writes the consolidated memories into it. The input store is never mutated.'
      type: object
      additionalProperties: false
      required:
      - type
      properties:
        type:
          type: string
          enum:
          - create_new
    BetaTargetStoreHeldError:
      description: 'The `output_behavior.memory_store_id` target is still held by a prior `{type: "update_existing"}` dream — one that is `pending` or `running`, or was canceled with its final writes still landing. Rarely the named dream has just finished (`completed`/`failed`) and its execution is still closing; an immediate retry then almost always succeeds. The message names the holding dream when the server can identify it (rarely omitted); poll it to a terminal state or cancel it, then retry. Carried with `x-should-retry: false`.'
      type: object
      additionalProperties: false
      required:
      - type
      properties:
        type:
          type: string
          const: conflict_error
        message:
          description: Human-readable description of the conflict, naming the dream that holds the target store when the server can identify it.
          type: string