Virtual Users API Documentation – xMagic

Virtual users let you tell which person a request belongs to when your app uses one API key for everyone. Each email is unique within a workspace and does not need to belong to an xMagic account.

Authentication & Base URL

See the Authentication page for details on API keys. Use the workspace ID in each URL. You must be a workspace admin or owner to manage virtual users.

Base URL:

https://api.xmagic.ai/xmagic-backend/v1

1. Create a Virtual User

POST /v1/workspaces/{workspace_id}/virtual-users

Request Body (JSON)

Field	Type	Required	Description
email	string	Yes	Valid email address. Matching is case-insensitive.
name	string	No	Display name, up to 256 characters.
origin	string	No	Application the user comes from, up to 256 characters.
metadata	object	No	Additional key-value data. Keys and text values are saved in lowercase. Defaults to {}.

If the email already exists, this returns the existing profile without changing its name, origin, or metadata. Use PATCH to update those fields.

Example

curl -X POST "https://api.xmagic.ai/xmagic-backend/v1/workspaces/{workspace_id}/virtual-users" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "name": "Alice Chen",
    "origin": "customer-portal",
    "metadata": {"Department": "Engineering", "region": "Europe"}
  }'

Response — 200 OK

{
  "data": {
    "id": "507f1f77bcf86cd799439011",
    "organization_id": "507f1f77bcf86cd799439012",
    "email": "alice@example.com",
    "name": "Alice Chen",
    "origin": "customer-portal",
    "metadata": {"department": "engineering", "region": "europe"},
    "created_at": "2026-09-24T10:00:00Z",
    "updated_at": null
  }
}

2. List or Find Virtual Users

GET /v1/workspaces/{workspace_id}/virtual-users

Query Parameters

Parameter	Type	Default	Description
email	string	—	Match an exact email, ignoring case.
search	string	—	Find text within email, name, or origin, ignoring case. Maximum 256 characters.
page	integer	0	Page number, starting at 0.
page_size	integer	50	Number of users per page, from 1 to 200.

Increase page to get the next page. An unknown email returns an empty list.

Example

curl -G "https://api.xmagic.ai/xmagic-backend/v1/workspaces/{workspace_id}/virtual-users" \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "email=alice@example.com"

The response includes virtual_users and pagination with page, page_size, and total_count. Each profile uses the same fields as the create response.

3. Get a Virtual User

GET /v1/workspaces/{workspace_id}/virtual-users/{virtual_user_id}

Use the id returned by creation or listing.

Example

curl "https://api.xmagic.ai/xmagic-backend/v1/workspaces/{workspace_id}/virtual-users/{virtual_user_id}" \
  -H "x-api-key: YOUR_API_KEY"

Returns 200 OK with the profile in data.

4. Update a Virtual User

PATCH /v1/workspaces/{workspace_id}/virtual-users/{virtual_user_id}

Request Body (JSON)

Field	Type	Description
name	string or null	New display name, up to 256 characters. null clears it.
origin	string or null	New application name, up to 256 characters. null clears it.
metadata	object	Replaces all existing metadata. {} clears it.

All fields are optional. Omitted fields stay unchanged. Include any existing metadata fields you want to keep when updating metadata. Email cannot be changed.

Example

curl -X PATCH "https://api.xmagic.ai/xmagic-backend/v1/workspaces/{workspace_id}/virtual-users/{virtual_user_id}" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Alice Chen",
    "origin": "help-desk",
    "metadata": {"team": "customer-success", "region": "europe"}
  }'

Returns 200 OK with the updated profile in data.

5. Delete a Virtual User

DELETE /v1/workspaces/{workspace_id}/virtual-users/{virtual_user_id}

Removes the user from workspace lists. Existing chats keep their attribution. If the email is used again, the profile is restored.

Example

curl -X DELETE "https://api.xmagic.ai/xmagic-backend/v1/workspaces/{workspace_id}/virtual-users/{virtual_user_id}" \
  -H "x-api-key: YOUR_API_KEY"

Response — 200 OK

{"data": {"deleted": true}}

Errors

Status	Reason
401	Authentication failed.
403	You are not an admin or owner of the requested workspace.
404	The user does not exist in your workspace or has been removed.
422	Invalid email, ID, pagination, or profile fields.

A missing user returns {"error_code": "VIRTUAL_USER_NOT_FOUND"}.

Use Virtual Users in Chats and Uploads

Pass virtual_user_email on a query or file upload to identify the person making the request. If the email does not exist, the API creates the virtual user automatically.