Talk to Sydekick from your own backend

Dispatch a message to a Synup account's Sydekick agent and get the reply back — however fits your integration. This is a backend/API surface only: you build your own front-end entirely, this API only controls what comes back in the response.

How it works

Every message is dispatched asynchronously: POST /v1/agent/messagesalways returns immediately with a job id — it never blocks waiting for the agent's reply. From there you pick however many of these three ways you want to learn the answer:

• Poll — GET /v1/agent/messages/{id}, the simplest contract, always available.
• Stream — a short-lived stream_url returned at dispatch time, for a live typing-style experience. See Streaming.
• Webhook — register a URL once (Settings → Developer → Webhooks) and get agent.message.completed/agent.message.failed pushed to you, no polling at all.

All three read from the same underlying event log — nothing is special-cased per delivery style, and a dropped stream connection never loses anything or restarts the agent turn.

Concurrency limiting — this is not queued

Each account has a limited number of agent messages it can process at once, set by your plan. If you go over it, the dispatch call fails immediately with a 429 agent_concurrency_limit error telling you to retry shortly — nothing is queued on our end. Design your integration to retry (with backoff) on that specific error, not to assume unlimited parallelism.

This is a differentlimit from the account's request-rate limit (how many API calls per minute — see Authentication and Rate limiting). One governs how many requests you can make; this one governs how many the agent can work on at the same time.

What to expect: turns that need human approval

Some actions Sydekick can take require approval in the account's own dashboard (the same "Pending approvals" inbox a logged-in team member sees) before they run — true regardless of which surface asked for it. A headless API caller can't answer that kind of prompt, so a dispatched task that hits one fails with status: "failed" and an errorReason starting with approval_required:, naming the tool that needed a decision.

This can happen unpredictably — the same message can succeed cleanly on one run and hit this on another, depending on which action the agent decides to take. Design for it: someone with dashboard access resolves the pending approval directly, or your integration avoids asking for things that would require one. Treat any approval_required:error as distinct from a genuine failure — the turn didn't go wrong, it just hit a decision only a human in the dashboard can make.