Employees from code

Create and prepare an employee from your own system, then continue the same work in the Docana UI. An employee is an Assistant application with a goal, portrait, category, and persona. The application holds its agents, collections, website access, channels, and other settings. One agent usually does the work. An employee can also contain several cooperating agents.

The employee UI and the public interfaces share the same creation, preparation, knowledge, and credential services. You can use the preparation assistant from Claude, ChatGPT, or the CLI, or build the underlying agents directly with the existing APIs. The employee's ID is its application ID. The application carries an explicit employee profile. Existing Assistant applications without that profile remain regular applications.

For the same workflow in the product, see the employee walkthrough with screenshots. The Applications guide shows how an employee connects to its underlying workspace.

Employee creation enables skillsEnabled and codeExecutionEnabled in application settings. Generated files remain excluded from retrieval by default (codeExecutionOutputRetrievable: false). Drafts authored through preparation receive common PDF/chart instructions, including real output files, source checks, and download links. Existing employees can enable these capabilities through application settings or preparation.

Create and prepare

Sign in with docana login, or set DOCANA_API_URL and a Full access DOCANA_API_KEY together. Run docana whoami to confirm the deployment before writing. REST requests use Authorization: ApiKey <key>; MCP also supports browser sign-in. Every operation checks the caller's existing application access. Preparing an employee and changing its settings require write permission.

To use the same role templates as the UI, run:

docana employees templates --locale en-US

The catalog returns 20 entries with an id, title, description, and an employee object containing name, job, group, avatar, and personaPreset. Choose an entry, customize its employee object, and save that object as employee.json for the existing create command. Keep the full employee.job instructions and append your team’s requirements to that string. The UI does the same when someone selects a role and adds context in the text area; there is no separate template ID required by the create API. pt-BR returns Portuguese text. MCP clients call listEmployeeTemplates with query: { "locale": "en-US" }, then pass the chosen employee fields as the body of createEmployee. Listing templates is read-only. Creation and preparation remain separate operations.

Save an employee definition as employee.json:

{
  "name": "Robin",
  "avatar": "sage",
  "group": "FINANCE",
  "personaPreset": "neutral",
  "job": "Compare supplier invoices with purchase orders, flag discrepancies, and prepare a weekly report with verified totals."
}

docana employees create employee.json
# Returns { "success": true, "applicationId": 42 }

docana employees prepare 42 "Create the draft, define expectations for missing and conflicting data, and measure discrepancies and human handoffs."
# Returns { "threadId": "...", "text": "...", "tools": [...] }

docana employees prepare 42 "Also check that the report totals match the source invoices." --thread <thread-id>

Creation saves the employee identity and owner membership. Preparation builds drafts, connects available capabilities, defines evaluation scenarios, and configures performance measures. It uses the same scoped tools and saved conversation as the UI. The assistant considers source verification, conversation history, document and chart deliverables, bounded follow-ups, and requested routines when relevant to the job. Inspect its results and run representative tests; a generated plan does not prove the employee can do the job.

listEmployees separates a selected draft needing publication (needsPublication: true) from a published, enabled agent available for chat (chatAgentId). Neither field certifies that tests passed. Review & publish opens the draft for review without changing it. Publish the selected agent through the existing agent publication endpoint after reviewing its workflow and tests.

Preparation does not publish agents. Publish through the existing agent controls after reviewing the draft and test results. Scheduled work remains paused for unpublished agents.

The JSON preparation call can take several minutes. Continue with its returned threadId to preserve context. After a timeout or interruption, inspect employee status and preparation history before repeating a write: the turn may have completed some operations. The initial turn is bounded to 24 model steps and is not a durable background job.

Prepare from files or a voice brief

Attach an existing job description or recording to the same preparation command:

docana employees prepare 42 "Use this brief to prepare a draft and ask about missing requirements." \
  --attach ./job-description.pdf \
  --attach ./voice-brief.webm

--attach is repeatable. Preparation accepts up to 10 files with a combined decoded size of 20 MB. The CLI reads local files and sends base64 data URLs. REST and MCP callers supply attachments alongside prompt:

{
  "prompt": "Summarize this job brief and ask what is missing.",
  "attachments": [
    {
      "name": "brief.txt",
      "contentType": "text/plain",
      "url": "data:text/plain;base64,UmV2aWV3IGludm9pY2VzLg=="
    }
  ]
}

The file above contains “Review invoices.” Remote URLs are not accepted by this brief field. Supported content follows the existing chat attachment pipeline. Files and audio stay with the saved preparation conversation. For lasting searchable sources, use collection uploads and connectors. Incomplete attachment ingestion stops preparation so it cannot silently build from a partial brief.

The reply includes attachmentCount, the number of incoming attachments confirmed saved with that message. Check it against the number you sent before treating the brief as delivered. The creation form makes this check before opening the saved conversation.

