> ## Documentation Index
> Fetch the complete documentation index at: https://docs.abundly.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# API Access
> Expose your agent to external systems via HTTP API, MCP, webhooks, or an embeddable chat widget
Your agent can be called from outside Abundly. In the agent's **Settings → API Access** tab, you can expose the agent as an HTTP API, as an [MCP](/integrations/mcp) server, as a webhook receiver, and as an embeddable chat widget — each with its own configuration, but sharing the same API keys.
## When to use each
| Exposure mode | Use for | Authentication |
| ---------------- | ------------------------------------------------------------------------------------- | -------------------------------------- |
| **HTTP API** | Calling your agent from a script, backend service, or automation tool | API key |
| **Document API** | Reading and writing agent documents from external systems | API key |
| **MCP server** | Letting AI apps like Claude Desktop, Cursor, or n8n use your agent as a tool provider | API key |
| **Chat widget** | Embedding an AI chat bubble on your own website | API key (stored on your backend proxy) |
| **Webhooks** | Receiving callbacks from external services like Stripe, GitHub, or Trello | None (URL is the secret) |
All modes run through the same agent, respect the same capabilities and guardrails, and log activity to the [activity log](/features/monitoring).
## API keys
HTTP API and MCP calls are authenticated with API keys. Open the **API Keys** section to create, list, and revoke keys for the agent.
Include a key on every request using either header:
```
X-Agent-Access-Key: your_key_here
Authorization: Bearer your_key_here
```
Keys grant full access to the endpoints you've defined. Never commit them to source control or expose them in client-side code.
### Workspace API keys
By default, API keys are scoped to a single agent. If you have multiple agents that external systems need to access, you can create **workspace API keys** instead — a single key that authenticates across all agents in the workspace that opt in.
1. Go to **Workspace → API Keys** tab and create a workspace key (requires workspace admin role)
2. On each agent that should accept the key, open **Settings → API Access → API Keys** and enable **Allow Workspace Keys**
Workspace keys use the same headers as agent keys and work with all exposure modes (HTTP API, Document API, MCP, widget). They start with `wk_` to distinguish them from per-agent keys.
## HTTP API
Turn on **Enable HTTP API** to expose your agent at:
```
https://your-service-domain/agents/{agentId}/api/{path}
```
You explicitly define which paths are available. Any request to an undefined path returns 404.
For each endpoint, you choose:
* **Path** — e.g. `summarize` or `ingest/orders`
* **Handler** — either a natural-language prompt for the agent, or a [script](/features/scripts) that runs directly without invoking the LLM
* **Model override** (optional) — run this endpoint on a specific model, separate from the agent's default
```bash theme={null}
curl -X POST https://your-service-domain/agents/{agentId}/api/summarize \
-H "X-Agent-Access-Key: your_key_here" \
-H "Content-Type: application/json" \
-d '{"text": "..."}'
```
The JSON body is passed to the agent (or script) as input. The response contains the agent's reply.
## Document API
The Document API provides built-in REST endpoints for reading and writing your agent's [documents](/features/documents) — no custom scripts needed.
Turn on **Enable Document API** and select which documents to expose. For each document, you choose read and/or write permissions.
Documents are accessed at:
```
https://your-service-domain/agents/{agentId}/documents/{documentId}
```
The document ID is shown in the settings card for each exposed document.
### Reading a document
```bash theme={null}
curl https://your-service-domain/agents/{agentId}/documents/{documentId} \
-H "X-Agent-Access-Key: your_key_here"
```
Returns the document's name, description, content, and data (if it's a [database](/features/agent-databases)).
### Querying a database document
For database-type documents, you can query, insert, update, and delete records:
```bash Query theme={null}
curl -X POST https://your-service-domain/agents/{agentId}/documents/{documentId}/data/query \
-H "X-Agent-Access-Key: your_key_here" \
-H "Content-Type: application/json" \
-d '{"filter": {"category": "Electronics"}}'
```
```bash Insert theme={null}
curl -X POST https://your-service-domain/agents/{agentId}/documents/{documentId}/data/insert \
-H "X-Agent-Access-Key: your_key_here" \
-H "Content-Type: application/json" \
-d '{"items": [{"name": "New Product", "price": 29.99}]}'
```
The Document API is useful when external systems need to read or update the same data your agent works with — for example, syncing a product catalog, populating a knowledge base, or pulling reports.
## MCP server
[MCP](/integrations/mcp) (Model Context Protocol) lets external AI applications — Claude Desktop, Cursor, n8n, and others — call tools you define on your agent.
Turn on **Enable MCP server** to expose the agent at:
```
https://your-service-domain/agents/{agentId}/mcp
```
For each **tool** you add, you specify:
* **Name and description** — shown to MCP clients so they know when to call it
* **Handler** — a prompt for the agent, or a [script](/features/scripts) for deterministic execution
* **Model override** (optional)
Connect from Claude Desktop by adding your server to the MCP config:
```json theme={null}
{
"mcpServers": {
"my-agent": {
"url": "https://your-service-domain/agents/{agentId}/mcp",
"headers": {
"X-Agent-Access-Key": "your_key_here"
}
}
}
}
```
## Chat widget
The chat widget embeds your agent as a floating chat bubble on any external website. Visitors can ask questions and get streaming answers — without logging in or leaving your site. Turn on **Enable widget** in the API Access tab to configure it.
The widget uses a secure backend proxy pattern: a small server-side endpoint on your server holds the API key and forwards requests to Abundly, so your key never appears in client-side code.
For setup instructions, backend proxy examples, configuration options, and the headless `createClient` API, see the [Chat Widget](/features/chat-widget) page.
## CORS settings
If you want to call your agent's HTTP API directly from a browser (for example, from a web application), you need to configure which origins are allowed to make cross-origin requests. In the **HTTP API** section, use **Allowed origins (CORS)**:
* **Allow requests from Abundly apps** — Automatically allows requests from Abundly's user-facing domains
* **Custom origins** — Add any additional origins (e.g. `https://yourapp.com`) that should be permitted to make browser requests
CORS restrictions apply to browsers only. If you're calling the API from a server-side environment, you can leave CORS unconfigured. The chat widget always goes through your backend proxy (server-to-server), so it doesn't need a CORS entry either.
## Webhooks
Many external services send notifications by calling a URL you provide — Stripe after a payment, GitHub when a PR opens, Trello when a card moves. Turn on **Enable Webhooks** to receive these callbacks.
Each webhook you define gets its own URL:
```
https://your-service-domain/agents/{agentId}/webhook/{integration}
```
Unlike HTTP API calls, webhooks don't use API keys — the URL itself provides routing. Requests to undefined integration names return 404.
For each integration, configure:
* **Integration name** — used as the URL path, e.g. `stripe` or `github`
* **Handler** — a prompt describing how the agent should process the callback, or a [script](/features/scripts) for fast, deterministic handling
* **Model override** (optional)
* **Signature verification** (optional) — enable HMAC signature verification to ensure requests are authentic. Many services (Jira, GitHub, Stripe, Linear, Shopify, etc.) sign webhook payloads with a shared secret. When configured, Abundly verifies the signature before processing — requests with invalid or missing signatures are rejected with a 401. Store the signing secret as a "Webhook signing secret" in your workspace's Secrets page.
Webhooks respond immediately with `200 OK` and process the payload asynchronously, so external services never time out.
Paste the webhook URL into the external service's webhook settings. The agent will run each time the service fires an event — driven entirely by your prompt or script.
## Agent self-management
If you want the agent to manage its own exposed surfaces programmatically — for example, spinning up a webhook endpoint in response to a user request, or exposing a new MCP tool after learning a new skill — enable the **Endpoint Management** capability on the agent's [capabilities](/features/capabilities) page.
With this capability, the agent can list, add, update, and remove entries across HTTP API endpoints, Document API entries, MCP server tools, and webhooks, as well as toggle surface settings like enabling/disabling, activity logging, and CORS configuration.
## Activity log
All exposure modes record entries in the [activity log](/features/monitoring), including the full request headers and body, the agent's response, and any credits consumed. You can disable logging per section if you have a high-volume endpoint where logging isn't useful.
## Learn more
Add external MCP servers to your agent's capabilities
Back endpoints, tools, and webhooks with scripts for faster handling
Review what your agent does when triggered externally