---
title: Developer API
slug: /developer-api
description: Create chat sessions with your Chatley agents and send them messages from your own application.
---

The Chatley Developer API lets your own application hold a conversation with one
of your agents. You create a session, send messages to it, and read the agent's
replies back as JSON.

It is the inbound half of Chatley's integration surface: your application calls
Chatley. For the outbound half — Chatley calling you when a lead arrives — see
[Webhooks](../webhooks.md).

## Base URL

```text
https://api.chatley.ai
```

Every request and response body is JSON.

## What you can do today

| Endpoint | Purpose |
| --- | --- |
| [`POST /api/developer/chat/sessions`](./chat-sessions.md) | Start a conversation with an agent |
| [`POST /api/developer/chat/messages`](./chat-messages.md) | Send a message and get the agent's reply |

A session holds the conversation context. Create one, keep its `sessionId`, and
send every message in that conversation with the same ID so the agent remembers
what was said earlier.

## Before you start

You need two things:

1. **An API key.** Create one in **Integrations & API Keys → API Keys**. See
   [Authentication](./authentication.md).
2. **An agent ID.** Open the agent in Chatley and copy the ID from the agent
   page URL.

## A complete example

Create a session:

```bash
curl --request POST "https://api.chatley.ai/api/developer/chat/sessions" \
  --header "Authorization: Bearer $CHATLEY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{"agentId":"YOUR_AGENT_ID"}'
```

```json
{
  "success": true,
  "data": {
    "sessionId": "session-id",
    "agentId": "YOUR_AGENT_ID"
  }
}
```

Then send a message into it:

```bash
curl --request POST "https://api.chatley.ai/api/developer/chat/messages" \
  --header "Authorization: Bearer $CHATLEY_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "agentId": "YOUR_AGENT_ID",
    "sessionId": "YOUR_SESSION_ID",
    "message": "What appointment times are available?"
  }'
```

```json
{
  "success": true,
  "data": {
    "chatId": "chat-id",
    "sessionId": "YOUR_SESSION_ID",
    "response": "We have Tuesday at 10am or Thursday at 2pm. Which suits you?"
  }
}
```

## Response shape

Every endpoint answers with the same envelope, so you can branch on one field:

```json
{ "success": true, "data": { } }
```

```json
{ "success": false, "error": "Agent not found" }
```

A failed request always carries a non-2xx status code as well as
`"success": false`. Authentication failures add a machine-readable `code` —
see [Authentication](./authentication.md#error-responses).

:::note
The agent must have chat enabled. If it does not, requests come back with
**400 — Agent does not have chat enabled**; open the agent in Chatley and turn
chat on before calling the API.
:::