Skip to main content
POST
/
api
/
agent
/
chat
/
sync
Run an agent chat synchronously
curl --request POST \
  --url https://app.puffle.ai/api/agent/chat/sync \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "message": "<string>",
  "history": [
    {
      "role": "user",
      "content": "<string>"
    }
  ],
  "conversationId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
}
'
{ "text": "Here are 10 prospects matching your ICP.", "messages": [], "toolCalls": [ { "toolName": "search_leads", "args": { "query": "founders in fintech" } } ], "conversationId": "aaaa1111-1111-1111-1111-111111111111" }

​
Overview

The blocking variant of startAgentChat. Runs the agent loop in-process and returns the completed result in one response — text, messages, toolCalls, and the conversation id. Simpler than the queue-and-poll pattern but bounded by the request timeout. For long tool chains or anything that might exceed ~30–60 s, prefer startAgentChat + pollAgentChat.

​
AI agent notes

Admin-only. Rate-limited. Same 429 / retryAfter semantics as the async variant.Timeout risk. The request holds open for the full agent loop. If the agent calls many tools or the model is slow, you may hit serverless function timeouts (~5 min on Vercel) before the chain finishes. The async variant (startAgentChat + poll) is immune to this.Conversation persistence. The interaction is saved to the conversation (conversationId returned) after the run completes. If conversation persistence fails, it’s logged as a non-fatal warning — the response still carries the agent result.Related: Start an agent chat run (async), Stream an agent chat run (SSE).

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.

Minimum string length: 1
​
history
object[]
​
conversationId
string<uuid>
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

Agent finished. Full result returned.

​
text
string
required

Final assistant message text.

​
messages
object[]
required

Full message log produced during the run.

​
toolCalls
object[]
required

Tool invocations and their results.

​
conversationId
string<uuid>
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)$
​
{key}
any