The UI and code share the employee definition and preparation conversation.

REST, MCP, and CLI operations

Paths below are relative to /api/v1/employees/. MCP names match the documented operation IDs. MCP JSON bodies are nested in a body argument, alongside path parameters such as id.

Action	REST	MCP tool	CLI
List role templates	GET /templates/?locale=en-US	listEmployeeTemplates	employees templates --locale en-US
List employees	GET /	listEmployees	employees list --limit 25 --cursor <id>
Create employee	POST /	createEmployee	employees create <file>
Read identity and goal	GET /{id}/	getEmployee	employees get <id>
Browse knowledge files	GET /{id}/knowledge/?limit=50&search=policy	listEmployeeKnowledgeFiles	employees files <id> --search policy
Change portrait or category	PATCH /{id}/	updateEmployeeIdentity	employees identity <id> <file>
Prepare from a message	POST /{id}/prepare-message/	askEmployeePreparation	employees prepare <id> <prompt> --thread <id>
Resolve knowledge collection	POST /{id}/knowledge/	prepareEmployeeKnowledge	employees knowledge <id>
List enabled test scenarios	GET /{id}/expectations/	listEmployeeExpectations	employees expectations <id>
Read tests, sources, and work	GET /{id}/status/	getEmployeePreparationStatus	employees status <id>
Read performance measures	GET /{id}/performance/	getEmployeePerformance	employees performance <id>
Read website access	GET /{id}/websites/	getEmployeeWebsites	employees websites <id>
Save a website login	PATCH /{id}/websites/{siteId}/login/	updateEmployeeWebsiteLogin	employees login <id> <siteId> --file <file>

For example, an MCP preparation invocation has this input:

{
  "id": 42,
  "body": {
    "prompt": "Inspect the current draft and explain which expectations still need tests.",
    "threadId": "your-preparation-thread-id"
  }
}

The UI consumes POST /api/v1/employees/{id}/prepare/, which streams AI SDK UI messages. Its non-streaming counterpart, askEmployeePreparation, returns the conversation ID, answer text, and tool completion states. It omits internal reasoning and tool payloads. Both use one preparation engine.

listEmployees returns up to 50 visible employees per page with a nextCursor. Pagination is applied in the database before loading agents. Portrait IDs are sage, iris, sunny, coral, bruno (Bruno Admin), hazel (Ellie), john, philip, hiro, henry, peter, mike, ana, marcellus, and timon. Categories use company-scoped stable keys. List them with docana categories list, then pass categoryKey when creating or editing an employee. The legacy group field remains supported for existing integrations. To discover persona presets and all field constraints, run docana api schema search employees or read the API reference. Persona settings remain available through applications persona and the existing application settings APIs.

Add substantial knowledge

Resolve the employee's collection, then use existing document ingestion or source connectors:

docana employees knowledge 42
# Returns collection.id, collection.name, and collection.libraryId

