Call your agent from your own app
Create an API deployment and stream replies into your own app or server.
Last updated
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#
- Open Deployments and select Create Deployment.
- Under Channel, pick API.
- Under Basics, enter a Name and choose the AI Agent.
- 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:
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" }] }]
}'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.
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().
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.
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.
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.