---
title: Create a message (Anthropic Messages API)
url: https://developers.wpengine.com/docs/ai/api/reference/operations/createmessage/
image: https://developers.wpengine.com/og/docs/ai/api/reference/operations/createmessage.png
---

# Create a message (Anthropic Messages API)

POST

/v1/messages

Select code sample

```php
<?php


$client = new \GuzzleHttp\Client();


$response = $client->request('POST', 'https://api.ai.wpengine.com/v1/messages', [
  'body' => '{ "model": "anthropic/claude-sonnet-4-6", "messages": [ { "role": "user", "content": "example" } ], "max_tokens": 1024, "system": "example", "tools": [ {} ], "stream": false, "thinking": { "type": "enabled", "budget_tokens": 1 } }',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);


echo $response->getBody();
```

- Current environment

Anthropic-native Messages endpoint, compatible with official Anthropic SDKs. Accepts the standard Anthropic Messages request shape, including system prompts, multi-turn conversations, image content blocks, tool use, extended thinking, custom stop sequences, and streaming. Prompt caching is supported: add “cache_control” breakpoints to your request (on system, tools, or message content) to cache stable prefixes; cached-token counts are reported as “cache_creation_input_tokens” and “cache_read_input_tokens” in the response usage, and “cache_creation” splits the cache writes by “cache_control” ttl. A 1-hour cache write is charged at a higher rate than a 5-minute one. Authenticate with a WP Engine bearer token, or with the Anthropic SDK convention of an “x-api-key” header carrying a WP Engine API key. API keys must carry the “chat:write” permission. The model field accepts prefixed (“anthropic/claude-sonnet-4-6”) or bare (“claude-sonnet-4-6”) names; only Anthropic models are supported. The “anthropic-version” and “anthropic-beta” headers are accepted and forwarded. All errors are returned in Anthropic’s error envelope format.

## Authorizations

