Employees API
Create and prepare employees from job descriptions, files, or voice briefs. Employees are Assistant applications with an employee profile and shared knowledge, agents, permissions, and channels. Review tests before publishing the selected agent. See the Employee API overview for the lifecycle and visual walkthrough for screenshots.
List employee’s recurring responsibilities
Reads saved routines across the employee application’s active custom agents, including paused routines and disabled triggers. Schedules and next-run timestamps are UTC. Does not activate or run anything.
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.
List employee role templates
Returns 20 editable starting points with a detailed goal, suggested name, portrait, category and persona. Pass the selected employee object to createEmployee. Listing or choosing a template does not create or publish resources.
Read employee WhatsApp contact
Read employee WhatsApp contact
Enable or disable employee WhatsApp
Requires employee write access. Enabling requires a published employee and routes WhatsApp to its primary agent. New channels default to public access; isPublic=false limits access to application members. Omit isPublic to preserve a saved choice. Voice and credentials are preserved. Enabling Twilio without a number provisions a paid number and requires acknowledgeNumberPurchase=true. Meta and proxy connections require their existing provider setup. Disabling pauses the channel without releasing its number. The returned number can be used to generate a wa.me QR code; this is not account pairing.
List employees
List employees
Create employee
Creates the employee application, category, portrait, persona and owner membership. Does not create agents or publish them. Use askEmployeePreparation to build from the goal, or the existing agent APIs to author directly.
Get employee
Get an employee
Update employee portrait or category
Updates the employee identity while preserving its goal and primary agent. Sending avatar replaces the photo of an existing Twilio WhatsApp sender, custom logos included, and re-sending the current portrait repairs a stale photo. Category-only updates keep the photo. Meta/proxy profile pictures are preserved. A failed provider update fails the save so it can be retried.
Browse employee knowledge files
Returns a cursor page of accessible connected source files, newest first. Excludes archived files, workflow artifacts and temporary chat attachments. Search matches filenames. Use the employee status operation for full counts, known pages and file-type distribution.
Prepare employee knowledge collection
Returns the employee collection, creating it only when needed. Upload files with the existing collection document/upload APIs or CLI docs upload --collection, and configure existing source connectors using libraryId and collection.id.
List enabled employee expectations
Lists scenarios across all nondeleted employee agents. Run each with runAgentTestCase and inspect getAgentTestRun. This read does not execute tests or external actions.
Stream employee preparation
AI SDK UI-message event stream. Supply the latest user message and optionally a caller-owned preparation thread. Uses the same engine and scoped tools as askEmployeePreparation, the JSON alternative for CLI and MCP clients. Writes drafts and can run authorized tests; publishes only after explicit user approval. An interrupted write may have succeeded: inspect current state before retrying.
Prepare employee from message
Uses the same employee preparation assistant as the UI. Send a goal or correction; optionally continue a caller-owned preparation thread. Can write drafts, configure connections and run authorized tests. Publishes only after explicit user approval. May take several minutes. With Prefer: respond-async, returns 202 once the brief is saved; the response continues in the returned preparation thread. After a timeout or interrupted write, inspect employee status and thread history before retrying. Enter website credentials through the dedicated login operation or secure form, not the prompt.
Read employee preparation evidence
Read employee preparation evidence
Read employee performance measures
Read employee performance measures
Read employee website access
Read employee website access
Save employee website login
Saves encrypted credentials for a caller-owned website linked exclusively to this employee. Omitted or empty password preserves the stored password; clearCredentials removes both login fields. Response never includes credentials. Use a secure local input file or a client credential form; do not paste passwords into ordinary chat history.