Agents API Overview - nuwacom Documentation

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 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
`POST`	`/api/v1/spaces/{spaceId}/agents`	Create a new agent
`GET`	`/api/v1/spaces/{spaceId}/agents/{agentId}`	Get agent details
`PATCH`	`/api/v1/spaces/{spaceId}/agents/{agentId}`	Update an agent
`POST`	`/api/v1/spaces/{spaceId}/agents/{agentId}/publish`	Publish an agent
`POST`	`/api/v1/spaces/{spaceId}/agents/{agentId}/unpublish`	Unpublish an agent
`DELETE`	`/api/v1/spaces/{spaceId}/agents/{agentId}`	Delete an agent

Method	Endpoint	Description
`POST`	`/api/v1/openai/chat/completions`	Chat with an agent via the `agentId` option
`GET`	`/api/ai/models`	List available models

Pagination

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.

{
  "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:

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 and pass the agent’s ID as agentId. The agent’s full configuration (system prompt, knowledge sources, model options) is applied automatically:

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

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, 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. 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 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 server’s tools, or actions from a connected integration (Gmail, Outlook, …). Configure them via the actions array on Create and Update. 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.

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.

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 the agent to make them take effect for the Completion API.

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 and Update:

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).

appEnabled, embedEnabled, and embedOptions are draft settings like everything else — publish 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.

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"
    }
  }'

​Before you start

​Base URL

​Available endpoints

​Agents

​Related

​Pagination

​Chat with an agent

​Example: create an agent

​Actions

​Built-in nuwacom action keys

​Availability: app and external embed

Before you start

Base URL

Available endpoints

Agents

Related

Pagination

Chat with an agent

Example: create an agent

Actions

Built-in nuwacom action keys

Availability: app and external embed