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

# Agents API Overview

> Create, manage, and chat with agents in your nuwacom workspace programmatically

The Agents API lets you create, manage, and chat with agents in your nuwacom workspace programmatically, for example to provision agents from your own tooling, keep agent instructions in sync with an external source, or build custom chat experiences on top of them.

## Before you start

* **API key**: All endpoints require a Bearer token. Admins can create API keys in the workspace settings under the **API Keys** section.
* **Space scope**: Agents always belong to a space, so all endpoints are nested under the space path (`/api/v1/spaces/{spaceId}/agents`). The caller's role in that space must grant read permission for the Agents feature to list or read agents, and write permission to create, update, or delete them.
* **Draft & published versions**: Create and update operations write to the agent's **draft**. [Publishing](/api-reference/agents/publish-an-agent) makes the draft the live version that the Completion API uses by default. API responses always show the draft state. The `published` field tells whether a published version exists, and `hasUnpublishedChanges` tells whether the draft differs from it. Who can see and use the agent is controlled separately via sharing in the nuwacom app.

## Base URL

```
https://{customer-tenant}.nuwacom.ai
```

Replace `{customer-tenant}` with your workspace's tenant name.

## Available endpoints

### Agents

| Method   | Endpoint                                              | Description                                                    |
| -------- | ----------------------------------------------------- | -------------------------------------------------------------- |
| `GET`    | `/api/v1/spaces/{spaceId}/agents`                     | [List agents](/api-reference/agents/list-agents)               |
| `POST`   | `/api/v1/spaces/{spaceId}/agents`                     | [Create a new agent](/api-reference/agents/create-an-agent)    |
| `GET`    | `/api/v1/spaces/{spaceId}/agents/{agentId}`           | [Get agent details](/api-reference/agents/get-an-agent)        |
| `PATCH`  | `/api/v1/spaces/{spaceId}/agents/{agentId}`           | [Update an agent](/api-reference/agents/update-an-agent)       |
| `POST`   | `/api/v1/spaces/{spaceId}/agents/{agentId}/publish`   | [Publish an agent](/api-reference/agents/publish-an-agent)     |
| `POST`   | `/api/v1/spaces/{spaceId}/agents/{agentId}/unpublish` | [Unpublish an agent](/api-reference/agents/unpublish-an-agent) |
| `DELETE` | `/api/v1/spaces/{spaceId}/agents/{agentId}`           | [Delete an agent](/api-reference/agents/delete-an-agent)       |

### Related

| Method | Endpoint                          | Description                                                                                         |
| ------ | --------------------------------- | --------------------------------------------------------------------------------------------------- |
| `POST` | `/api/v1/openai/chat/completions` | [Chat with an agent](/api-reference/completion-api/openai-chat-completion) via the `agentId` option |
| `GET`  | `/api/ai/models`                  | [List available models](/api-reference/ai/list-all-ai-models)                                       |

## Pagination

[List agents](/api-reference/agents/list-agents) is paginated. Control the page with two optional query parameters:

| Parameter | Type    | Description                                                           |
| --------- | ------- | --------------------------------------------------------------------- |
| `limit`   | integer | Maximum number of agents to return (1–100). Defaults to `50`.         |
| `offset`  | integer | Number of agents to skip from the start of the list. Defaults to `0`. |

The response is an envelope: the agents are in `data`, alongside pagination metadata.

```json theme={null}
{
  "data": [ { "id": "…", "name": "Support Agent", "published": true } ],
  "total": 128,
  "limit": 50,
  "offset": 0,
  "hasMore": true
}
```

Page through the full list by increasing `offset` by `limit` until `hasMore` is `false`:

```bash theme={null}
curl "https://{customer-tenant}.nuwacom.ai/api/v1/spaces/YOUR_SPACE_ID/agents?limit=50&offset=50" \
  -H "Authorization: Bearer $NUWACOM_API_KEY"
```

## Chat with an agent

