---
title: "Create Chat"
method: POST
path: "/v1/chat"
tags: ["chat"]
---

# Create Chat

`POST /v1/chat`

## Request

- Base URL: `https://api.happenstance.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.happenstance.ai/v1/chat`
- Auth: HTTP bearer

Start a chat with Happenstance Chat, optionally with its first message.

Chat searches the user's network (their connections, their friends' and their groups'),
researches people and drafts outreach, over as many turns as the conversation needs. A
message returns at once with a turn id: poll GET /v1/chat/{chat_id}/turns/{turn_id} until
the turn's status is completed, then read the people and drafts.

Each turn is charged when it finishes. Returns 402 when the balance is below 3 credits.

## Request body

- CreateChatRequestV1
  - `message` string, nullable: The first message. Omit it to create an empty chat and send messages with POST /v1/chat/{chat_id}/messages.

## Response `200`

Successful Response

- CreateChatResponseV1: Response from POST /v1/chat.
  - `id` string, required: The chat's id
  - `url` string, required: The chat in the Happenstance app
  - `turn_id` string, nullable: The first message's turn, when a message was sent
  - `status` 'queued' | 'running' | 'completed' | 'failed' | 'cancelled', nullable: The turn's status, when a message was sent
  - `warning` string, nullable: Warning message when credit balance is low

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `402`: Payment Required
- `403`: Forbidden
- `404`: Not Found
- `410`: Gone
- `422`: Validation Error
- `500`: Internal Server Error
- `503`: Service Unavailable

## Changes

- **2026-10-23** `c8149ed29b44`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/happenstance/apis/happenstance-api/changes/v1/chat/post.md)

---

[API](https://skmtc.dev/happenstance/apis/happenstance-api.md) - [All operations](https://skmtc.dev/happenstance/apis/happenstance-api/llms.txt) - [OpenAPI document](https://skmtc.dev/happenstance/apis/happenstance-api/revisions/0b6ee3927db3?raw)