# Custom API

> Connect any REST API, such as your own app or a tool without a connector, so your AI can read from it and, with your approval, make changes.

Connect any REST API on a public https address: your own app, an internal tool, or a service Plugsight has no connector for. You give Plugsight the API's address and how it signs in. Your AI can then call it through your MCP server. Import the API's OpenAPI (Swagger) spec and each endpoint becomes its own tool, so your AI knows what the API can do.

## What your AI can do

- **Read from the API**: any `GET` request under the address you connect, with JSON answers read for your AI.
- **Use each endpoint as a tool**: with an OpenAPI 3 or Swagger 2.0 spec imported, every endpoint is its own tool, with its parameters and request body, for APIs with up to 50 endpoints.
- **Look up endpoints**: your AI can list and search every imported endpoint (up to 300), with its parameters, and call any of them.
- **Make changes**: `POST`, `PUT`, `PATCH` and `DELETE` requests, only when you allow changes, and each one waits for your approval in the chat.

### Example questions

- "Using the Acme CRM API, list the customers who signed up this week."
- "Look up order 1042 in our fulfilment API and tell me where it's stuck."
- "Which endpoints does the inventory API have for stock levels?"
- "Create a ticket in our tracker for the bug I just described."

## What you need

- The Pro or Agency plan. On Free, the Custom API tile shows **On Pro: upgrade to connect**. See [Plans](https://docs.plugsight.app/get-started/plans.md).
- The API's base URL: the public https address every request starts with, like https://api.example.com/v1.
- How it signs in, from the API's documentation or settings: an API key, a bearer token, a username and password, or an OAuth 2.0 client ID and secret.
- Optionally, the API's OpenAPI or Swagger spec, as a web address or a file you can copy from (JSON or YAML, up to 2 MB).

> [!TIP]
> Make a key just for Plugsight, with only the access your AI needs. You can delete it at the API's end any time to cut access.

## Connect your API

1. In Plugsight, open **Connections**, click **Add connection** and choose Custom API (any REST API) in the catalog.
2. Type the API's **Base URL**, like https://api.example.com/v1. Your AI can only call paths under it.
3. Optionally give the connection a **Name**, such as "Acme CRM". It also starts the names of the API's tools, so keep it short.
4. Under **How it signs in**, choose one, then fill in the boxes it shows:
   - **API key**: choose where to send it under **Send the key in** (a header or the query string), type the header or parameter name your API expects, such as X-API-Key, and paste the **API key**.
   - **Bearer token**: paste the **Token**. It's sent as "Authorization: Bearer" and the token.
   - **Username and password**: type the **Username** and **Password**.
   - **OAuth 2.0 client credentials**: type the **Token URL**, **Client ID** and **Client secret**, and the **Scope** if your API needs one. Plugsight gets an access token itself and renews it when it expires.
   - **No sign-in**: for APIs anyone can call.
5. If your API wants more on every request, such as an account id, click **Add header** under **Extra headers** and type its name and value.
6. To import a spec, choose **From a web address** or **Paste it** under **OpenAPI spec**, then give the **Spec address** or paste the **Spec**.
7. Optionally type a **Test path**, such as /me. Plugsight sends a `GET` request to it before saving, and only saves if it succeeds. Pick one that only reads.
8. Click **Test connection & save**.

When it works, you see a message like "Connected Acme CRM (api.example.com), id "acme-crm". Imported 12 operations, each a tool your AI can use."

Then add the connection to an MCP server. Each import adds or changes tools, so [refresh the tools list](https://docs.plugsight.app/ai-apps/refresh-tools.md) in your AI app and start a new chat.

### Connect it again

To change the key, or import a new version of the spec, connect it again with the same **Base URL** and **Name**: Plugsight replaces what it has. Without a new spec, the endpoints already imported stay. With a different **Name**, it's a second connection, which is how you connect the same API twice, for example with a test key and a live key.

## What it can and can't change

Reading is always on: your AI can send `GET` and `HEAD` requests whenever the connection is in its MCP server.

`POST`, `PUT`, `PATCH` and `DELETE` requests change things in your API, so they need all of these:

1. Your plan includes changes (Pro and Agency do).
2. The connection's switch on **Connections** says **Can make changes**. It starts as **Read-only** for every API you connect.
3. **Allow changes** is ticked on the MCP server your AI app uses.
4. **Custom APIs and MCP servers** isn't paused on **Permissions**.
5. You approve the exact request in the chat.

See [How changes are allowed](https://docs.plugsight.app/permissions/how-changes-are-allowed.md).

What Plugsight never does, whatever you allow:

- It never calls an address outside the base URL. A request for a full address, another site, or a path that climbs out of the base URL (with `..`) is refused before anything is sent.
- It never calls private or local networks, and never follows redirects.
- It never shows your key, token, password, client secret or extra headers to your AI. They're stored encrypted, and cut from anything the API sends back.
- It never sets headers such as Host, Cookie or Content-Length, and your AI can't replace the sign-in or your extra headers.

To cut access, delete the key at the API's end, and remove the connection on **Connections**.

## Limits

- Public https addresses on the standard port only.
- Each request has 30 seconds to answer. Plugsight reads up to 1 MB of the answer, and gives your AI up to 100,000 characters of it; anything longer is cut, and your AI is told so.
- Request bodies are JSON or plain text, up to 1 MB. File uploads and forms aren't supported.
- A spec can have up to 300 endpoints imported. With more than 50, they don't get tools of their own: your AI finds them in the list and calls them by name.
- Only references inside the spec are followed; parts that point to other files are described loosely.
- Up to 20 extra headers.

## Troubleshooting

### Custom API connections are on the Pro plan. Upgrade under Billing to connect your own APIs.

**What it means:** Your plan doesn't include Custom APIs.

**How to fix it:** Upgrade under **Billing**. See [Plans](https://docs.plugsight.app/get-started/plans.md).

### The base URL must start with https://. Plugsight only sends keys over encrypted connections.

**What it means:** The address starts with http://, so keys would travel unencrypted.

**How to fix it:** Use the API's https:// address. If it has none, Plugsight can't connect to it.

### That address isn't a public website. Enter the API's public https address, like https://api.example.com/v1.

**What it means:** The address points to a private or local network, which Plugsight never calls.

**How to fix it:** Use the API's public address on the internet.

### The test request (GET [path]) answered HTTP [status]. Check the base URL, the sign-in details and the test path.

**What it means:** The API answered the test path with an error, so nothing was saved. 401 or 403 usually means the sign-in is wrong; 404 means the base URL or test path is.

**How to fix it:** Check each detail against the API's documentation, or leave **Test path** empty to save without the test.

### The token URL didn't give an access token (HTTP …). Check the token URL, client ID, client secret and scope.

**What it means:** The OAuth token endpoint refused the client ID and secret, or answered something else.

**How to fix it:** Copy the client ID and secret again, check the **Token URL**, and leave **Scope** empty unless your API needs one.

### That OpenAPI spec is larger than 2 MB. Import a smaller one, or call the API by path instead.

**What it means:** The spec is too big to import.

**How to fix it:** Import a smaller version of the spec, such as one section of the API, or connect without a spec. Your AI can still call the API by method and path.

### The API rejected the saved sign-in details (HTTP 401).

**What it means:** The API no longer accepts the key or token. The connection shows **Reconnect needed**.

**How to fix it:** Make a new key or token, then [connect it again](#connect-it-again) with the same **Base URL** and **Name**.

### Changes are off for "[connection]". Allow them under Connections first.

**What it means:** The connection's switch is **Read-only**, so your AI can read but not change anything.

**How to fix it:** On **Connections**, click the switch so it says **Can make changes**.

### Custom API changes are paused (Permissions page).

**What it means:** Changes through Custom APIs and custom MCP servers are paused for every connection.

**How to fix it:** On **Permissions**, resume **Custom APIs and MCP servers**. See [Pause changes](https://docs.plugsight.app/permissions/pause.md).

## Related articles

- [How changes are allowed](https://docs.plugsight.app/permissions/how-changes-are-allowed.md)
- [Approvals in the chat](https://docs.plugsight.app/permissions/approvals.md)
- [Refresh the tools list](https://docs.plugsight.app/ai-apps/refresh-tools.md)
- [Custom API tools](https://docs.plugsight.app/developers/custom-api-tools.md)
- [Custom MCP server](https://docs.plugsight.app/connectors/custom-mcp.md)
- [Connectors](https://docs.plugsight.app/connectors.md)

---

Web version: https://docs.plugsight.app/connectors/custom-api
