Synup
Criar chave
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
Sua chave de API
Corpo da solicitação*
{
  "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}
Sua chave de API
id *
{
  "data": {
    "id": "task_9f2c...",
    "status": "completed",
    "resultText": "Your average rating this month is 4.6.",
    "errorReason": null,
    "conversationId": "3f7900ae-34b2-47b0-8254-27864bf3b5c8"
  }
}

Just the names of this account's connected third-party servers — no per-tool fetch. Use this to render "what's connected" without paying for a full capability list.

List connected servers

get/v1/capabilities/servers
capabilities:read
Errors
409This account's connected capabilities aren't ready yet.
get/v1/capabilities/servers
Sua chave de API
{
  "data": [
    {
      "name": "mycrm"
    },
    {
      "name": "pipedream-billing"
    }
  ],
  "count": 2
}

Optionally search with ?q= and/or narrow with ?server= — results are ranked, and a non-matching capability is left out rather than returned unranked. count is the total across every page, not this page's data.length. An account with nothing connected gets an empty data array — that's expected, not an error. Recomputed on every call (no fixed snapshot), so entries can shift between pages if a server connects/disconnects mid-walk.

List connected capabilities

get/v1/capabilities
capabilities:read
Parameters
qstringoptional
Search text. Omit to list every connected capability.
serverstringoptional
Comma-separated server name(s) to narrow to (e.g. mycrm,pipedream-billing). Case-insensitive. A name matching nothing connected just yields no results for it, never an error. Omit to include every connected server.
limitintegeroptional
Max results per page (default 25, capped at 100).
cursorstringoptional
Opaque pagination cursor from a previous response's next_cursor. Omit to start from the first page.
Errors
400cursor is malformed.
409This account's connected capabilities aren't ready yet.
get/v1/capabilities
Sua chave de API
q
server
limit
cursor
{
  "data": [
    {
      "name": "mycrm.lookup_contact",
      "description": "Look up a contact by email",
      "input_schema": {
        "type": "object"
      }
    },
    {
      "name": "pipedream-billing.create_invoice",
      "description": "Draft an invoice for a contact",
      "input_schema": null
    }
  ],
  "count": 2,
  "has_next_page": false,
  "next_cursor": null
}

Invoke one capability by name with its arguments.

Call a capability

post/v1/capabilities/call
capabilities:invoke
Request body
namestringrequired
A capability's name, exactly as returned by the list endpoint.
argumentsobjectoptional
Arguments for the capability. Defaults to no arguments if omitted.
Errors
400name is missing or blank.
403Missing scope, or this token is client-restricted (Capabilities is account-wide).
409This account's connected capabilities aren't ready yet.
429Rate limited — see Authentication and Rate limiting.
502The capability's own error — status and message vary by what went wrong. The message is always the capability's real error text, not a generic failure.
504The capability is temporarily unavailable. Retry shortly.
post/v1/capabilities/call
Sua chave de API
Corpo da solicitação*
{
  "data": {
    "id": "c_204",
    "email": "jane@example.com",
    "name": "Jane Doe"
  }
}

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": "..." } }