> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ravenna.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Set up a custom API integration

> Connect a tool to Ravenna using a static credential (API key, bearer token, basic auth) or an advanced login exchange. Walkthrough of the Settings → Integrations wizard.

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](/guides/how-to/foundry/setup-oauth/overview) instead.

<Callout icon="link" color="#6B7280">
  Reference: [Integrations](/documentation/automate/foundry/integrations) in the main docs covers the full UI surface and field-by-field behaviour.
</Callout>

<Info>
  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](/documentation/automate/foundry/integrations#set-up-a-custom-integration-from-copilot-chat).
</Info>

***

## 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

<Steps>
  <Step title="Open Settings → Integrations">
    In Ravenna, go to **Settings → Integrations** and click **Create**. The Create integration modal opens on the provider picker.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.

    Then click **Continue**.
  </Step>

  <Step title="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.

    <Info>
      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.
    </Info>
  </Step>

  <Step title="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: Basic` header 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](/documentation/automate/foundry/integrations#advanced-auth) for the full field-by-field reference.
    * **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`.

    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.
  </Step>
</Steps>

***

## 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:

<Prompt description="List all open Linear issues assigned to the requester's email and return the title, status, and URL.">
  List all open Linear issues assigned to the requester's email and return the title, status, and URL.
</Prompt>

Foundry generates the code, type-checks it, and runs a dry-run. Iterate in chat until it does what you want, then publish.

<Callout icon="link" color="#6B7280">
  Full build → test → refine → publish loop: [Building functions](/documentation/automate/foundry/actions).
</Callout>

***

## What to try next

<CardGroup cols={2}>
  <Card title="Examples" icon="sparkles" href="/guides/how-to/foundry/examples">
    Recipes you can adapt, with the prompts that generated them.
  </Card>

  <Card title="Tips & troubleshooting" icon="life-ring" href="/guides/how-to/foundry/tips-and-troubleshooting">
    Get more out of Foundry, and fix the most common issues.
  </Card>
</CardGroup>


## Related topics

- [Foundry integrations](/documentation/automate/foundry/integrations.md)
- [Foundry guide](/guides/how-to/foundry/overview.md)
- [Set up a custom OAuth app](/guides/how-to/foundry/setup-oauth/overview.md)
- [Setting up access provisioning](/guides/how-to/setting-up-access-provisioning.md)
- [Set up a form](/guides/day-one/set-up-form.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.