DEVELOPER DOCS

Build on a clear contract.

The fastest path from an API key to a production tool call. Keep credentials server-side, inspect every response, and make retries intentional.

01 / QUICKSTART

Make your first request.

Create a trial key in the Quickstart, save it in your secret store, then call the canonical MCP endpoint.

curl
curl -X POST https://mcp.swamix.com/mcp \
  -H "Authorization: Bearer swx_live_..." \
  -H "Content-Type: application/json" \
  -d '{"tool":"search","arguments":{"query":"launch notes"}}'
Never ship a swx_live_ key in a public client bundle, source control, logs, or a URL. The console keeps a connected key in memory only.
02 / TOOL CALLS

Discover, then execute.

Browser clients can use the authenticated bridge for catalog discovery and execution. Your bearer token is attached by the console API client.

POST /api/tools/call
const response = await fetch("/api/tools/call", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    name: "search",
    arguments: { query: "launch notes", limit: 5 }
  })
});
const result = await response.json();

Use GET /api/tools to load the current account catalog. Schemas are authoritative: validate required fields before sending a call.

03 / ERRORS

Errors are actionable.

400Bad request
The JSON shape or tool arguments are invalid. Check the tool schema.
402Credits required
The account balance cannot cover this operation.
403Forbidden
The key is valid but lacks access to this tool or operation.
404Not found
The route or named tool does not exist.
413Payload too large
Reduce input size or upload large assets through the supported flow.
429Rate limited
Back off using the response guidance; do not hot-loop retries.
502Upstream error
The provider failed. Retry safe, idempotent work with jitter.
504Upstream timeout
The request took too long. Poll asynchronous media runs rather than repeating blindly.
04 / RELIABILITY

Make retries safe.

Paid media tools accept an idempotency key. Send a unique key per intended operation and reuse that same key when recovering from a timeout or network failure.

idempotency
fetch("/api/media/image", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${token}`,
    "Idempotency-Key": "checkout-asset-2025-001"
  },
  body: JSON.stringify({ prompt })
});

For read-only tools, bounded exponential backoff is usually enough. For generation, do not create a new key on every retry or you may pay for duplicate work.