To chat with an agent, use the OpenAI-compatible [Completion API](/api-reference/completion-api/openai-chat-completion) and pass the agent's ID as `agentId`. The agent's full configuration (system prompt, knowledge sources, model options) is applied automatically:

```bash theme={null}
curl https://{customer-tenant}.nuwacom.ai/api/v1/openai/chat/completions \
  -H "Authorization: Bearer $NUWACOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "space_id": "YOUR_SPACE_ID",
    "agentId": "YOUR_AGENT_ID",
    "model": "azure-gpt-4o",
    "messages": [
      { "role": "user", "content": "Hello!" }
    ]
  }'
```

The `model` field is required on the Completion API and acts as a fallback; when the agent has a `model` configured, the agent's model wins.

By default, the **published** version of the agent is used. To chat with an agent that only exists as a draft (for example right after creating it via the API), additionally pass `"agentPublished": false`.

## Example: create an agent

```bash theme={null}
curl -X POST https://{customer-tenant}.nuwacom.ai/api/v1/spaces/YOUR_SPACE_ID/agents \
  -H "Authorization: Bearer $NUWACOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent",
    "description": "Answers customer support questions",
    "systemInstruction": "You are a friendly support agent. Answer concisely.",
    "conversationStarters": [
      { "text": "What can you help me with?" }
    ],
    "model": "azure-gpt-4o",
    "temperature": 0.3,
    "attachmentIds": ["YOUR_ASSET_ID_AFTER_UPLOAD"]
  }'
```

Upload files first via [Upload an asset](/api-reference/assets/upload-an-asset), then pass the returned `id` in `attachmentIds`. Use `folderIds` or `contentIds` for knowledge folders and nuwacom documents.

The available model IDs for `model` can be retrieved via [List available models](/api-reference/ai/list-all-ai-models).

The response contains the new agent's `id` along with all its settings. The agent starts as an unpublished draft (`published: false`); use [Publish an agent](/api-reference/agents/publish-an-agent) to make it the live version.

## Actions

