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

# Custom APIs

> Connect any REST API that uses an API key, bearer token or basic auth

A custom API connects Vybe to a REST API that isn't in the integration or MCP catalogs, such as your own internal service. You store the credential once. Vybe adds it to every request on its servers, so AI coworkers and apps can call the API without ever seeing the key.

## Check that your API fits

A custom API works when the API:

* uses one static secret on every request: an API key in a header, a bearer token, or basic auth
* is served over HTTPS from one base domain
* takes JSON or file upload (multipart) request bodies

Custom APIs don't support OAuth or any per-user sign-in, keys sent as query parameters, request signing, or login sessions and cookies.

> [!TIP]
>
> Not sure? Ask a coworker:
>
> > Can we connect Acme Billing as a custom API?
>
> It reads the service's API docs. If the authentication fits, it shows an **Add *service* as a custom API** card with setup steps that links to the create form. If it doesn't fit, it tells you which part isn't supported.

## Create a custom API

**1. Open the form**

Go to **Connections** in the sidebar, open the **Advanced** tab and click **Add Custom API**. You can also go to **Settings → Data → Custom APIs** and click **Add Custom API**.

**2. Fill in the details**

| Field | What to enter |
| - | - |
| **Type** | **Free text** or **OpenAPI**: how you'll describe the API in **Documentation** |
| **Name** | At least 6 characters, no spaces, for example `StripeAPI` |
| **Auth Type** | **API Key**, **Bearer Token** or **Basic Auth** |
| **API Key**, **Bearer Token** or **Basic Auth** | The credential itself. For **Basic Auth**, enter `username:password`. |
| **API Key Header (optional)** | For **API Key** only: the header your key is sent in. Defaults to `X-Api-Key`. |
| **Domain (optional)** | The API's base domain, for example `api.stripe.com` |
| **Scope** | **Organization (all apps)** or **Specific Apps**. For **Specific Apps**, tick the apps under **Select Apps**. |
| **Description (optional)** | What the API is used for |
| **Documentation (optional)** | Docs, examples, or a pasted OpenAPI spec |

**3. Save**

Click **Create Custom API**.

Fill in **Domain** so calls only need a path, such as `/v1/customers`. Without a domain, every call has to use a full URL.

Vybe sends the credential like this:

| Auth Type | Header Vybe adds |
| - | - |
| **API Key** | `X-Api-Key: <your key>`, or the header you set |
| **Bearer Token** | `Authorization: Bearer <your token>` |
| **Basic Auth** | `Authorization: Basic <username:password, base64-encoded>` |

## How Vybe protects the credential

* Vybe encrypts the credential and never shows it again after you save it.
* Vybe adds the credential to each request on its servers. Coworkers, app code and the browser never see it.
* When a credential is attached, calls must use HTTPS.
* Calls to private or internal network addresses, such as `localhost` or `10.x.x.x`, are blocked.
* Vybe removes the credential from error responses before showing them.

See [Secrets and encryption](https://docs.vybe.build/security/secrets-and-encryption.md).

## Add documentation

Coworkers and the app editor's AI read a custom API's **Documentation** before they call it. You'll see "Retrieved custom API documentation" in the chat. The better the docs, the fewer wrong guesses about endpoints and fields.

* **Free text**: paste the parts of the API docs that matter, with example requests and responses.
* **OpenAPI**: paste the OpenAPI spec as JSON or YAML, then click **Validate OpenAPI**. You'll see "OpenAPI spec is valid", or a list of **OpenAPI Validation Issues** to fix.

In the app editor, you can also paste an OpenAPI spec into the chat and ask the AI to generate a typed TypeScript client from it. The AI adds the client to the app's server code.

## Who can use a custom API

The **Scope** decides which apps can call the API:

* **Organization (all apps)**: every app in your organization. These are also the only custom APIs that AI coworkers can use.
* **Specific Apps**: only the apps you selected. Coworkers can't use these; their **Connections** section shows "Restricted to specific apps".

AI coworkers start with no access to any custom API. To give access, open the coworker's **Connections** section, go to the **Advanced** tab and turn on the custom API's switch, or approve the coworker's request in chat. If you create the custom API from the coworker's **Add *service* as a custom API** card and keep the **Organization (all apps)** scope, that coworker gets access right away. Custom API access is on (**Full access**) or off, with no read-only level.

## Use a custom API in chat

> Call our billing API and list the invoices that failed in the last 7 days.

> Look up customer 4821 in the Acme API and tell me their plan.

Each call appears as a step such as "Called GET /v1/invoices". In the coworker's activity history, calls appear as "Called custom API". A call times out after 30 seconds, or 120 seconds when it uploads files.

## Use a custom API in apps

The AI in the app editor writes the code. It calls the custom API through Vybe's helpers, which add the credential for you:

```typescript theme={null}
import { callCustomApiFromServer } from '@/server-lib/custom-api-client';

const result = await callCustomApiFromServer('custom-api-id', {
  method: 'POST',
  path: '/v1/invoices',
  body: { customerId: '4821' },
});
```

Browser code uses `callCustomApi` from `@/client-lib/custom-api-client` the same way. App code never reads the key from environment variables or sets the auth header itself. See [Working with code](https://docs.vybe.build/apps/working-with-code.md).

## Edit or delete a custom API

Custom APIs are listed on the **Advanced** tab of **Connections** and under **Settings → Data → Custom APIs**, with their **Type**, **Domain** and **Scope**.

To edit one, click **Edit** next to it. On **Edit Custom API**:

* You can change the type, name, API key header, domain, scope, description and documentation.
* "Auth type can't be changed after creation." To switch auth type, create a new custom API and delete the old one.
* To replace the credential, fill in the credential fields. "Leave all credential fields blank to keep the current values, or fill them all in to replace them."

Click **Save Changes**.

To delete one, click **Delete** next to it and confirm. This permanently deletes the custom API. Apps and coworkers that use it lose access.


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