Build an employee through the API

Turn a job description into an employee your team can prepare, test, and chat with. The employee endpoints use the same services as the Employees screen. A draft created from your backend or an MCP client appears in the product with its goal, portrait, knowledge, and preparation history.

For example, create Robin to review supplier invoices. Attach the job brief, connect the purchasing policy, prepare the workflow, and try invoices with missing or conflicting information. Review those results before publishing Robin for chat.

A role, written goal, file, or voice brief starts the same preparation journey.

One employee, one application

An employee is an Assistant application with an employee profile. The employee ID is the application ID. Its agents, collections, persona, MCP providers, channels, and memberships use the existing application services. Creating an employee does not create a second copy of those resources.

Existing Assistant applications without an employee profile remain regular applications. See how employees connect to applications for the product view.

Follow the lifecycle

Use a Full access API key with the caller's application permissions. All paths below start with /api/v1/. MCP tools use the same operation names and nest request fields in body.

Stage	Operation	What to inspect
Choose a starting role	List templates	20 editable role definitions, with English and Portuguese catalogs.
Save the employee	Create employee	The returned applicationId identifies both the employee and its application.
Prepare the job	Ask employee preparation	Send a prompt and optional file or voice attachments. Continue with the returned threadId.
Add source knowledge	Resolve knowledge collection	Use the returned collection with document ingestion or a source connector.
Inspect the tests and work	Read preparation status	Recorded outcomes, knowledge coverage, and recent executions.
Make the reviewed draft available	Publish agent	Publication is explicit. Preparation does not publish or activate channels.
Follow actual results	Read performance	Goal-specific measures from analyzed conversations.

listEmployees includes needsPublication for a selected unpublished draft and chatAgentId for an enabled, published agent. Test outcomes remain separate. A published employee can be available for chat even when its latest tests need attention.

Status connects the employee overview to the underlying execution records.

Keep integrations consistent

Preparation uses the caller's permissions and saves its conversation. It can take several minutes. If a request times out, inspect the employee and preparation history before repeating a write. Some operations may already have completed.

Employees share application categories and the application export/import package. Export includes definitions and a manifest of original connections. Credentials, source file binaries, memberships, conversations, and execution history stay in the source workspace. Import creates a new unpublished application with schedules paused. Reconnect its sources and test it before publishing.

Use Employees from Code for complete REST, MCP, and CLI examples, including file briefs, categories, website access, WhatsApp, knowledge pagination, and transfer packages. Use the visual employee walkthrough to see what your users will experience, or browse the generated endpoint reference for field-level contracts.

Reuse an existing application

An existing Assistant can become an employee without export/import. Preview its identity and primary-agent choices with Get application employee setup, then call Adopt application as employee with a portrait, goal and primary agent when needed. Both operations use /api/v1/applications/{id}/employee/ and require application write access.

The operation adds the employee profile to the same application. It preserves knowledge, permissions, agent definitions, published versions and routines. It neither publishes a draft nor activates paused work. Repeated requests preserve an existing employee profile. See the adoption examples for REST, CLI and MCP usage.

Inspect recurring work

List employee routines returns saved responsibilities across the employee application's custom agents. It includes paused routines, trigger state, UTC schedules, next scheduled times and last-run timestamps, with cursor pagination. listEmployees includes a compact responsibilities preview with up to two routines and the total count.

Use the existing routine APIs to change schedules or enable work. Publishing for chat does not activate paused routines. A saved schedule describes the intended recurrence; it does not certify that a future run will finish successfully.