# Call your agent from your own app

> Create an API deployment and stream replies into your own app or server.

An API deployment has no chat window. Your own app or server sends each message and streams the agent's reply back, so you can build your own chat or connect the agent to another system.

## Create an API deployment

1. Open **Deployments** and select **Create Deployment**.
2. Under **Channel**, pick **API**.
3. Under **Basics**, enter a **Name** and choose the **AI Agent**.
4. Keep **Live** on and select **Create Deployment**.

An API deployment has a **Settings** tab and an **Install** tab. It has no **Chat widget** tab and no hosted page.

## Send a message

Open the **Install** tab, or choose **API integration guide** from the deployment's row menu. The **Parameters** card has the **Deployment ID** and **Public key**. Send each message as a `POST` to `https://help.ai/api/agent/pai/stream-message`:

```bash
curl -N https://help.ai/api/agent/pai/stream-message \
  -H "x-public-key: agent_pk_..." \
  -H "x-ai-agent-deployment-id: <deployment id>" \
  -H "content-type: application/json" \
  -d '{
    "visitorId": "01900000-0000-7000-8000-000000000001",
    "conversationId": "01900000-0000-7000-8000-000000000002",
    "responseType": "stream",
    "messages": [{ "role": "user", "parts": [{ "type": "text", "text": "hi" }] }]
  }'
```

| Field | What to send |
| --- | --- |
| `x-public-key` header | The deployment's **Public key** |
| `x-ai-agent-deployment-id` header | The **Deployment ID** |
| `visitorId` | Your id for the person, as a UUID version 7. Keep it the same for the same person |
| `conversationId` | A UUID version 7. Keep it to continue a conversation, and use a new one to start another |
| `responseType` | `"stream"` returns the reply in the same response |
| `messages` | The new message. help.ai keeps the conversation's earlier messages, so you don't send them again |

The reply streams back as server-sent events and ends with `[DONE]`. If the `conversationId` you sent is already in use, the response's `X-Conversation-Id` header gives the one to use from then on.

<Tip>
The **Install** tab's **curl**, **Node fetch** and **Python (httpx)** samples have your values filled in and stream the reply. The Node sample makes its ids with the `uuid` package, and the Python one needs Python 3.14 or later for `uuid.uuid7()`.
</Tip>

## Limits and errors

An API deployment's **Settings** tab has the same **Allowed websites**, **Conversation history**, **Traffic limits** and **Message and file size** sections as a widget.

| Response | Why |
| --- | --- |
| `404` | The deployment isn't **Live**, its AI agent is disabled, or the key and ID don't match |
| `429` | A traffic limit was reached. Try again when the minute or hour is up |
| `400` | The message is longer than **Maximum message length**, or a field is missing or not valid |

**Allowed websites** only checks calls from browsers, so it doesn't affect calls from your server.

## Keys

The public key and deployment ID are safe to use anywhere, even in a browser. Keep the **Secret key** on your server only. See [Secure a deployment: websites, limits and history](https://support.help.ai/deployments-and-the-widget/secure-your-deployment).

To work with your workspace from a script, such as reading form submissions, use a workspace API key instead. See [Create and manage API keys](https://support.help.ai/workspace-and-billing/create-and-manage-api-keys).