Sign in
Async Messages

Initiate Async Chat Stream

Initiate an asynchronous chat completion stream.

This endpoint starts an asynchronous chat completion process that streams events. Unlike synchronous chat, this endpoint returns immediately with a message_id that can be used to observe the stream progress.

Key Features:

  • Asynchronous Processing: Non-blocking request handling with immediate response
  • Stream Observation: Use returned message_id to observe real-time events
  • Works exactly like synchronous chat, but in an async manner

Notes:

  • Optional message_id query parameter for custom stream identification
  • Stream events follow the same format as synchronous chat responses
  • Stream status can be monitored via status endpoint
post/v1/messages/async

Query parameters

message_idstring nullable

Optional custom identifier for the stream. If not provided, a unique ID will be generated automatically.

Example:custom_msg_12345

Optional custom identifier for the stream. If not provided, a unique ID will be generated automatically.

Request body

modelstring required

Model identifier or alias.

streamboolean

Whether to stream the response back to the client.

containerstring nullable

Container identifier for reuse across requests.

priorityinteger nullable

Priority of the request, used for prioritizing responses.

seedinteger nullable

Random seed for reproducibility.

min_pnumber nullable

Minimum probability threshold for token selection. Tokens with probability below this value are filtered out.

top_pnumber

Nucleus sampling parameter. Only tokens with cumulative probability up to this value are considered.

temperaturenumber

Controls randomness in generation. Higher values make output more random, lower values more deterministic.

top_kinteger

Limits token selection to the top K most likely tokens at each step.

repetition_penaltynumber nullable

Penalty applied to tokens that have already appeared in the sequence to reduce repetition.

presence_penaltynumber nullable

Penalty applied based on whether a token has appeared in the text, encouraging topic diversity.

frequency_penaltynumber nullable

Penalty applied based on how frequently a token appears in the text, reducing repetitive content.

max_tokensinteger required

Maximum number of tokens to generate in the response.

stop_sequencesstring[]

Custom stop sequences that stop generation when matched.

service_tier'auto' | 'standard_only'

Service tier preference (for example, "auto" or "standard_only").

inference_geostring nullable

Geographic region hint for inference processing.

correlation_idstring nullable

Correlation ID for tracking the request across systems.

maximum_loaded_skillsinteger nullable

Optional cap for concurrently loaded skills in a conversation. When exceeded, the oldest loaded skill is evicted.

{"stackTrail":"components:schemas:ChatBody:properties:context_management:anyOf","oasType":"schema","type":"unknown","title":"Context Management","description":"Optional context management configuration","nullable":true}

Example request

{
  "max_tokens": 1000,
  "messages": [
    {
      "content": "How do you fry an egg? Choose the best method.",
      "role": "user"
    }
  ],
  "response_format": {
    "type": "text"
  },
  "stream": false,
  "system": {
    "citations": {
      "enabled": true
    },
    "text": "You are a helpful cooking assistant. Provide clear, step-by-step instructions."
  },
  "temperature": 0.7,
  "thinking": {
    "enabled": false
  },
  "tool_choice": {
    "disable_parallel_tool_use": false,
    "type": "auto"
  },
  "tools": [
    {
      "description": "A tool to fry eggs with precise temperature control",
      "input_schema": {
        "properties": {
          "temperature": {
            "description": "Temperature in degrees Celsius",
            "type": "number"
          },
          "time": {
            "description": "Time in minutes to fry the egg",
            "type": "number"
          }
        },
        "required": [
          "temperature",
          "time"
        ],
        "type": "object"
      },
      "name": "egg_fryer"
    }
  ]
}

Response

Chat stream initiated successfully

message_idstring required

Unique identifier for the initiated stream

status'pending' | 'processing' | 'completed' | 'failed' | 'cancelled' | 'error' required

Enumeration of possible stream statuses.

messagestring

Confirmation message for successful stream initiation

Example response

{
  "message": "Request initiated successfully",
  "message_id": "msg_async_12345",
  "status": "pending"
}

Changes