docana documents push <collection-id> ./policies/*.pdf
docana connections connect GoogleDrive
docana collections link <collection-id> -c <connection-id> -f <folder-id> -n "Company policies"
docana collections sync <collection-id>

The UI accepts up to 1,000 knowledge files per batch and queues three transfers at a time. Drop a folder or select Choose folder to retain its root folder and nested file paths in the employee’s collection. Knowledge’s collection upload dialog and drop targets use the same folder resolution. Matching manual folders are reused; connector-synced folders stay separate. Empty directories contain no documents and are omitted. These files go into a collection. Message attachments use the existing chat attachment pipeline. Upload completion and indexing completion are separate states; inspect collection documents before assuming a source is searchable. MCP clients use the existing upload tools or document ingestion protocol, including chunked uploads for larger files.

Test, measure, and connect

employees expectations lists enabled cases across the employee's agents. The UI's Test expectations button runs those cases through the existing test-case run API; use docana agents eval-case run --agent-id <agent-id> --case-id <case-id> for the same operation, then inspect each returned run. employees status summarizes observed test outcomes and recent execution activity. Its progress.executions contains up to five work runs from the last 30 days, excluding evaluation conversations. Each run includes durationMs (wall time from creation to the last update, including waits; null while running or when timestamps are invalid), nodeCount (recorded nodes, including nested steps), errorCount, and specArtifactVersion when available. These same fields are returned by REST and the getEmployeePreparationStatus MCP tool; execution IDs link to the existing agent execution APIs. It does not certify the current draft: changing a draft can make earlier test evidence stale.

employees performance returns per-agent Conversation Insights over the last 30 days, with bounded samples and explicit truncation flags. Evaluation conversations are excluded. Numeric measures report averages, booleans report the share recorded as true, and categories report the most common value. Unknown values remain empty. These are captured observations, not a universal employee score. Configure measures through agents insights, and inspect executions through agents runs or the existing execution UI.

Routines, channels, collections, skills, application persona, and MCP connections keep their existing public contracts. The preparation assistant can configure the capabilities in its scoped catalog; other controls link to the corresponding existing setup screens. A request to connect a provider may still require its browser sign-in.

Website access and credentials

Use the existing application allowed-website APIs, MCP tools, or docana app <id> allowed-websites commands to register a specific website with the advanced browser. The preparation assistant can also register the requested site. Saving access is separate from verifying a successful sign-in; MFA, CAPTCHA, or unavailable browser infrastructure can still block work.

For a caller-owned website linked exclusively to the employee, the secure login operation accepts username, password, persistContext, and clearCredentials. Supply credentials through a secure form or a private local JSON file, then run:

docana employees login 42 <website-id> --file /private/path/website-login.json

Passwords are encrypted before storage and never returned. An omitted or blank password preserves the saved password; clearCredentials: true removes both login fields. Persistent browser context is an explicit opt-in. The employee preparation assistant does not accept credential arguments through its own tools: enter them through the secure operation instead of ordinary chat. Shared websites require their existing advanced settings.

Contact an employee on WhatsApp

Open Add a channel → WhatsApp beneath the employee’s portrait. You can enable or pause the existing WhatsApp channel without leaving preparation. Once a number is assigned, the profile shows it and the dialog offers a QR code and a link to start a conversation. The QR code opens wa.me; it does not pair a personal WhatsApp account. Provider status shows whether setup still needs attention.

Twilio can assign a paid number through the configured provider account. The dialog explains this before you select Get number & enable. Meta and proxy configurations use their existing channel setup; connect the business number in advanced settings first. Disabling preserves the number, routing, privacy, voice settings, and credentials.

The UI and external assistants use the same operations:

Operation	REST	MCP
Read the number and status	GET /api/v1/employees/{id}/channels/whatsapp/	getEmployeeWhatsApp
Enable or pause WhatsApp	PATCH /api/v1/employees/{id}/channels/whatsapp/	updateEmployeeWhatsApp

Read the contact from the CLI:

docana employees whatsapp 12

Enable an existing connection with --enable, or pause it with --disable. To allow provisioning a paid Twilio number when none is assigned:

docana employees whatsapp 12 --enable --acknowledge-number-purchase

PATCH accepts enabled and optional acknowledgeNumberPurchase. Write access is required, credentials are never returned, and incomplete provider setup returns 409. Channel activation remains an explicit user action; the preparation assistant cannot enable channels on its own.

Follow a large upload

The preparation page keeps the batch count and progress bar visible. Select View uploads to open the same file cards used in Knowledge, with relative folder paths, file status, and progress. Large queues show 25 files per page and support searching by file or folder name. Closing the dialog keeps transfers running while you continue preparing the employee. Saved files still need background processing before they are ready for retrieval.

Shared categories

Employees and Applications use the same catalog. The following routes are relative to /api/v1/:

Action	REST	MCP	CLI
List categories	GET /application-categories/?locale=en-US	listApplicationCategories	docana categories list
Create a category	POST /application-categories/	createApplicationCategory	docana categories create category.json
Rename or change an icon	PATCH /application-categories/{key}/	updateApplicationCategory	docana categories update <key> category.json

For creation, category.json contains a name and an optional icon, for example { "name": "Customer success", "icon": "support" }. Updates accept either field. Names are normalized and unique within the company. Creation and editing require company administrator access. Listing also returns canManage for the caller. The icon choices are documented in the request schema.

Use the returned stable key as categoryKey in createEmployee, updateEmployeeIdentity, createApplication, or updateApplication. CLI users can pass --category <key> to docana apps create. A category rename or icon change applies to every existing assignment. Unknown or foreign-company keys are rejected. Updates that omit both category fields preserve the assignment. A legacy group update selects that group; an explicit categoryKey: null update returns to the supplied group or Default.

The Prisma rollout is additive: ApplicationCategory stores company names and icons, while nullable Application.categoryKey links assignments. Existing applications with no key resolve their legacy group. The existing database enum and group column remain during the rolling deployment for backward compatibility. Their eventual removal requires a later migration after deployed readers stop depending on them. Both schema and concurrent-index migrations include rollback scripts.

Knowledge coverage

employees status <id> and getEmployeePreparationStatus include knowledge: total files, ready, processing, failed, pages, filesWithPageCount, and a bounded types distribution. Counts are computed in the database across accessible connected source collections. Archived files, workflow artifacts, and temporary chat attachments are excluded. Page totals only include known positive page counts on completed files, so missing page metadata never becomes an invented count.

employees files <id> --limit 50 --cursor <next_cursor> --search policy browses the full source set. Results include file IDs, names, status, collection and library IDs, and an optional folder ID. Pagination uses decreasing document IDs and a nextCursor when more results exist. Search matches filenames without case sensitivity. File contents and private storage paths are not included.

MCP providers

Employee preparation reuses the existing MCP server APIs. List available providers with listApplicationMcpServers, create a private server with createMcpServer, and select it with enableApplicationMcpServer. getMcpServerConnectionById checks the current user's authentication; testMcpServerConnectionById checks tool discovery. Selection alone does not prove a working connection.

The CLI exposes the same operations under docana mcp-servers and docana app <id> mcp. Use --help for each command's arguments. The preparation assistant can register a credential-free or OAuth-discovery endpoint and enable it within the employee application. It cannot read or accept provider secrets. Complete OAuth consent or enter credentials through MCP connections in the preparation UI. Registration requires company administrator permission; existing application selection follows application write access.

Portable employee and application packages

Employees reuse the application transfer contract: docana.application, version 1. Standalone agent exports keep their existing format and endpoint. The application exporter calls the shared agent export utilities for inlined criteria, evaluations, routines, insights, and baseline mocks, then applies application-package cleanup.

docana employees export 42 --output robin.docana.json
docana employees import robin.docana.json --check
docana employees import robin.docana.json --name "Robin restored" --category FINANCE
docana employees import-report 43 --search policy --offset 0

# The same package and services for any application
docana applications export 42 --output application.docana.json
docana applications import application.docana.json --name "Restored application"

--check inspects the local file without a server mutation; the import API validates the full package. Export uses exclusive file creation and will not overwrite an existing output file. Packages are limited to 20 MB, 200 agents, 500 document templates, 500 recommendation definitions, and 100,000 source references.

REST operation	MCP tool
GET /api/v1/applications/{id}/export/	exportApplication
POST /api/v1/applications/import/	importApplication
GET /api/v1/applications/{id}/import-report/	getApplicationImportReport

Import accepts { package, name?, categoryKey? }. Export and checklist access require application write permission; import requires application creation permission and available quota. Import creates a new owner-admin membership and restores definitions in one transaction. It never copies source memberships, provider authentication, file binaries, conversations, or execution logs.

The dependency manifest contains metadata-only references. Internal agent and document-template IDs are remapped to newly created records. Recognized external resource IDs become unresolved placeholders, including IDs in serialized tool arguments. Reconnect resources and update references in the draft before testing and publishing. Unstructured IDs or secrets written inside authored prompts cannot be identified reliably; review instructions, examples, and template content before sharing.

The checklist is stored as an application-owned artifact. Its API returns up to 50 references by default, with totalCount, filteredCount, and nextOffset. Pass offset, limit (1 to 100), and search to inspect large manifests without returning every file to the client. Original references remain available if the restored application is exported again.

Add an existing Assistant application to Employees

Use this when you already have an application and want the employee preparation experience around it. Unlike package import, adoption keeps the existing ID and resources. It requires application write access and an active ASSISTANT application. Other application types are rejected.

docana employees application-setup 42 --limit 25

The response contains the application name and description, any existing employee profile, and a paginated list of eligible agents. Follow nextCursor with --cursor to see more agents. Choose the primary agent explicitly when there are several. A sole agent is selected automatically; an application without agents can be adopted and prepared afterward.

Save the reviewed identity in employee.json:

{
  "avatar": "sage",
  "job": "Review weekly supplier invoices, reconcile totals and flag missing evidence.",
  "primaryAgentId": "your-existing-agent-id"
}

docana employees adopt 42 employee.json

REST uses GET /api/v1/applications/42/employee/ for the preview and POST to the same path with the JSON body above. MCP exposes getApplicationEmployeeSetup and adoptApplicationAsEmployee. The result is { "success": true, "applicationId": 42 }.

Only the employee profile is added. Existing agents, publication, knowledge, connections, persona, members and routines remain intact. Adoption does not make an unpublished agent available for chat or activate paused work. Repeating it preserves an existing employee profile. If another edit changes the application during adoption, the API returns 409; refresh the preview before retrying.

Read recurring responsibilities

docana employees routines 42 --limit 25

GET /api/v1/employees/42/routines/ and the MCP tool listEmployeeRoutines return routines, total, nextCursor, and canWrite. Each routine includes its name, agent, enabled state, last run, and saved triggers. Scheduled triggers include the UTC cron expression and nextRunAt; disabled routines, disabled agents, disabled triggers, and triggers without a valid schedule have no next scheduled run. Document triggers retain their selected collection IDs; an empty list means the application's connected collections. API triggers describe on-demand work.

The directory's listEmployees response includes a responsibilities preview with a total and up to two routines per employee. Use the dedicated list endpoint for the rest. These fields describe saved configuration, not a guarantee that an external scheduler or a future execution will succeed. To edit, pause or enable a routine, use the existing routine APIs with its agentId and routine ID. Reading either endpoint starts no work.