Skip to main content
POST
/
v1
/
messages

​
Authorization

  • Auth Type: Bearer Auth (In: header)
  • Format: Authorization: Bearer <YOUR_API_KEY>
  • Description: Use Bearer <YOUR_API_KEY>. Format: Authorization: Bearer sk-xxxxxx.
  • API Key: where API Key is your AGCloud API KEY

​
Response Examples

​
Async Chat Response Field Description

FieldTypeRangeDescription
idstring-The current chat task id.
objectstring-The type of object returned by the API. In this case it is always task.
statusstringpending
processing
success
failed		Current status of the task.
created_atnumber-Unix timestamp (in seconds) indicating when the task was created.

​
Streaming Events

EventDescription
message_startIndicates the start of a new message
content_block_startIndicates the start of a content block
content_block_deltaContains incremental text content
content_block_stopIndicates the end of a content block
message_deltaContains final message metadata (stop_reason, usage)
message_stopIndicates the end of the message

​
Parameters

FieldTypeRequiredDefaultDescription
modelstring✅-The model ID to use for this request.
messagesarray<object>✅-An array of message objects representing the conversation history. See Messages
max_tokensinteger✅4096The maximum number of tokens the model can generate in the response. Range 1-32000
asyncboolean-falseWhether to return an asynchronous response. Only supported for non-streaming requests.
streamboolean-falseIf true, returns a stream of server-sent events (SSE) as the response is generated.
systemstring | array<object>--System prompt that sets the behavior and context for the assistant. See System
temperaturenumber-1.0Controls the randomness of the output. Lower values produce more focused responses, higher values produce more creative outputs. Range 0.0-1.0
top_pnumber-1.0Nucleus sampling parameter. The model considers tokens with top_p cumulative probability mass. Range 0.0-1.0
top_kinteger--Limits token selection to the K most probable tokens at each step.
stop_sequencesarray<string>--An array of strings that will stop generation when encountered.
toolsarray<object>--A list of tools the model may call to generate the response. See Tools
tool_choiceobject-autoControls how the model selects which tool(s) to use. Can be auto any tool. See Tool Choices
thinkingobject--Configuration for extended thinking (chain-of-thought) mode. See Thinking
metadataobject--Optional metadata to associate with the request. See Metadata
If both stream and async are true, stream takes precedence.

​
Messages Array Structure

FieldTypeRequiredDefaultDescription
rolestring✅-The role of the message. Can be: user or assistant
contentstring | array✅-The content of the message. Can be a simple string for text-only messages, or an array of content blocks for multimodal content
>content.typestring✅ if content is array-Must be text
>content.textstring✅ if content is array-The text content

​
System Array Structure

FieldTypeRequiredDefaultDescription
typestring✅-The system tips, default text
textstring✅-Describe the role the model plays.

​
Tools Array Structure

FieldTypeRequiredDefaultDescription
typestring✅-The type of tool. Must be web_search_20250305 for web search
namestring✅-The name of the tool. Use web_search
max_usesinteger--Maximum number of times the web search tool can be used in a single request, range in 1-10
allowed_domainsarray--Only include search results from these domains. Cannot be used with blocked_domains
blocked_domainsarray--Never include search results from these domains. Cannot be used with allowed_domains
user_locationobject--Localize search results based on user’s location. See User Location
Max Uses Structure The max_uses parameter limits the number of searches performed. If Claude attempts more searches than allowed, the web_search_tool_result will be an error with the max_uses_exceeded error code. Domain Filtering When using domain filters:
  • Domains should not include the HTTP/HTTPS scheme (use example.com instead of https://example.com)
  • Subdomains are automatically included (example.com covers docs.example.com)
  • Specific subdomains restrict results to only that subdomain (docs.example.com returns only results from that subdomain, not from example.com or api.example.com)
  • Subpaths are supported (example.com/blog)
  • You can use either allowed_domains or blocked_domains, but not both in the same request
  • Request-level domain restrictions must be compatible with organization-level domain restrictions configured in the Console

​
User Location Structure

The user_location object allows you to localize search results based on user’s location:
FieldTypeRequiredDescription
typestring✅The type of location. Must be approximate
citystring-The city name (e.g., San Francisco)
regionstring-The region or state (e.g., California)
countrystring-The country code in ISO 3166-1 alpha-2 format (e.g., US)
timezonestring-The IANA timezone ID (e.g., America/Los_Angeles)

​
Tool Choices Structure

FieldTypeRequiredDescription
typestring✅Tool selection mode. auto: model decides whether to use a tool, any: model must use one of the available tools, tool: model must use the specific tool specified by name.
namestring-The name of the specific tool to use. Required only when type is tool.

​
Thinking Structure

FieldTypeRequiredDescription
typestring✅Thinking mode. enabled: model uses extended thinking for internal reasoning before generating the response, disabled: standard response mode.
budget_tokensinteger-Maximum tokens allocated for thinking. Required when type is enabled. The model uses these tokens for internal reasoning before producing the final output.

​
Metadata Structure

FieldTypeRequiredDescription
user_idstring-An external identifier for the user making the request. Useful for analytics, abuse detection, and logging.