Changed in 4 of the 11 revisions of this API.447

  • 4e828cf153c41See the full diff
    • ○

      added the new optional request property mounts

      new-optional-request-property

  • 594fa71dfb90436See the full diff
    • ▲

      removed Base64PDFSource URLPDFSource from the messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source request property oneOf list

      request-property-one-of-removed

    • ▲

      removed Base64PDFSource URLPDFSource from the messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #16: TLDRBlock -> subschema #17: TLDRBlock]/content/items/anyOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source request property oneOf list

      request-property-one-of-removed

    • ▲

      removed Base64PDFSource URLPDFSource from the messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #17: ToolResultBlock -> subschema #18: ToolResultBlock]/content/anyOf[subschema #2]/items/oneOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source request property oneOf list

      request-property-one-of-removed

    • ▲

      removed Base64PDFSource URLPDFSource from the messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #17: ToolResultBlock -> subschema #18: ToolResultBlock]/content/anyOf[subschema #2]/items/oneOf[subschema #16: TLDRBlock -> subschema #17: TLDRBlock]/content/items/anyOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source request property oneOf list

      request-property-one-of-removed

    • ○

      added the new optional request property system/items/prompt/code_execution

      new-optional-request-property

    • ○

      added the new optional request property system/items/prompt/skills

      new-optional-request-property

    • ○

      added LocalResourceBlock to the messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #16: TLDRBlock -> subschema #17: TLDRBlock]/content/items/ request property anyOf list

      request-property-any-of-added

    • ○

      added LocalResourceBlock to the messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #17: ToolResultBlock -> subschema #18: ToolResultBlock]/content/anyOf[subschema #2]/items/oneOf[subschema #16: TLDRBlock -> subschema #17: TLDRBlock]/content/items/ request property anyOf list

      request-property-any-of-added

    • ○

      the request property messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source/oneOf[subschema #2: PlainTextSource]/type became optional

      request-property-became-optional

    • ○

      the request property messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source/oneOf[subschema #3: ContentSource]/type became optional

      request-property-became-optional

    • ○

      the request property messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #16: TLDRBlock -> subschema #17: TLDRBlock]/content/items/anyOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source/oneOf[subschema #2: PlainTextSource]/type became optional

      request-property-became-optional

    • ○

      the request property messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #16: TLDRBlock -> subschema #17: TLDRBlock]/content/items/anyOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source/oneOf[subschema #3: ContentSource]/type became optional

      request-property-became-optional

    • ○

      the request property messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #17: ToolResultBlock -> subschema #18: ToolResultBlock]/content/anyOf[subschema #2]/items/oneOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source/oneOf[subschema #2: PlainTextSource]/type became optional

      request-property-became-optional

    • ○

      the request property messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #17: ToolResultBlock -> subschema #18: ToolResultBlock]/content/anyOf[subschema #2]/items/oneOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source/oneOf[subschema #3: ContentSource]/type became optional

      request-property-became-optional

    • ○

      the request property messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #17: ToolResultBlock -> subschema #18: ToolResultBlock]/content/anyOf[subschema #2]/items/oneOf[subschema #16: TLDRBlock -> subschema #17: TLDRBlock]/content/items/anyOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source/oneOf[subschema #2: PlainTextSource]/type became optional

      request-property-became-optional

    • ○

      the request property messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #17: ToolResultBlock -> subschema #18: ToolResultBlock]/content/anyOf[subschema #2]/items/oneOf[subschema #16: TLDRBlock -> subschema #17: TLDRBlock]/content/items/anyOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source/oneOf[subschema #3: ContentSource]/type became optional

      request-property-became-optional

    • ○

      the type request property default value content was added

      request-property-default-value-added

    • ○

      the type request property default value content was added

      request-property-default-value-added

    • ○

      the type request property default value content was added

      request-property-default-value-added

    • ○

      the type request property default value content was added

      request-property-default-value-added

    • ○

      the type request property default value text was added

      request-property-default-value-added

    • ○

      the type request property default value text was added

      request-property-default-value-added

    • ○

      the type request property default value text was added

      request-property-default-value-added

    • ○

      the type request property default value text was added

      request-property-default-value-added

    • ○

      added local_resource discriminator mapping keys to the messages/items/content/anyOf[subschema #2]/items/ request property

      request-property-discriminator-mapping-added

    • ○

      added local_resource discriminator mapping keys to the messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #17: ToolResultBlock -> subschema #18: ToolResultBlock]/content/anyOf[subschema #2]/items/ request property

      request-property-discriminator-mapping-added

    • ○

      mapped value for discriminator key base64 changed from Base64PDFSource to Base64Source for messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source request property

      request-property-discriminator-mapping-changed

    • ○

      mapped value for discriminator key base64 changed from Base64PDFSource to Base64Source for messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #16: TLDRBlock -> subschema #17: TLDRBlock]/content/items/anyOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source request property

      request-property-discriminator-mapping-changed

    • ○

      mapped value for discriminator key base64 changed from Base64PDFSource to Base64Source for messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #17: ToolResultBlock -> subschema #18: ToolResultBlock]/content/anyOf[subschema #2]/items/oneOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source request property

      request-property-discriminator-mapping-changed

    • ○

      mapped value for discriminator key base64 changed from Base64PDFSource to Base64Source for messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #17: ToolResultBlock -> subschema #18: ToolResultBlock]/content/anyOf[subschema #2]/items/oneOf[subschema #16: TLDRBlock -> subschema #17: TLDRBlock]/content/items/anyOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source request property

      request-property-discriminator-mapping-changed

    • ○

      mapped value for discriminator key url changed from URLPDFSource to URLDocumentSource for messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source request property

      request-property-discriminator-mapping-changed

    • ○

      mapped value for discriminator key url changed from URLPDFSource to URLDocumentSource for messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #16: TLDRBlock -> subschema #17: TLDRBlock]/content/items/anyOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source request property

      request-property-discriminator-mapping-changed

    • ○

      mapped value for discriminator key url changed from URLPDFSource to URLDocumentSource for messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #17: ToolResultBlock -> subschema #18: ToolResultBlock]/content/anyOf[subschema #2]/items/oneOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source request property

      request-property-discriminator-mapping-changed

    • ○

      mapped value for discriminator key url changed from URLPDFSource to URLDocumentSource for messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #17: ToolResultBlock -> subschema #18: ToolResultBlock]/content/anyOf[subschema #2]/items/oneOf[subschema #16: TLDRBlock -> subschema #17: TLDRBlock]/content/items/anyOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source request property

      request-property-discriminator-mapping-changed

    • ○

      added Base64Source URLDocumentSource to the messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source request property oneOf list

      request-property-one-of-added

    • ○

      added Base64Source URLDocumentSource to the messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #16: TLDRBlock -> subschema #17: TLDRBlock]/content/items/anyOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source request property oneOf list

      request-property-one-of-added

    • ○

      added Base64Source URLDocumentSource to the messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #17: ToolResultBlock -> subschema #18: ToolResultBlock]/content/anyOf[subschema #2]/items/oneOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source request property oneOf list

      request-property-one-of-added

    • ○

      added Base64Source URLDocumentSource to the messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #17: ToolResultBlock -> subschema #18: ToolResultBlock]/content/anyOf[subschema #2]/items/oneOf[subschema #16: TLDRBlock -> subschema #17: TLDRBlock]/content/items/anyOf[subschema #13: DocumentBlock -> subschema #14: DocumentBlock]/source request property oneOf list

      request-property-one-of-added

    • ○

      added LocalResourceBlock to the messages/items/content/anyOf[subschema #2]/items/ request property oneOf list

      request-property-one-of-added

    • ○

      added LocalResourceBlock to the messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #17: ToolResultBlock -> subschema #18: ToolResultBlock]/content/anyOf[subschema #2]/items/ request property oneOf list

      request-property-one-of-added

    This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 7914e6f947be9See the full diff
    • ○

      added MidConvSystemBlock to the messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #15: TLDRBlock -> subschema #16: TLDRBlock]/content/items/ request property anyOf list

      request-property-any-of-added

    • ○

      added MidConvSystemBlock to the messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #16: ToolResultBlock -> subschema #17: ToolResultBlock]/content/anyOf[subschema #2]/items/oneOf[subschema #15: TLDRBlock -> subschema #16: TLDRBlock]/content/items/ request property anyOf list

      request-property-any-of-added

    • ○

      added mid_conv_system discriminator mapping keys to the messages/items/content/anyOf[subschema #2]/items/ request property

      request-property-discriminator-mapping-added

    • ○

      added mid_conv_system discriminator mapping keys to the messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #16: ToolResultBlock -> subschema #17: ToolResultBlock]/content/anyOf[subschema #2]/items/ request property

      request-property-discriminator-mapping-added

    • ○

      added the new system enum value to the request property messages/items/role

      request-property-enum-value-added

    • ○

      added the new xhigh enum value to the request property output_config/effort/anyOf[subschema #1]/

      request-property-enum-value-added

    • ○

      added the new xhigh enum value to the request property thinking/effort/anyOf[subschema #1]/

      request-property-enum-value-added

    • ○

      added MidConvSystemBlock to the messages/items/content/anyOf[subschema #2]/items/ request property oneOf list

      request-property-one-of-added

    • ○

      added MidConvSystemBlock to the messages/items/content/anyOf[subschema #2]/items/oneOf[subschema #16: ToolResultBlock -> subschema #17: ToolResultBlock]/content/anyOf[subschema #2]/items/ request property oneOf list

      request-property-one-of-added

  • c711b911f68e1See the full diff
    • ○

      endpoint added

      endpoint-added

    This revision also has 13 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog