--- title: "Create a new assistant" method: POST path: "/v0/assistant" tags: ["Assistant Management"] --- # Create a new assistant `POST /v0/assistant` Creates a new assistant for the authenticated user with the specified configuration. This action will deduct credits from the user account. ## Request body - AssistantCreate — Schema for creating a new assistant. - `first_name` string, nullable — First name of the assistant - `surname` string, nullable — Surname of the assistant - `age` integer, nullable — Age of the assistant - `weekly_limit` number, nullable — Weekly time limit for the assistant in hours - `max_parallel` integer, nullable — Maximum number of parallel tasks the assistant can handle - `nationality` string, nullable — Assistant's nationality - `profile_photo` string, nullable — URL to the assistant's profile photo - `profile_video` string, nullable — URL to the assistant's profile video - `desktop_mode` 'ubuntu' | 'windows' | 'macos', nullable — Desktop operating system mode for assistant's VM type - `user_desktop_id` integer, nullable — ID of the registered user desktop to assign to this assistant - `user_desktop_filesys_sync` boolean, nullable — Whether to enable filesystem sync with user's desktop - `about` string, nullable — Brief description about the assistant - `voice_id` string, nullable — Id of the provider voice to use for the assistant - `voice_provider` string, nullable — Provider of the selected voice (e.g., 'elevenlabs', 'openai') - `create_infra` boolean, nullable — Whether to create the infrastructure for the assistant (pubsub, VM, etc.) - `is_local` boolean, nullable — Whether this is a local assistant (runs unity locally instead of on GKE). Local assistants skip wakeup calls and GKE job management in the adapters. - `deploy_env` 'preview', nullable — Set to 'preview' to route this assistant to the preview runtime stack. Leave null for native assistants (routed to this Orchestra's own environment). - `pre_hire_chat` ChatMessage[], nullable — A list of chat messages from the pre-hire conversation to be logged. - `role` 'user' | 'assistant', required — The role of the message sender. - `msg` string, required — The content of the message. - `timezone` string, nullable — Timezone of the assistant in IANA format ## Response `200` Assistant created successfully - InfoResponseAssistantRead - `info` AssistantRead, required — Schema for reading assistant data, extends AssistantCreate with additional fields. - `first_name` string, nullable — First name of the assistant - `surname` string, nullable — Surname of the assistant - `age` integer, nullable — Age of the assistant - `weekly_limit` number, nullable — Weekly time limit for the assistant in hours - `max_parallel` integer, nullable — Maximum number of parallel tasks the assistant can handle - `nationality` string, nullable — Assistant's nationality - `profile_photo` string, nullable — URL to the assistant's profile photo - `profile_video` string, nullable — URL to the assistant's profile video - `desktop_mode` 'ubuntu' | 'windows' | 'macos', nullable — Desktop operating system mode for assistant's VM type - `user_desktop_id` integer, nullable — ID of the registered user desktop to assign to this assistant - `user_desktop_filesys_sync` boolean, nullable — Whether to enable filesystem sync with user's desktop - `about` string, nullable — Brief description about the assistant - `voice_id` string, nullable — Id of the provider voice to use for the assistant - `voice_provider` string, nullable — Provider of the selected voice (e.g., 'elevenlabs', 'openai') - `create_infra` boolean, nullable — Whether to create the infrastructure for the assistant (pubsub, VM, etc.) - `is_local` boolean, nullable — Whether this is a local assistant (runs unity locally instead of on GKE). - `deploy_env` 'preview', nullable — Set to 'preview' to route this assistant to the preview runtime stack. Leave null for native assistants (routed to this Orchestra's own environment). - `pre_hire_chat` ChatMessage[], nullable — A list of chat messages from the pre-hire conversation to be logged. - `role` 'user' | 'assistant', required — The role of the message sender. - `msg` string, required — The content of the message. - `timezone` string, nullable — Timezone of the assistant in IANA format - `user_desktop_url` string, nullable — Resolved URL of the assigned user desktop (from device registry) - `user_desktop_mode` string, nullable — Resolved OS of the assigned user desktop (from device registry) - `agent_id` string, required — Unique identifier for the assistant - `user_id` string, required — ID of the user who created/owns the assistant - `organization_id` integer, nullable — Organization ID if this is an organizational assistant, None for personal assistants - `created_at` string, date-time, required — Timestamp when the assistant was created - `updated_at` string, date-time, nullable — Timestamp when the assistant was last updated - `phone` string, nullable — Phone number of the assistant - `phone_country` string, nullable — Country code for the provisioned phone number - `email` string, nullable — Email address of the assistant - `user_phone` string, nullable — User's personal phone number (for call forwarding) - `user_whatsapp_number` string, nullable — User's WhatsApp number associated with the assistant - `assistant_whatsapp_number` string, nullable — WhatsApp number of the assistant - `api_key` string, nullable — API key associated with this assistant (personal or org key) - `user_first_name` string, nullable — First name of the user - `user_last_name` string, nullable — Last name of the user - `user_email` string, nullable — Email of the user - `user_image` string, nullable — Profile image URL of the user (owner/supervisor) - `monthly_spending_cap` number, nullable — Monthly spending limit in dollars for this assistant. - `demo_id` integer, nullable — ID of demo metadata if this is a demo assistant, None for regular assistants. - `desktop_filesync_sshkey` string, nullable — SSH private key for desktop filesystem sync. Only returned via admin endpoints. - `team_ids` integer[] — Team IDs the assistant's user belongs to within the assistant's organization. Empty for personal assistants or when the user has no team memberships. ## Other responses - `402` — Insufficient credits - `422` — Validation Error --- [API](https://skmtc.net/unify/apis/unifyai-http-api-reference.md) · [All operations](https://skmtc.net/unify/apis/unifyai-http-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/unify/unifyai-http-api-reference/versions/900377f918b6/schema)