AgentReference

Reference

Every Agent API endpoint. All except the stream itself use the same Bearer-token auth as the rest of the Developer API (see Authentication and Rate limiting) — scope is the additional scope each one requires on top of that. The console on the right sends a real request against ai.synup.com — paste your own key to try one.

Always returns immediately with a job id — never blocks on the agent's reply.

Dispatch a message

post/v1/agent/messages

agent:invoke

Request body

idempotency_keystringrequired

A retried call with the same key returns the same task rather than dispatching twice.

messagestringrequired

The message to send.

conversation_idstringoptional

Optional — the conversationId from a previous poll response, to continue that same conversation instead of starting a new one. Never generate this value yourself; it only ever comes from an earlier task's response.

Errors

400idempotency_key or message missing.

409This account's Sydekick instance isn't ready yet.

429Rate limit or concurrency limit hit — see the Overview page.

post/v1/agent/messages

Ihr API-Schlüssel

Anfragetext*

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

A task belonging to a different token 404s — never confirms it exists.

Poll a message's status

get/v1/agent/messages/{id}

agent:invoke

Parameters

idstringrequired

The task id returned by dispatch.

Errors

404Not found, or belongs to a different token.

get/v1/agent/messages/{id}

Ihr API-Schlüssel

id *

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

The stream

Not Bearer-token auth like the endpoints above — its own short-lived token instead. No Try It console for these two: an SSE connection and a token-refresh call don't fit this console's request/response shape. See Streaming for the full walkthrough.

get/v1/agent/stream(stream token, not the API key)

SSE stream for one task. Authenticated via the token embedded in stream_url, not a Bearer header. Accepts ?starting_after=<seq> to resume — see the Streaming page.

Response

text/event-stream — see the Streaming page.

post/v1/agent/stream/token(refresh token, not the API key)

Reissue an expired stream token from its refresh secret.

Request

{ "task_id": "task_...", "refresh_token": "..." }

Response

{ "data": { "stream_url": "..." } }