Skip to main content
POST
/
api
/
agent
/
chat
Start an agent chat run
curl --request POST \
  --url https://app.puffle.ai/api/agent/chat \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "<string>",
  "history": [
    {
      "role": "user",
      "content": "<string>"
    }
  ],
  "conversationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'
{ "runId": "run_1234567890abcdef", "status": "queued", "conversationId": "aaaa1111-1111-1111-1111-111111111111" }

​
Overview

The asynchronous entry point for the Puffle agent. Queues a chat turn as a Trigger.dev background task and returns immediately with a runId the caller polls via pollAgentChat until the agent finishes. For real-time streaming UIs, use streamAgentChat instead; for inline blocking calls where you don’t need tokens as they arrive, use syncAgentChat.

​
AI agent notes

Admin-only. This endpoint rejects non-admin callers with 403. The agent framework is not yet generally available.Rate-limited. Per-user rate limit returns 429 with a retryAfter (seconds) field and the standard Retry-After header. Respect it.Conversation handling. Pass conversationId on follow-up turns to persist history in the same thread. If omitted, the server creates a new conversation labeled with the first 100 chars of message. Conversations not owned by the caller return 404.Typical flow:
  1. POST /api/agent/chat with { message } → get runId
  2. GET /api/agent/chat/{runId} every 1–2 s until status reaches completed, failed, or cancelled
  3. On completed, read text, messages, toolCalls from the poll response
Alternatives:

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
message
string
required

The user's prompt for this turn. Required, non-empty.

Minimum string length: 1
​
history
object[]

Prior conversation turns. Omit to start a fresh conversation. Ignored when conversationId resolves to an existing conversation — the server loads history from the DB.

​
conversationId
string<uuid>

Existing conversation UUID (returned from a previous startAgentChat or syncAgentChat call). If omitted, a new conversation is created from the first 100 chars of message. Must be owned by the caller or the endpoint returns 404.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$

Response

Run queued.

​
runId
string
required

Trigger.dev run id (starts with run_). Pass to pollAgentChat to watch status.

​
status
enum<string>
required

Always queued — the run is dispatched but not started yet.

Available options:
queued
​
conversationId
string<uuid>

The conversation the run is writing into. Present unless conversation creation failed mid-call (non-fatal — the run still proceeds without history).

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$