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 modal
1
Open Settings → Integrations
In Ravenna, go to Settings → Integrations and click Create. The Create integration modal opens on the provider picker.
2
Skip the curated provider picker
The picker lists Ravenna’s curated providers with a search box. If the API you want is on the list, click it and connect from there instead of following this guide. Ravenna already has the base URL, test endpoint, and OAuth endpoints for you, prefills the API key header name and location when it knows them, and skips docs research entirely since the catalog entry serves as the research.For any API not in the list, click Can’t find it? Set up a custom integration at the bottom of the picker.
3
Name the integration
Enter the API name you want to use. As you type, Ravenna searches Context7’s documentation index and offers to auto-configure from any match. Click the match to prefill the docs URL and description, then jump straight to Connect.If nothing matches or you want to fill in the details yourself, click the Advanced option to expand the full field set:
- 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.
4
Wait for research
Ravenna reads the documentation to learn how the API works, including pagination, auth, rate limits, error handling, and versioning. A banner on the Connect screen shows research progress. 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.
5
Connect
If research detected the API’s auth method, the matching Authentication Method is already pre-selected on the Connect screen. 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 method if the suggestion is wrong.Pick the authentication method 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. - OAuth 2.0. Pick an OAuth provider you’ve already registered in Settings → OAuth Providers. The option is hidden until your organization has at least one.
- 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.Click Connect. Ravenna runs a test call against the auth test endpoint (or the OAuth token exchange) and saves the integration once it succeeds. It 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.