Reference: Integrations in the main docs covers the full UI surface and field-by-field behaviour.
Prefer chat? Ask Copilot to add the integration and it renders an inline setup card that walks the same config → credentials → validation flow described here. Credentials go straight to encrypted storage and are never sent to the LLM, and Copilot resumes on its own once you save them, so you never have to type “done”. See Set up a custom integration from Copilot chat.
Before you begin
You’ll need:- Organization admin access in Ravenna.
- A link to the tool’s API reference. OpenAPI or Swagger URLs work best, failing that, a page that lists endpoints and parameters.
- The credential the tool uses (API key, bearer token, or username and password).
Walk through the wizard
1
Open Settings → Integrations
In Ravenna, go to Settings → Integrations, pick the Custom category, and click New Integration.
2
Basics
Fill in:
- Name. What you want to call the integration.
- Logo. Optional, helpful for finding it later.
- Description. A short note about what it’s for.
- Category. Pick the best-fit group.
- Documentation URL. Link directly to the API reference. If the tool publishes an OpenAPI or Swagger URL, use that.
3
Research
Foundry reads the documentation to learn how the API works, including pagination, auth, rate limits, error handling, and versioning. You’ll see progress for each step. It usually takes under a minute.
If research stalls, the docs URL probably doesn’t point at a reference page. Try a more specific URL, like the “API reference” rather than the docs homepage.
4
Auth
If research detected the API’s auth method, the matching type is already pre-selected when you reach this step, and the Research step shows a banner explaining the suggestion. APIs that need a login/token-exchange call or multiple credential fields get Advanced pre-selected. OAuth 2.0 is never pre-selected. Change the type if the suggestion is wrong.Pick the authentication type and fill in the credentials:
- API Key. Paste the key and choose whether it goes in a header (most common) or a query parameter, then set the header or parameter name.
- Bearer Token. Paste the token; it’s sent as
Authorization: Bearer <token>. - Basic Auth. Paste the username and password. Basic auth also supports a key-as-username configuration: for APIs that authenticate with an API key in the username slot and no password (Stripe, Mailgun, Cursor), paste the key as the username and leave the password blank. Foundry sends a valid
Authorization: Basicheader either way. - Advanced. For APIs the other types can’t express: a login request that exchanges credentials for a token (Mosyle, for example), or multiple credentials spread across headers, JSON body, query string, or form fields. You define each credential as a row in a fields table, optionally configure the login exchange (login URL, where the token comes back, its prefix and lifetime), preview the exact request as curl or JSON, and run Test connection before saving. See Advanced auth for the full field-by-field reference.
- No Auth. For public APIs.
X-Tenant-Id: acme.5
Review and save
Confirm your settings and save. The integration appears in the Custom category and is ready for functions to use.
Build your first function on top
Open Foundry in the workspace sidebar and click New Function. In the function’s Integrations tab, connect the integration you just created. Then describe what the function should do in plain language. For example:List all open Linear issues assigned to the requester's email and return the title, status, and URL.
Full build → test → refine → publish loop: Building functions.
What to try next
Examples
Recipes you can adapt, with the prompts that generated them.
Tips & troubleshooting
Get more out of Foundry, and fix the most common issues.