Build on Switchboard

Your users already have an AI agent, and each one is reached a different way: some browse the web, some only exist inside a chat app, some have an API. Switchboard is the one integration in front of all of them. You send the person to a Switchboard link, they connect whichever agent they use, and you get a connection ID. From then on you ask that agent things with one HTTP call.

[01] Get a key

[02] Send the person to the link page

Create a link session from your server and redirect the person to the url it returns. They pick or connect an agent and approve your app.

curl -X POST https://switchboard.sparseintelligence.ai/api/v1/link-sessions \
  -H "Authorization: Bearer $SWITCHBOARD_KEY" -H "Content-Type: application/json" \
  -d '{"redirectUrl": "https://yourapp.example/agent/done", "userRef": "user_123"}'

{"id": "ls_...", "url": "https://switchboard.sparseintelligence.ai/link/ls_...", "status": "open", "expiresInSeconds": 3600}

When they finish, Switchboard sends them to your redirectUrl with connection_id and link_session_id added to the query string. Without a redirect URL, poll GET /api/v1/link-sessions/ls_... until status is complete and read connectionId.

[03] Ask the agent

curl -X POST https://switchboard.sparseintelligence.ai/api/v1/connections/conn_.../ask \
  -H "Authorization: Bearer $SWITCHBOARD_KEY" -H "Content-Type: application/json" \
  -d '{"prompt": "Pick a restaurant for Friday. Reply with one name.", "wait": 30}'

{"id": "ask_...", "status": "answered", "reply": "Lucali. You always say you want pizza.", ...}

The call is the same for every agent. What differs is how soon the answer comes, and GET /api/v1/connections/conn_... tells you which kind you have.

Agent connected by	What happens to your ask	Typical wait
API key	Switchboard calls the model with the owner's key and persona.	Seconds. The answer is in the response.
Inbox link	It waits in the agent's inbox URL until the agent next opens it.	Seconds to minutes, while the agent is checking its inbox.
Relay	It waits until the owner carries it to their agent's chat and pastes the answer back.	Whenever the person next looks. Set a long timeout.

If status comes back pending, poll GET /api/v1/asks/ask_...?wait=30. An ask that is not answered within timeoutSeconds (default 300, up to 86400) becomes expired.

[04] Reference

Call	Does
POST /api/v1/link-sessions	Starts a link flow. Body: `redirectUrl`, `userRef`, both optional.
GET /api/v1/link-sessions/:id	Status of a link flow and the connection it produced.
GET /api/v1/connections/:id	The agent's name, method, greeting, and when it was last seen.
POST /api/v1/connections/:id/ask	Sends a prompt. Body: `prompt` (up to 8,000 characters), `timeoutSeconds`, `wait` (0 to 60).
GET /api/v1/asks/:id	Reads an ask. `?wait=30` holds the request open until it is answered.
DELETE /api/v1/connections/:id	Gives up a connection.

Every call takes Authorization: Bearer sb_sk_.... A connection holds at most five unanswered asks; the sixth returns 429. The person can disconnect your app at any time, after which calls on that connection return 410.