Actions are the tools an agent may call while chatting — built-in nuwacom tools (like web search or knowledge retrieval), an [MCP](https://modelcontextprotocol.io) server's tools, or actions from a connected integration (Gmail, Outlook, …). Configure them via the `actions` array on [Create](/api-reference/agents/create-an-agent) and [Update](/api-reference/agents/update-an-agent).

Each action has the following fields:

| Field                  | Type    | Description                                                                                                                                                                           |
| ---------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `integration`          | string  | Provider the action belongs to: `"nuwacom"` for built-in tools, `"MCP"` for an MCP server, or a connected integration type (e.g. `"gmail"`).                                          |
| `key`                  | string  | Action key within the integration. For `nuwacom`, one of the built-in keys listed below; for an integration or MCP server, the exact tool key it exposes (e.g. `"GMAIL_SEND_EMAIL"`). |
| `requiresConfirmation` | boolean | Whether the user must confirm before the action runs. Defaults to `false`.                                                                                                            |
| `defaultValues`        | object  | Preset parameter values applied whenever the action runs. Defaults to `{}`.                                                                                                           |
| `integrationId`        | string  | ID of the specific connected integration instance to use (for provider integrations). Optional.                                                                                       |
| `mcpClientId`          | string  | ID of the MCP client that exposes this action. Required for `"MCP"` actions.                                                                                                          |

### Built-in nuwacom action keys

When `integration` is `"nuwacom"`, `key` must be one of the app-supported built-in tools:

| `key`                          | Description                                  |
| ------------------------------ | -------------------------------------------- |
| `WEB_SEARCH`                   | Search the web.                              |
| `RETRIEVE_FROM_KNOWLEDGE_BASE` | Retrieve from the agent's knowledge sources. |
| `DISPLAY_DOCUMENT`             | Render a document in the chat.               |
| `DISPLAY_SLIDES`               | Render slides in the chat.                   |
| `DISPLAY_EMAIL`                | Render an email draft in the chat.           |
| `IMAGE_GENERATION`             | Generate images.                             |
| `VIDEO_GENERATION`             | Generate videos.                             |

<Warning>
  Only the keys above are valid for `nuwacom` actions. Other internal nuwacom keys (e.g. `RETRIEVE_FROM_CONTENT`) are not configurable via the API — sending one is accepted by the API but is not a user-facing tool and will not render correctly in the app. For integration or MCP actions, use the exact key exposed by that provider/server.
</Warning>

<Note>
  On update, the `actions` array **fully replaces** the agent's current draft actions. Send the complete desired set, or `[]` to remove all of them. Omitting `actions` leaves them unchanged. Like other changes, action edits apply to the draft — [publish](/api-reference/agents/publish-an-agent) the agent to make them take effect for the Completion API.
</Note>

```bash theme={null}
curl -X POST https://{customer-tenant}.nuwacom.ai/api/v1/spaces/YOUR_SPACE_ID/agents \
  -H "Authorization: Bearer $NUWACOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Research Agent",
    "systemInstruction": "You research topics using web search.",
    "actions": [
      { "integration": "nuwacom", "key": "WEB_SEARCH" },
      { "integration": "nuwacom", "key": "RETRIEVE_FROM_KNOWLEDGE_BASE", "requiresConfirmation": true }
    ]
  }'
```

## Availability: app and external embed

Where an agent can be used is controlled by two independent switches, both configurable on [Create](/api-reference/agents/create-an-agent) and [Update](/api-reference/agents/update-an-agent):

| Field          | Type    | Description                                                                                                                  |
| -------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `appEnabled`   | boolean | Whether the agent is available inside the nuwacom app. Defaults to `true`.                                                   |
| `embedEnabled` | boolean | Whether the agent is published as an external, embeddable chat widget. Defaults to `false`.                                  |
| `embedOptions` | object  | External embed widget configuration (see below). On update the provided object **fully replaces** the current embed options. |
| `embedId`      | string  | Read-only identifier used to embed the agent as an external widget. Returned in responses.                                   |

`embedOptions` supports the following keys:

| Field             | Type               | Description                                                                                                              |
| ----------------- | ------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| `domainWhitelist` | string\[]          | Origins allowed to load the embed widget (e.g. `"https://www.example.com"`). Required to publish an embed-enabled agent. |
| `showSources`     | boolean            | Whether the widget shows source citations.                                                                               |
| `allowFileUpload` | boolean            | Whether end users can upload files in the widget.                                                                        |
| `allowVoiceInput` | boolean            | Whether end users can use voice input in the widget.                                                                     |
| `themeMode`       | `"light"`/`"dark"` | Default color theme of the widget.                                                                                       |
| `lightTheme`      | object             | Light-theme colors (`backgroundColor`, `primaryColor` as HSVA objects).                                                  |
| `darkTheme`       | object             | Dark-theme colors (`backgroundColor`, `primaryColor` as HSVA objects).                                                   |

<Note>
  `appEnabled`, `embedEnabled`, and `embedOptions` are draft settings like everything else — [publish](/api-reference/agents/publish-an-agent) the agent to make them take effect. Publishing an agent with `embedEnabled: true` makes the external widget live and therefore requires a non-empty `embedOptions.domainWhitelist`; otherwise the publish request is rejected with `400`.
</Note>

```bash theme={null}
curl -X POST https://{customer-tenant}.nuwacom.ai/api/v1/spaces/YOUR_SPACE_ID/agents \
  -H "Authorization: Bearer $NUWACOM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Website Assistant",
    "systemInstruction": "You help visitors on our marketing site.",
    "appEnabled": false,
    "embedEnabled": true,
    "embedOptions": {
      "domainWhitelist": ["https://www.example.com"],
      "showSources": false,
      "themeMode": "light"
    }
  }'
```