v1

latestOpenAPI 3.1.02026-07-13154170539.0 KB

Assistant Management

Create a new assistant

Creates a new assistant for the authenticated user with the specified configuration. This action will deduct credits from the user account.

post/v0/assistant

Request body

first_namestring nullable

First name of the assistant

surnamestring nullable

Surname of the assistant

ageinteger nullable

Age of the assistant

weekly_limitnumber nullable

Weekly time limit for the assistant in hours

max_parallelinteger nullable

Maximum number of parallel tasks the assistant can handle

nationalitystring nullable

Assistant's nationality

profile_photostring nullable

URL to the assistant's profile photo

profile_videostring 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_idinteger nullable

ID of the registered user desktop to assign to this assistant

user_desktop_filesys_syncboolean nullable

Whether to enable filesystem sync with user's desktop

aboutstring nullable

Brief description about the assistant

voice_idstring nullable

Id of the provider voice to use for the assistant

voice_providerstring nullable

Provider of the selected voice (e.g., 'elevenlabs', 'openai')

create_infraboolean nullable

Whether to create the infrastructure for the assistant (pubsub, VM, etc.)

is_localboolean 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).

timezonestring nullable

Timezone of the assistant in IANA format

Example request

{
  "first_name": "Ada",
  "surname": "Lovelace",
  "age": 28,
  "weekly_limit": 15.75,
  "max_parallel": 2,
  "nationality": "North America",
  "profile_photo": "https://example.com/photos/ada.jpg",
  "profile_video": "https://example.com/videos/ada.mp4",
  "desktop_mode": "windows",
  "user_desktop_id": 1,
  "about": "Mathematician and writer known for work on Analytical Engine",
  "voice_id": "bf0a246a-8642-498a-9950-80c35e9276b5",
  "voice_provider": "elevenlabs",
  "pre_hire_chat": [
    {
      "role": "assistant",
      "msg": "Hello, how can I help you?"
    }
  ],
  "timezone": "America/New_York"
}

Response

Assistant created successfully

Example response

{
  "info": {
    "first_name": "Ada",
    "surname": "Lovelace",
    "age": 28,
    "weekly_limit": 15.75,
    "max_parallel": 2,
    "nationality": "North America",
    "profile_photo": "https://example.com/photos/ada.jpg",
    "profile_video": "https://example.com/videos/ada.mp4",
    "desktop_mode": "windows",
    "user_desktop_id": 1,
    "about": "Mathematician and writer known for work on Analytical Engine",
    "voice_id": "bf0a246a-8642-498a-9950-80c35e9276b5",
    "voice_provider": "elevenlabs",
    "pre_hire_chat": [
      {
        "role": "assistant",
        "msg": "Hello, how can I help you?"
      }
    ],
    "timezone": "America/New_York",
    "user_desktop_url": "https://abc123.tunnel.unify.ai",
    "user_desktop_mode": "macos",
    "agent_id": "12345",
    "user_id": "123",
    "created_at": "2025-04-25T10:30:00Z",
    "updated_at": "2025-04-26T14:15:00Z",
    "phone": "+15551234567",
    "phone_country": "US",
    "email": "ada.lovelace@unify.ai",
    "user_phone": "+15559876543",
    "user_whatsapp_number": "+15559876543",
    "assistant_whatsapp_number": "+15551234567",
    "api_key": "1234567890",
    "user_first_name": "Ada",
    "user_last_name": "Lovelace",
    "user_email": "ada.lovelace@unify.ai",
    "monthly_spending_cap": 100
  }
}