# Create virtual user.

Source: <https://everruns.com/docs/api/operations/create_virtual_user/>

POST

/v1/virtual-users

Select code samplecURL (shell:curl)

```js
const url = 'https://app.everruns.com/api/v1/virtual-users';
const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: '{"avatar_url":"https://example.com/avatar.png","description":"example","locale":"en-US","name":"Ops Bot","timezone":"America/Los_Angeles","usage":"end_user"}'
};


try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```sh
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" }'
```

* Production APIapp.everruns.com/api/v1/virtual-users

## Request Bodyrequired

Media typeapplication/json

Create an organization-scoped runtime account.

object

**avatar\_url**

Profile image URL.

string | null

##### Example

```plaintext
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

```plaintext
en-US
```

**name**

required

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

string

##### Example

```plaintext
Ops Bot
```

**timezone**

IANA time zone used for agent-facing defaults.

string | null

##### Example

```plaintext
America/Los_Angeles
```

**usage**

Runtime purpose; service accounts may be attached to agents.

string

Allowed values: end\_user service

## Responses

### 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:

* object

  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

* null

  null

**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:

* object

  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

* null

  null

**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

```json
{
  "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

Authentication required

### 403

Permission denied