Skip to main content
This walkthrough sets up a custom API integration, the right choice when the tool you’re connecting uses a single shared credential, like an API key. Every function built on top runs as the same service account. For tools where each end user should connect with their own account, see the OAuth setup overview instead.
Reference: Integrations in the main docs covers the full UI surface and field-by-field behaviour.

​
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

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.
  • No Auth. For public APIs.
Add any default headers that should be sent with every request. For example, a tenant header like 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.

Foundry generates the code, type-checks it, and runs a dry-run. Iterate in chat until it does what you want, then publish.
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.
Last modified on June 4, 2026