> ## 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, or basic auth). 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>

***

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

<Steps>
  <Step title="Open Settings → Integrations">
    In Ravenna, go to **Settings → Integrations**, pick the **Custom** category, and click **New Integration**.
  </Step>

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

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

    <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="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. Some APIs (like Stripe and Mailgun) expect an API key as the username. In that case, paste the key as the username and leave the password blank — Foundry still sends the `Authorization` header.
    * **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`.
  </Step>

  <Step title="Review and save">
    Confirm your settings and save. The integration 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>