- **[bearerAuth](https://developers.wpengine.com/docs/ai/api/reference/#bearerauth)**
- **[anthropicApiKey](https://developers.wpengine.com/docs/ai/api/reference/#anthropicapikey)**

## Request Bodyrequired

Media typeapplication/json

Standard Anthropic Messages API request. The full request shape is supported and forwarded to the model, including fields not listed here (tool_choice, stop_sequences, temperature, top_p, metadata, …). See Anthropic’s Messages API reference for the complete schema.

object

**model**

required

Anthropic model name, prefixed or bare (e.g. “anthropic/claude-sonnet-4-6” or “claude-sonnet-4-6”).

string

### Example

```
anthropic/claude-sonnet-4-6
```

**messages**

required

Conversation turns in Anthropic message format.

Array\<object>

object

**role**

required

string

Allowed values: user assistant

**content**

required

Message content: a plain string, or an array of content blocks (text, image, tool_use, tool_result, thinking, …).

**max_tokens**

required

Maximum number of tokens to generate.

integer

\>= 1

### Example

```json
1024
```

**system**

System prompt, as a string or array of content blocks.

**tools**

Tool definitions in Anthropic tool format, each with a name, description, and input_schema.

Array\<object>

object

**stream**

When true, the response is a Server-Sent Events stream using Anthropic’s streaming event protocol.

boolean

**thinking**

Extended thinking configuration.

object

**type**

string

Allowed values: enabled disabled

**budget_tokens**

Token budget for thinking when enabled.

integer

## Responses

### 200

Anthropic message response. When stream is false, returns a single JSON message object. When stream is true, returns Server-Sent Events using Anthropic’s streaming event protocol (message_start, content_block_delta, message_delta, message_stop, …).

Select media type

Standard Anthropic Messages API response.

object

**id**

string

**type**

string

Allowed values: message

**role**

string

Allowed values: assistant

**model**

string

**content**

Generated content blocks (text, tool_use, thinking, …).

Array\<object>

object

**type**

string

**stop_reason**

string

Allowed values: end_turn max_tokens stop_sequence tool_use model_context_window_exceeded

**stop_sequence**

The matched custom stop sequence, when applicable.

string

nullable

**usage**

object

**input_tokens**

integer

**output_tokens**

integer

**cache_creation_input_tokens**

integer

**cache_read_input_tokens**

integer

**cache_creation**

Breakdown of cache_creation_input_tokens by the cache_control ttl the prompt cache was written with. A 1-hour write is charged at a higher rate than a 5-minute one.

object

**ephemeral_5m_input_tokens**

Tokens written to the cache with a 5-minute ttl.

integer

**ephemeral_1h_input_tokens**

Tokens written to the cache with a 1-hour ttl.

integer

**output_tokens_details**

Breakdown of output_tokens. On streams it appears only on the final message_delta.

object

**thinking_tokens**

Thinking tokens, already counted in output_tokens.

integer

**server_tool_use**

Server-side tool calls the provider ran, each charged in credits on top of tokens. On streams the count is cumulative on message_delta.

object

**web_search_requests**

Web searches run for this message.

integer

#### Example

```json
{
  "id": "msg_01XFDUDYJgAACzvnptvVoYEL",
  "type": "message",
  "role": "assistant",
  "model": "claude-sonnet-4-6",
  "content": [
    {
      "type": "text"
    }
  ],
  "stop_reason": "end_turn"
}
```

### 400

Invalid request body or parameters, in Anthropic error envelope format (error type “invalid_request_error”).

Media typeapplication/json

Anthropic error envelope, as parsed by Anthropic SDKs.

object

**type**

required

string

Allowed values: error

**error**

required

object

**type**

required

Anthropic error type, e.g. “invalid_request_error”, “authentication_error”, “permission_error”, “not_found_error”, “request_too_large”, “rate_limit_error”, “overloaded_error”, “api_error”, or “content_policy_violation” (request content blocked by moderation policy when content moderation is enabled — never identifies which filter or category matched).

string

**message**

required

string

**request_id**

Correlation ID for this request, matching the X-Request-ID response header. Quote it in support reports.

string

#### Example

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens is required and must be greater than zero",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}
```

### 401

Missing or invalid credentials, in Anthropic error envelope format (error type “authentication_error”).

Media typeapplication/json

Anthropic error envelope, as parsed by Anthropic SDKs.

object

**type**

required

string

Allowed values: error

**error**

required

object

**type**

required

Anthropic error type, e.g. “invalid_request_error”, “authentication_error”, “permission_error”, “not_found_error”, “request_too_large”, “rate_limit_error”, “overloaded_error”, “api_error”, or “content_policy_violation” (request content blocked by moderation policy when content moderation is enabled — never identifies which filter or category matched).

string

**message**

required

string

**request_id**

Correlation ID for this request, matching the X-Request-ID response header. Quote it in support reports.

string

#### Example

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens is required and must be greater than zero",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}
```

#### Headers

**WWW-Authenticate**

string

##### Example

```
Bearer realm="ai-services"
```

### 402

The account’s credit balance is exhausted. Grant or top up credits before retrying. Body is in Anthropic error envelope format.

Media typeapplication/json

Anthropic error envelope, as parsed by Anthropic SDKs.

object

**type**

required

string

Allowed values: error

**error**

required

object

**type**

required

Anthropic error type, e.g. “invalid_request_error”, “authentication_error”, “permission_error”, “not_found_error”, “request_too_large”, “rate_limit_error”, “overloaded_error”, “api_error”, or “content_policy_violation” (request content blocked by moderation policy when content moderation is enabled — never identifies which filter or category matched).

string

**message**

required

string

**request_id**

Correlation ID for this request, matching the X-Request-ID response header. Quote it in support reports.

string

#### Example

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens is required and must be greater than zero",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}
```

### 403

Valid credentials but insufficient permission, in Anthropic error envelope format (error type “permission_error”). The same type is returned when billing isn’t set up for the account yet, because AI hasn’t been turned on for it in the User Portal or its setup hasn’t finished; the message says so. On /v1/messages, when content moderation is enabled, a 403 with error type “content_policy_violation” instead means the request content was blocked by content moderation policy; that response never identifies which filter or category matched.

Media typeapplication/json

Anthropic error envelope, as parsed by Anthropic SDKs.

object

**type**

required

string

Allowed values: error

**error**

required

object

**type**

required

Anthropic error type, e.g. “invalid_request_error”, “authentication_error”, “permission_error”, “not_found_error”, “request_too_large”, “rate_limit_error”, “overloaded_error”, “api_error”, or “content_policy_violation” (request content blocked by moderation policy when content moderation is enabled — never identifies which filter or category matched).

string

**message**

required

string

**request_id**

Correlation ID for this request, matching the X-Request-ID response header. Quote it in support reports.

string

#### Example

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens is required and must be greater than zero",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}
```

### 404

The requested model was not found or does not support this endpoint, in Anthropic error envelope format (error type “not_found_error”).

Media typeapplication/json

Anthropic error envelope, as parsed by Anthropic SDKs.

object

**type**

required

string

Allowed values: error

**error**

required

object

**type**

required

Anthropic error type, e.g. “invalid_request_error”, “authentication_error”, “permission_error”, “not_found_error”, “request_too_large”, “rate_limit_error”, “overloaded_error”, “api_error”, or “content_policy_violation” (request content blocked by moderation policy when content moderation is enabled — never identifies which filter or category matched).

string

**message**

required

string

**request_id**

Correlation ID for this request, matching the X-Request-ID response header. Quote it in support reports.

string

#### Example

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens is required and must be greater than zero",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}
```

### 413

Request body exceeds the size limit, in Anthropic error envelope format (error type “request_too_large”).

Media typeapplication/json

Anthropic error envelope, as parsed by Anthropic SDKs.

object

**type**

required

string

Allowed values: error

**error**

required

object

**type**

required

Anthropic error type, e.g. “invalid_request_error”, “authentication_error”, “permission_error”, “not_found_error”, “request_too_large”, “rate_limit_error”, “overloaded_error”, “api_error”, or “content_policy_violation” (request content blocked by moderation policy when content moderation is enabled — never identifies which filter or category matched).

string

**message**

required

string

**request_id**

Correlation ID for this request, matching the X-Request-ID response header. Quote it in support reports.

string

#### Example

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens is required and must be greater than zero",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}
```

### 429

Rate limit exceeded. The request was throttled at the edge; wait and retry later. The response body is a short HTML page generated by the load balancer, not a structured JSON error — clients should rely on the 429 status code rather than parsing the body.

Media typetext/html

string

### 502

Upstream provider returned an error, in Anthropic error envelope format (error type “api_error”).

Media typeapplication/json

Anthropic error envelope, as parsed by Anthropic SDKs.

object

**type**

required

string

Allowed values: error

**error**

required

object

**type**

required

Anthropic error type, e.g. “invalid_request_error”, “authentication_error”, “permission_error”, “not_found_error”, “request_too_large”, “rate_limit_error”, “overloaded_error”, “api_error”, or “content_policy_violation” (request content blocked by moderation policy when content moderation is enabled — never identifies which filter or category matched).

string

**message**

required

string

**request_id**

Correlation ID for this request, matching the X-Request-ID response header. Quote it in support reports.

string

#### Example

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens is required and must be greater than zero",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}
```

### 503

A required dependency (such as the authorization service) is temporarily unavailable, in Anthropic error envelope format (error type “overloaded_error”). Retry after a short delay with exponential back-off.

Media typeapplication/json

Anthropic error envelope, as parsed by Anthropic SDKs.

object

**type**

required

string

Allowed values: error

**error**

required

object

**type**

required

Anthropic error type, e.g. “invalid_request_error”, “authentication_error”, “permission_error”, “not_found_error”, “request_too_large”, “rate_limit_error”, “overloaded_error”, “api_error”, or “content_policy_violation” (request content blocked by moderation policy when content moderation is enabled — never identifies which filter or category matched).

string

**message**

required

string

**request_id**

Correlation ID for this request, matching the X-Request-ID response header. Quote it in support reports.

string

#### Example

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens is required and must be greater than zero",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}
```

### default

Upstream provider error relayed with its original status code and translated into Anthropic error envelope format. The error type reflects the status code (e.g. “rate_limit_error” for 429, “overloaded_error” for 529).

Media typeapplication/json

Anthropic error envelope, as parsed by Anthropic SDKs.

object

**type**

required

string

Allowed values: error

**error**

required

object

**type**

required

Anthropic error type, e.g. “invalid_request_error”, “authentication_error”, “permission_error”, “not_found_error”, “request_too_large”, “rate_limit_error”, “overloaded_error”, “api_error”, or “content_policy_violation” (request content blocked by moderation policy when content moderation is enabled — never identifies which filter or category matched).

string

**message**

required

string

**request_id**

Correlation ID for this request, matching the X-Request-ID response header. Quote it in support reports.

string

#### Example

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens is required and must be greater than zero",
    "request_id": "80f1e2c3a4b5c6d7e8f9a0b1c2d3e4f5"
  }
}
```

## Was this helpful?

Thanks for the feedback!

```json
{"@context":"https://schema.org","@graph":[{"@type":"WebSite","@id":"https://developers.wpengine.com/#website","name":"WP Engine Product Documentation","url":"https://developers.wpengine.com/","description":"Resources for developing, deploying, and scaling on WP Engine.","inLanguage":"en-US","keywords":["API documentation","product documentation","headless WordPress","managed WordPress hosting"],"publisher":{"@id":"https://wpengine.com/#organization"}}]}
```