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

​
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.

​
Parameters

FieldTypeRequiredDefaultDescription
modelstring✅claude-opus-4-6The model ID to use for this request.
messagesstring | array<object>✅-An array of message objects representing the conversation history.
max_tokensinteger✅1024The maximum number of tokens the model can generate in the response. Range 1-32000
toolsarray<object>✅-Array of tool objects. For web search, must include the web_search tool configuration with type web_search_20250305.
asyncboolean-falseWhether to return an asynchronous response. Only supported for non-streaming requests. See Tools.
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.
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.

​
Tools Object Structure

FieldTypeRequiredDescription
typestring✅The tool type. Must be web_search_20250305 for web search.
namestring✅Override the default tool name. Default: web_search.
max_usesinteger-Maximum number of web search requests allowed per model turn. Range 1-20.
allowed_domainsarray<string>-Only include search results from these domains. Cannot be used with blocked_domains.
blocked_domainsarray<string>-Never include search results from these domains. Cannot be used with allowed_domains.
user_locationobject-Approximate user location for localized search results.
>user_location.typestring-Must be approximate if provided.
>user_location.citystring-City name (e.g., "San Francisco").
>user_location.regionstring-Region or state (e.g., "California").
>user_location.countrystring-Two-letter country code (e.g., "US").
>user_location.timezonestring-IANA timezone (e.g., "America/New_York").
{
  "type": "web_search_20250305",
  "name": "web_search",
  "max_uses": 5,
  "allowed_domains": ["example.com", "trusteddomain.org"],
  "user_location": {
    "type": "approximate",
    "city": "San Francisco",
    "region": "California",
    "country": "US",
    "timezone": "America/Los_Angeles"
  }
}

​
Max Uses

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