DEVELOPERS
First context call in five minutes
Connect a source, create a scoped key, make a request. Everything else is optional.
ON THIS PAGE
Quickstart
Authentication
Request anatomy
Errors
Webhooks
Resources
Your first request in five minutes
1
Install
Grab the SDK from npm. Node 18+, TypeScript types included.
npm install @switchyard/sdk
2
Authenticate
Create a scoped key in the dashboard and export it. A key never grants more than its scope.
export SWITCHYARD_API_KEY=sk_live_… # scoped key
3
Send a request
Ask in plain language. Switchyard resolves permissions, queries your sources, and returns a cited context object.
const ctx = await switchyard.search({ query: “overdue invoices” })
Anatomy of a request
REQUEST
{
“query”: “overdue invoices”,
“user”: “support-bot”,
“sources”: [“stripe”, “postgres”],
“scope”: “invoices.read”
}
RESPONSE · 48MS
{
“matches”: 3,
“confidence”: 0.94,
“trace_id”: “req_8f42”,
“status”: “verified”
}
When something goes wrong
401
Missing key
Set SWITCHYARD_API_KEY.
403
Scope not granted
Request the scope in the dashboard.
429
Rate limited
Back off and retry after 30s.
409
Approval required
Route to a human approver.
RESOURCES
Everything else you need
MCP in three steps
01
Generate an MCP key
Create a scoped key in the dashboard and mark it for MCP use. Scope it to exactly the sources your client should see.
switchyard keys create --mcp
02
Add the server block
Paste the Switchyard server entry into your client’s MCP config: Claude, Cursor, or any MCP-compatible client.
npx @switchyard/mcp
03
Ask a question
Restart the client and query your own systems in plain language. Every call appears in the trace explorer like any other request.
ask: "what changed in billing today?"
AUTHENTICATION
Scoped keys, not god keys
Every key carries explicit scopes: which sources it can read, which actions it can execute, and optional expiry. Keys are shown once at creation. Rotate them from the dashboard or the API, and revoke instantly. There is no all-access key, on purpose.
ERRORS
Errors you can act on
Every error returns a stable code, a human-readable message, and the trace ID. Permission failures tell you which scope was missing. Source failures tell you which system timed out and whether Switchyard served partial context. Rate limits return a retry-after header. The SDKs raise typed errors so your agent can branch on them.
WEBHOOKS
Know when something changes
Subscribe to events: source disconnected, action executed, scope revoked, usage threshold crossed. Deliveries are signed and retried.
MONITORING
Watch a query continuously
Pair webhooks with the monitor API to watch a query continuously and get pushed when the answer changes.
Go deeper
API reference. Every endpoint, parameter, and error code.
SDK guides. TypeScript and Python, end to end.
MCP server. Setup, scoping, and client notes.
Trace explorer. Read and search every request your agents make.