Applications API
Applications, their environments, and allowed websites.
Review Assistant application before adding it to Employees
Review an Assistant application before adding it to Employees
Add existing Assistant application to Employees
Adds an employee profile in place. Preserves the application ID, agents, knowledge, settings, permissions and published state. Requires write access. Select a primary agent when several exist. Repeated requests preserve an existing employee profile.
Discover safe environment references for application setup
Lists environment IDs, names, and variable names only. Use this for CLI and MCP discovery before requesting secrets or selecting a flow environment. Secret values are never returned, including for administrators. Requires application read access.
Request user setup
Returns a structured awaiting-user-input handoff for MCP, website, upload, or environment setup. This does not save settings or open a remote browser. Clients render a local form or direct the user to settingsPath. Complete setup through the existing application MCP, allowed-websites, environments, or document upload APIs, then resume the conversation with a non-secret completion message. Never send secret values in reason or variableNames. Requires application write access.
List shared employee and application categories
Returns 20 industry defaults, company-specific names and icons, and custom categories. Stable keys are accepted as categoryKey when creating or updating employees and applications.
Create shared category
Company administrators can create a named category with an icon for use in Employees and Applications. Names must be unique within the company. Returns the stable key to use as categoryKey.
Rename category or change its icon
Company administrators can customize a default or custom category. Its key and existing employee and application assignments remain unchanged. Changes apply throughout this company.
Export application or employee
Exports application instructions, employee identity, agent drafts, expectations, paused routine definitions and document templates. Knowledge and connections are descriptive references only. No binaries, credentials, memberships, conversation history or execution logs. Requires application write access. Review authored prompt and test content before sharing.
Import application or employee
Creates a new private application from exportApplication output. Employee identity is restored when present. Agents remain unpublished; routines and evaluation schedules are paused. Collection/file/connector/MCP/website/skill/channel references are saved in a reconnection checklist, never automatically linked. Creates no external resources. Requires application creation permission.
Read application import checklist
Read an application import checklist
List applications
Returns only applications the caller can access through ownership, direct membership, or team membership. Non-admin callers always get `ACTIVE` applications, admins can request `ARCHIVED` via `status`. All filters combine with AND. Pass `responseShape=summary` for a lean, cursor-paginated envelope (stable identity fields only) instead of the default full array; use `limit` and `cursor` to page through it.
Create application
Creates the application owned by the caller and adds the caller as an active `ADMIN` member. Requires company-level permission to write applications.
Get application
Returns one application in the same item shape as the `GET /api/applications/` list. Its own settings (the ones `PATCH` writes, such as `maxConcurrentExecutions` and the persona) are under `metadata.settings`; company defaults it inherits are not.
Update application
Updates one or more of the application name, description, group and settings. `settings` takes every application-level setting: capability toggles (`codeExecutionEnabled`, `skillsEnabled`, ...), model pins (`agentDefaultModel`, `assistantModel`, ...), attachment, document template and retrieval knobs, the concurrent-execution limit (`maxConcurrentExecutions`), whether the assistant answers only from the application knowledge (`assistantKnowledgeOnly`), and the persona and tone of voice (`persona`: a preset, six voice trait levels, and free-text voice notes; `null` or the `neutral` preset clears it). On the other settings `null` removes the application value so the company value applies again. Omitted fields are preserved. Settings read back from `metadata.settings`. Requires write access. `maxConcurrentExecutions` and the model pins (`agentDefaultModel`, `agentLiteModel`, `agentProModel`, `assistantModel`, `documentTemplateModelName`, `evaluationModel`, `smartAssertionModel`, `retrievalRerankModel`) are super admin only: from anyone else a body that sets or clears one is rejected whole with 403 `settings/super-admin-only`, `details.keys` naming them, and nothing is written.
Link collection to application
Grants the application access to the collection, so its agents can search and read the documents inside. The caller needs write access to the application and access to the collection.
Set file sharing for linked collection
Controls whether the application's assistant may send the collection's documents to end users as files. File sharing is off by default and the collection must already be linked to the application. An application's own collection is rejected: its documents are always shareable. The caller needs write access to the application and access to the collection.
Unlink collection from application
Removes the application's access to the collection. The collection and its documents stay untouched. A collection owned by the application itself cannot be unlinked.
List who can access application
Lists the people with direct access (owner first) and the teams that have access, each with its role. Channel guests, such as WhatsApp or SMS contacts, are counted, not listed. Requires read access.
Give person access to application
Adds a person from the caller’s company as a direct member, found by `person`: their email, or their name or part of it. A name that matches several people fails with 409 listing their names and emails, so the caller can ask which one. Someone who already has access, the owner included, is left unchanged (`added: false`); a deactivated membership or a channel contact’s guest access becomes a real one. People outside the company must be invited to it first. Requires write access to the application, as on its members page; the person receives an email saying they were added.
Remove person’s access to application
Removes a direct member found with listApplicationMembers. The owner cannot be removed, and access through a team stays until the team is removed on the members page. Requires write access; the person receives an email saying they were removed.
List selectable application skills
Lists the skills the company allows, each with its selection state for this application.
Select skill
Makes the skill available to the application's agents.
Deselect skill
Removes the skill from the application's agents.
List MCP servers selectable by application
Lists the MCP server connections in the workspace, each with its selection state for this application.
Enable MCP server
Lets the application's agents call the MCP server's tools.
Disable MCP server
Stops the application's agents from calling the MCP server's tools.
List environments
Environments are named sets of key-value variables that agents resolve through `{{env.*}}` placeholders at run time. API and MCP responses contain variable names with every value masked, including for application owners. Use an authorized sandbox connection to access a service without exposing its credentials.
Create environment
Environment names are unique per application, compared case-insensitively. Variables are encrypted before storage. Requires write access to the application.
Update application environment (deprecated shape)
Deprecated: use `PUT /api/v1/applications/{id}/environments/{environmentId}/`, which addresses the environment in the path instead of the `environmentId` body field. This variant behaves identically. Provide `name`, `variables`, or both. A provided `variables` map replaces every existing variable.
Delete application environment (deprecated shape)
Deprecated: use `DELETE /api/v1/applications/{id}/environments/{environmentId}/`, which addresses the environment in the path instead of a required request body — a shape several HTTP clients cannot send. This variant behaves identically. Agents that still reference the deleted environment resolve their `{{env.*}}` placeholders to empty values.
Update environment
Provide `name`, `variables`, or both. A provided `variables` map replaces every existing variable. Requires write access to the application.
Delete environment
Agents that still reference the deleted environment resolve their `{{env.*}}` placeholders to empty values. Requires write access to the application.
List service connections for application environment
Returns connection metadata without credentials. Select authorized connection IDs with the sandbox bash, Python, or JavaScript tools. Connection use requires a separate permission for the current user and agent. Manage connections in application environment settings.
List application's message templates
Returns registered generic text and WhatsApp templates for this application. `templateType` describes content; `channel` is `any` for generic text and `whatsapp` for WhatsApp definitions. Text placeholders are derived from variables and if/unless conditions in the template AST; WhatsApp also includes rendered preview tokens.
Register message template
Accepts a generic text definition `{ type: 'text', name, language: { code: 'pt_BR' }, text: '{{report}}' }` with unrestricted channel `any`, or an existing WhatsApp send payload/bare template with channel `whatsapp`. Generic text supports simple variables and if/unless blocks and renders values literally. A definition that could only ever produce nothing is refused; at send time an empty render publishes nothing and a render past the 256 KiB output cap is truncated. The serialized definition is limited to 65536 bytes. `name` and `language` come from the definition. Re-registering the same application/channel/name replaces and re-enables it. Enabled names duplicated across channels fail explicitly when sent. Requires write access to the application.
Enable or disable message template
Flips whether the template can be used to send messages, without touching its stored definition. Requires write access to the application.
Delete message template
Permanently removes the template definition from the send-side catalog. Requires write access to the application.
List allowed websites
Merges the company-level website records with the per-application link, so each row carries the global configuration plus an `enabledForApplication` toggle. Stored passwords are reported through `hasStoredPassword` and the ciphertext is never returned.
Create allowed website
Creates a company-level allowed website and links it to the application in one call. A plain-text `password` is encrypted before storage. Use `PATCH /api/v1/applications/{id}/allowed-websites/{siteId}/` to toggle the per-application link later.
Get allowed website
The response replaces stored credentials with a `hasStoredPassword` boolean. The password ciphertext is never returned.
Update allowed website
Most fields update the company-level record shared by every application, while `enabledForApplication` toggles only the link to this application. `password: null` clears the stored credentials, omitting the field keeps them.
Delete allowed website
Deletes the company-level record, which removes the website from every application it is linked to, not just the one in the path.
List threads
`limit` is clamped to 100. `threadGroupId` switches to a compact playground-history shape. `format=preview` strips full message content down to a display preview. The serving model (`metadata.modelProviderId`) is omitted unless the caller is a platform super admin.
Reset browser context
Discards the stored persistent browser context id, the shared browser profile that carries cookies and auth tokens across `ADVANCED` browser runs, so the next run mints a fresh context and logs in from scratch. Use it when cookies persisted by a failed or expired login break subsequent logins. Idempotent, requires write access to the application.
List pending OAuth connections
Checks the OAuth MCP servers enabled on the application and returns the ones that block the assistant for the calling user, that is servers with a `not_connected` or `expired` connection. Each entry carries a `settingsPath` pointing to the page where the connection can be completed. Connected and expiring-soon servers are excluded.