Start a stateful conversation

POSThttps://server.heyrik.com/api/v1/chat/sessions

Headers

AuthorizationstringRequired

Use Bearer $HEYRIK_API_KEY with an account-scoped API key. Keep the key on your server.

Get your API key

Parameters 3

Fields documented for this operation. See the request example for placement and structure.

agent_idstringRequired

The agent to talk to. `agency_id` also accepted.

titlestring

A label for the conversation.

testboolean

true runs the session for FREE (not charged, balance_credits comes back null) — for trying an agent out.

Response

Explore the example values. This is not a complete response schema.

dataobject

Explore 6 properties

idstring

Example "cht_c09b79cc"

agency_idstring

Example "agc_9f2a1c30"

channelstring

Example "api"

message_countnumber

Example 0

credits_usednumber

Example 0

created_atstring

Example "2026-07-31T10:17:49.946Z"

Error reference

POST/chat/sessions

cURL

curl -X POST https://server.heyrik.com/api/v1/chat/sessions \
  -H "Authorization: Bearer $HEYRIK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "agent_id": "agc_9f2a1c30", "title": "Support chat" }'

Response example

JSON

{
  "data": {
    "id": "cht_c09b79cc",
    "agency_id": "agc_9f2a1c30",
    "channel": "api",
    "message_count": 0,
    "credits_used": 0,
    "created_at": "2026-07-31T10:17:49.946Z"
  }
}

Illustrative examples · No live request is sent