Skip to content
EverrunsEverruns
Everruns Cloud is open in early access. Run agents without operating the platform.

Create virtual user.

POST
/v1/virtual-users
curl --request POST \
  --url https://app.everruns.com/api/v1/virtual-users \
  --header 'Content-Type: application/json' \
  --data '{ "avatar_url": "https://example.com/avatar.png", "description": "example", "locale": "en-US", "name": "Ops Bot", "timezone": "America/Los_Angeles", "usage": "end_user" }'

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json

Create an organization-scoped runtime account.

object
avatar_url

Profile image URL.

string | null
Example
https://example.com/avatar.png
description

Human-readable description. Safe to render in user-facing messages.

string | null
locale

Locale used for agent-facing defaults.

string | null
Example
en-US
name
required

Human-readable name. Safe to render in user-facing messages.

string
Example
Ops Bot
timezone

IANA time zone used for agent-facing defaults.

string | null
Example
America/Los_Angeles
usage

Runtime purpose; service accounts may be attached to agents.

string
Allowed values: end_user service

Responses

Section titled “Responses”

201

Section titled “201”

Success

Media typeapplication/json

Organization-scoped runtime account with its own profile and connections.

object
archived_at

Archive timestamp.

string | null format: date-time
avatar_url

Optional avatar URL for UI surfaces.

string | null
created_at
required

Creation timestamp.

string format: date-time
deleted_at

Delete timestamp.

string | null format: date-time
description

Optional description shown in management UI.

string | null
effective_owner
One of:

Effective human owner summary derived from the principal lineage.

object
id
required
string
kind
required

Class of principal that can hold permissions or own resources. system is reserved for platform-internal callers and is never minted via the public API.

string
Allowed values: user virtual_user system
metadata
subject_id
string | null format: uuid
id
required

External identifier (identity_<32-hex>). Shown as id in API.

string
locale

Default locale for unattended runs.

string | null
name
required

Display name used when the identity acts autonomously.

string
organization_id
required

Organization that owns the runtime account.

string
principal
One of:

Principal row representing this identity as a durable owner/executor.

object
id
required
string
kind
required

Class of principal that can hold permissions or own resources. system is reserved for platform-internal callers and is never minted via the public API.

string
Allowed values: user virtual_user system
metadata
subject_id
string | null format: uuid
status
required

Lifecycle status.

string
Allowed values: active archived deleted
timezone

Default timezone for unattended runs.

string | null
updated_at
required

Last update timestamp.

string format: date-time
usage
required

Immutable runtime account purpose.

string
Allowed values: end_user service
Example
{
  "effective_owner": {
    "id": "principal_01933b5a000070008000000000000001",
    "kind": "user"
  },
  "id": "identity_01933b5a000070008000000000000001",
  "organization_id": "org_example",
  "principal": {
    "id": "principal_01933b5a000070008000000000000001",
    "kind": "user"
  },
  "status": "active",
  "usage": "end_user"
}

401

Section titled “401”

Authentication required

403

Section titled “403”

Permission denied