AgentQuickstart

Quickstart

Two calls: send a message, get the reply back. Use any API key with the agent:invoke scope — mint one under Settings → Developer → API Keys (see Authentication if you don't have one yet). There's no separate sub-key step: one key per integration is enough, and a reseller wanting per-end-customer separation just mints one ordinary key per customer the same way.

1. Send a message

idempotency_key is required — a retried call with the same key returns the same task rather than dispatching twice.

curl -X POST https://ai.synup.com/api/v1/agent/messages \
  -H "Authorization: Bearer sy_..." \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "req-2026-08-31-001",
    "message": "What'"'"'s our average review rating this month?"
  }'

{
  "data": {
    "id": "task_9f2c...",
    "status": "queued",
    "stream_url": "https://ai.synup.com/api/v1/agent/stream?token=...",
    "stream_refresh_token": "..."
  }
}

2. Get the reply

Simplest option — poll until status is terminal:

curl https://ai.synup.com/api/v1/agent/messages/task_9f2c... \
  -H "Authorization: Bearer sy_..."

{
  "data": {
    "id": "task_9f2c...",
    "status": "completed",
    "resultText": "Your average rating this month is 4.6, up from 4.4 last month.",
    "errorReason": null,
    "conversationId": "3f7900ae-34b2-47b0-8254-27864bf3b5c8"
  }
}

Want the reply live instead of polling, or pushed to you with no polling at all? See Streaming or register a webhook for agent.message.completed in Settings → Developer → Webhooks.

Continuing a conversation

A completed task's conversationId (shown above) is the thread to reuse for a follow-up — pass it back as conversation_id on your next dispatch to keep the same context instead of starting a new conversation. Don't generate this value yourself; it only ever comes from a prior task's response.

curl -X POST https://ai.synup.com/api/v1/agent/messages \
  -H "Authorization: Bearer sy_..." \
  -H "Content-Type: application/json" \
  -d '{
    "idempotency_key": "req-2026-08-31-002",
    "message": "And how does that compare to last quarter?",
    "conversation_id": "3f7900ae-34b2-47b0-8254-27864bf3b5c8"
  }'