Create Session

POST

chat

sessions

Create session

curl --request POST \
  --url https://api.agntix.ai/v1/chat/chat/sessions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "agentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "platform": "SDK",
  "metadata": {
    "userId": "usr_123",
    "locale": "en-US"
  }
}
'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agentId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    platform: 'SDK',
    metadata: {userId: 'usr_123', locale: 'en-US'}
  })
};

fetch('https://api.agntix.ai/v1/chat/chat/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.agntix.ai/v1/chat/chat/sessions"

payload = {
    "agentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "platform": "SDK",
    "metadata": {
        "userId": "usr_123",
        "locale": "en-US"
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "ses_01j3m8xkqp8v2nw4f7g9hk0r",
  "agentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "platform": "SDK",
  "state": "OPEN",
  "metadata": {
    "userId": "usr_123",
    "locale": "en-US"
  },
  "createdAt": "2026-04-29T09:00:00Z",
  "updatedAt": "2026-04-29T09:00:00Z"
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "fullName should not be empty",
    "status": 400
  },
  "meta": {
    "requestId": "req_01j3m...",
    "timestamp": "2026-04-29T10:00:00Z"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required.",
    "status": 401
  },
  "meta": {
    "requestId": "req_01j3m...",
    "timestamp": "2026-04-29T10:00:00Z"
  }
}

Every endpoint on this page requires either a Clerk-issued JWT (Authorization: Bearer <token>) or an organization API key (x-api-key: pk_…). Anonymous calls return 401 Unauthorized. See Authentication for the full setup.

Code examples

curl -X POST https://api.agntix.ai/v1/chat/chat/sessions \
  -H "x-api-key: pk_live_••••" \
  -H "Content-Type: application/json" \
  -d '{
    "agentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "platform": "SDK",
    "metadata": {
      "userId": "usr_123",
      "locale": "en-US"
    }
  }'

const session = await fetch('https://api.agntix.ai/v1/chat/chat/sessions', {
  method: 'POST',
  headers: {
    'x-api-key': 'pk_live_••••',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    agentId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    platform: 'SDK',
    metadata: { userId: 'usr_123', locale: 'en-US' },
  }),
}).then(r => r.json());

console.log('Session ID:', session.id);
// Send your first message using session.id

import httpx

session = httpx.post(
    "https://api.agntix.ai/v1/chat/chat/sessions",
    headers={"x-api-key": "pk_live_••••"},
    json={
        "agentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "platform": "SDK",
        "metadata": {"userId": "usr_123", "locale": "en-US"},
    },
).json()

session_id = session["id"]
print("Session ID:", session_id)

Sample response

{
  "id": "ses_01j3m8xkqp8v2nw4f7g9hk0r",
  "agentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "platform": "SDK",
  "state": "OPEN",
  "metadata": {
    "userId": "usr_123",
    "locale": "en-US"
  },
  "orgId": "org_2abc123",
  "createdAt": "2026-04-29T09:00:00Z",
  "updatedAt": "2026-04-29T09:00:00Z"
}

Store the session id — you’ll pass it as {sessionId} in every subsequent message call.

Authorizations

x-api-key

string

header

required

Organization API key. Obtain from the dashboard. Format: pk_live_…

Body

application/json

agentId

string<uuid>

required

The agent to chat with.

Example:

"a1b2c3d4-e5f6-7890-abcd-ef1234567890"

platform

enum<string>

default:SDK

required

Originating platform. Affects session tagging and analytics.

Available options:

SDK,

WEB,

WHATSAPP,

VOICE

metadata

object

Arbitrary key-value pairs attached to the session (max 4096 characters total). Useful for storing user IDs, locale, etc.

contact

object

Contact information to associate with this session.

Show child attributes

Response

Session created.

string

Example:

"ses_01j3m8xkqp8v2nw4f7g9hk0r"

agentId

string<uuid>

platform

string

Example:

"SDK"

state

enum<string>

Available options:

OPEN,

CLOSED

Example:

"OPEN"

metadata

object

orgId

string

createdAt

string<date-time>

updatedAt

string<date-time>

Create session

curl --request POST \
  --url https://api.agntix.ai/v1/chat/chat/sessions \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data '
{
  "agentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "platform": "SDK",
  "metadata": {
    "userId": "usr_123",
    "locale": "en-US"
  }
}
'

const options = {
  method: 'POST',
  headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agentId: 'a1b2c3d4-e5f6-7890-abcd-ef1234567890',
    platform: 'SDK',
    metadata: {userId: 'usr_123', locale: 'en-US'}
  })
};

fetch('https://api.agntix.ai/v1/chat/chat/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.agntix.ai/v1/chat/chat/sessions"

payload = {
    "agentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "platform": "SDK",
    "metadata": {
        "userId": "usr_123",
        "locale": "en-US"
    }
}
headers = {
    "x-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "id": "ses_01j3m8xkqp8v2nw4f7g9hk0r",
  "agentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "platform": "SDK",
  "state": "OPEN",
  "metadata": {
    "userId": "usr_123",
    "locale": "en-US"
  },
  "createdAt": "2026-04-29T09:00:00Z",
  "updatedAt": "2026-04-29T09:00:00Z"
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "fullName should not be empty",
    "status": 400
  },
  "meta": {
    "requestId": "req_01j3m...",
    "timestamp": "2026-04-29T10:00:00Z"
  }
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required.",
    "status": 401
  },
  "meta": {
    "requestId": "req_01j3m...",
    "timestamp": "2026-04-29T10:00:00Z"
  }
}

Overview

Agents

Chat

Voice

Tools

Phone Numbers

Create Session

Code examples

Sample response

Authorizations

Body

Response

​Code examples

​Sample response

Authorizations

Body

Response

Code examples

Sample response