Skip to main content
Some systems have no Swan catalog integration and no MCP server to connect. For those, there’s a third route: Swan calls the system’s API directly. You store the API key as a secret, then ask Swan — in chat or in a trigger — to work with that API. Swan reads the API’s documentation, writes the code, runs it in its code sandbox, and can save the working integration as a skill so it never has to figure it out twice. This is the fallback, not the default — catalog integrations and MCP servers handle authentication and data schemas for you, so check those first. But it means “there’s no integration” is rarely a dead end.

​
Secrets

A secret is a named credential — an API key, token, or connection string — stored in Swan:
  • Org secrets are usable by every user and trigger in the org.
  • Personal secrets are usable only by you. A personal secret with the same name as an org secret overrides it for your runs.
Manage them at Settings → Secrets. Values are encrypted at rest, and the agent can never read them back: it sees only secret names (plus scope and when each was last used). In code, Swan references a secret as a placeholder — ${secret.STRIPE_API_KEY} — and the real value is injected only at execution time, inside the sandbox. It never appears in the conversation, and code that would leak a resolved value into an output file is blocked automatically. One rule on your side: don’t paste keys into chat. If you do, Swan is instructed to have you add the key at Settings → Secrets instead and delete the message — a value pasted in chat lives in the conversation history; a secret doesn’t.

​
How Swan works with an API

Ask for what you want in plain language — “pull our open invoices from our billing system, the key is stored as BILLING_API_KEY”. Swan then works the way a careful engineer would:
  1. Reads the docs first. It researches the official API reference for the exact endpoints it needs — auth format, parameters, pagination, rate limits — rather than guessing from memory.
  2. Validates step by step. First a cheap authenticated check, then a single read, then — only if the task requires writing — a single write, confirming with you before the first write to a production system. Only then does it scale up to the full job.
  3. Handles failures diagnosably. Non-success responses are surfaced with their status and cause, so a bad key, a permissions gap, or a wrong endpoint gets fixed rather than retried blindly.
Each code run costs 1 credit — see credit costs.

​
Swan remembers what works

Once an integration works, Swan documents it as an org skill — which secret name to use, the auth format, the endpoints and parameters that mattered, and any gotchas — so the next run, a trigger, or a teammate reuses the working recipe instead of rediscovering it. If you’ll use the API regularly, this is what makes it dependable: the first run is exploration, every run after is routine.

​
Common questions

Can Swan see or accidentally reveal my API key? No. The agent only ever sees secret names. Values are injected into code at execution time inside the sandbox, are never echoed back, and output that would contain a resolved value is blocked. Can a trigger use a secret? Yes — org secrets are available to triggers, so a standing automation can call your API on every run. Personal secrets are only available in your own runs. What happens if Swan references a secret that doesn’t exist? The run fails with the missing secret’s name, and Swan asks you to add exactly that name at Settings → Secrets, then retries. How do I rotate a key? Update the secret’s value at Settings → Secrets — the name stays the same, so nothing that references it needs to change. Should I use this instead of a catalog integration? No — if the app is in the catalog or has an MCP server, use that; auth and schemas are handled for you. Direct API access is for everything else.