# Create a chat

Creates a new chat and starts the first agent turn on your message. The request returns as soon as the message is saved. Poll the [chat status](https://betterstack.com/docs/ai-sre/api/chats/status/) until it leaves `processing`, then [get the chat](https://betterstack.com/docs/ai-sre/api/chats/get/) to read the answer.

[endpoint]
base_url = "https://chat.betterstack.com"
path = "/api/v2/chats"
method = "POST"

[[body_param]]
name = "team_name"
description = "Required if using [global API token](https://betterstack.com/docs/ai-sre/api/getting-api-token/#get-a-global-api-token) to specify the team which should own the chat."
required = false
type = "string"

[[body_param]]
name = "message"
description = "Your first message to the agent."
required = true
type = "string"

[[body_param]]
name = "name"
description = "Chat name. If omitted, the chat is named automatically after the first turn."
required = false
type = "string"

[[header]]
name = "Authorization"
description = "Bearer `$TOKEN`"
required = true
type = "string"

[[header]]
name = "Content-Type"
description = "application/json"
required = true
type = "string"
[/endpoint]

[responses]
[[response]]
status = 201
description = '''Returns the newly created chat, still processing. Its transcript holds your message and a placeholder for the agent's answer.'''
body = '''{
  "data": {
    "id": "12345",
    "type": "chat",
    "attributes": {
      "team_id": 123456,
      "team_name": "example-team",
      "name": "Checkout 5xx spike",
      "status": "processing",
      "message_count": 2,
      "last_message_at": "2026-09-07T10:30:00.000Z",
      "total_tokens": 0,
      "created_at": "2026-09-07T10:30:00.000Z",
      "updated_at": "2026-09-07T10:30:00.000Z",
      "messages": [
        {
          "id": 9001,
          "message_type": "user",
          "text": "Why did checkout start returning 5xx at 10:15?",
          "artifacts": [],
          "created_at": "2026-09-07T10:30:00.000Z",
          "user": null
        },
        {
          "id": 9002,
          "message_type": "ai",
          "text": null,
          "artifacts": [],
          "created_at": "2026-09-07T10:30:00.000Z",
          "user": null
        }
      ],
      "pending_confirmations": []
    }
  }
}'''

[[response]]
status = 401
description = '''Unauthorized'''
body = '''{
  "errors": "Invalid authentication"
}'''

[[response]]
status = 403
description = '''Forbidden - AI SRE Not Included In Your Plan'''
body = '''{
  "errors": "AI SRE is not available on this plan."
}'''

[[response]]
status = 422
description = '''Unprocessable Entity - Missing Required Attributes'''
body = '''{
  "errors": "Sorry, you are missing some required attributes",
  "required_attributes": ["message"]
}'''

[[response]]
status = 422
description = '''Unprocessable Entity - Validation Errors'''
body = '''{
  "errors": "Sorry, some values are incorrect",
  "invalid_values": {
    "message": "can't be blank"
  }
}'''
[/responses]

#### Example cURL

```shell
[label Example]
curl --request POST \
  --url https://chat.betterstack.com/api/v2/chats \
  --header "Authorization: Bearer $TOKEN" \
  --header 'Content-Type: application/json' \
  --data '{
    "message": "Why did checkout start returning 5xx at 10:15?",
    "name": "Checkout 5xx spike"
  }'
```