> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Kernel API reference

> API reference for the Kernel plugin in Corsair: every `kernel.api.*` operation with its input and output types, taken from the plugin's Zod schemas.

> [!NOTE]
>
> **New to Corsair?** See [API access](https://docs.corsair.dev/concepts/api.md), [authentication](https://docs.corsair.dev/concepts/auth.md), and [error handling](https://docs.corsair.dev/concepts/error-handling).

## Api Keys

### create

`apiKeys.create`

Create a Kernel API key. The secret is shown once in the response: store it right away and never paste it into chat.

**Risk:** `destructive`

```ts theme={null}
await corsair.kernel.api.apiKeys.create({ name: 'my-name' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `days_to_expire` | `number \| null` | No | Number of days until expiry, up to 3650. Use null for never. Cannot be combined with expires\_at. |
| `expires_at` | `string \| null` | No | Exact expiry time. Must be in the future and no later than the issuing credential's own expiry. Cannot be combined with days\_to\_expire. |
| `name` | `string` | Yes | Label for the API key (1-255 characters). API keys are not addressable by name. |
| `policy` | `object` | No | — |
| `project_id` | `string \| null` | No | Unique project identifier |
| `service_account_id` | `string` | No | Link to an active same-organization service account. Requires an organization administrator, explicit project and nonempty policy. Omit for a personal key. |

> [accordion] policy full type
>
> ```ts theme={null}
> {
>   statements: {
>     action: string,
>     condition?: {
>       key: source_ip,
>       operator: in,
>       values: string[]
>     },
>     resource: string
>   }[]
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `created_at` | `string \| null` | No | When the API key was created |
| `created_by` | `object \| null` | No | Human audit creator, or null after creator deletion. Not the service credential's principal. |
| `deleted_at` | `string \| null \| null` | No | When the API key was deleted (soft-deleted). Null for keys that have not been deleted. |
| `expires_at` | `string \| null \| null` | No | When the API key expires |
| `id` | `string \| null` | No | Unique API key identifier |
| `last_used_at` | `string \| null \| null` | No | When the API key last authenticated a request, accurate to within about 20 minutes. Null if the key has not been used since last-use tracking began. |
| `masked_key` | `string \| null` | No | Masked version of the API key |
| `name` | `string \| null` | No | Label for the API key. API keys are not addressable by name; use the ID or key identifier for stable references. |
| `policy` | `object \| null` | No | — |
| `principal` | `object \| null` | No | — |
| `project_id` | `string \| null \| null` | No | Project identifier for project-scoped API keys. Null means org-wide. |
| `project_name` | `string \| null \| null` | No | Project name for project-scoped API keys. Null means the key is org-wide or the project name is unavailable. |
| `service_account_id` | `string \| null` | No | Organization-owned service principal, when linked. |
| `key` | `string \| null` | No | Plaintext API key. Only returned once when the key is created. |

> [accordion] created\_by full type
>
> ```ts theme={null}
> {
>   email?: string | null,
>   id?: string | null,
>   name?: string | null | null
> } | null | null
> ```

> [accordion] policy full type
>
> ```ts theme={null}
> {
>   statements?: {
>     action?: string | null,
>     condition?: {
>       key?: string | null,
>       operator?: string | null,
>       values?: string[] | null
>     } | null,
>     resource?: string | null
>   }[] | null
> } | null | null
> ```

> [accordion] principal full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   type?: string | null
> } | null
> ```

***

### delete

`apiKeys.delete`

Delete an API key; anything using it stops working. Cannot be undone.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.kernel.api.apiKeys.delete({ id: 'apiKey_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | API key ID |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### get

`apiKeys.get`

Get an API key's metadata.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.apiKeys.get({ id: 'apiKey_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | API key ID |
| `include_deleted` | `boolean` | No | When true, return the API key even if it has been deleted (soft-deleted), for audit purposes. Defaults to false, which returns 404 for a deleted key. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `created_at` | `string \| null` | No | When the API key was created |
| `created_by` | `object \| null` | No | Human audit creator, or null after creator deletion. Not the service credential's principal. |
| `deleted_at` | `string \| null \| null` | No | When the API key was deleted (soft-deleted). Null for keys that have not been deleted. |
| `expires_at` | `string \| null \| null` | No | When the API key expires |
| `id` | `string \| null` | No | Unique API key identifier |
| `last_used_at` | `string \| null \| null` | No | When the API key last authenticated a request, accurate to within about 20 minutes. Null if the key has not been used since last-use tracking began. |
| `masked_key` | `string \| null` | No | Masked version of the API key |
| `name` | `string \| null` | No | Label for the API key. API keys are not addressable by name; use the ID or key identifier for stable references. |
| `policy` | `object \| null` | No | — |
| `principal` | `object \| null` | No | — |
| `project_id` | `string \| null \| null` | No | Project identifier for project-scoped API keys. Null means org-wide. |
| `project_name` | `string \| null \| null` | No | Project name for project-scoped API keys. Null means the key is org-wide or the project name is unavailable. |
| `service_account_id` | `string \| null` | No | Organization-owned service principal, when linked. |

> [accordion] created\_by full type
>
> ```ts theme={null}
> {
>   email?: string | null,
>   id?: string | null,
>   name?: string | null | null
> } | null | null
> ```

> [accordion] policy full type
>
> ```ts theme={null}
> {
>   statements?: {
>     action?: string | null,
>     condition?: {
>       key?: string | null,
>       operator?: string | null,
>       values?: string[] | null
>     } | null,
>     resource?: string | null
>   }[] | null
> } | null | null
> ```

> [accordion] principal full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   type?: string | null
> } | null
> ```

***

### list

`apiKeys.list`

List API keys (names, scopes, last used; never the secrets).

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.apiKeys.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `limit` | `number` | No | Maximum number of results to return |
| `offset` | `number` | No | Number of results to skip |
| `query` | `string` | No | Case-insensitive substring match against API key name, creator, and project. API key identifiers and masked keys match by exact value or prefix. |
| `name` | `string` | No | Exact-match filter on API key name using the database collation. In production, matching is case- and accent-insensitive. Names are not required to be unique, so multiple keys may match. When status=all or include\_deleted=true is set, soft-deleted keys with the same name may also match. |
| `sort_by` | `created_at \| name \| expires_at \| last_used_at` | No | Field to sort API keys by. Keys with no expiry or no recorded use sort last for expires\_at and last\_used\_at in either direction. |
| `sort_direction` | `asc \| desc` | No | Sort direction for API keys. |
| `status` | `active \| expired \| deleted \| all` | No | Filter API keys by status. "active" returns keys that are neither deleted nor expired (default), "expired" returns keys that are not deleted and whose expiry has passed, "deleted" returns only soft-deleted keys, "all" returns every key. |
| `service_account_id` | `string` | No | Return only keys that belong to this service account. |
| `principal_type` | `user \| service_account` | No | Return only keys that act as a user, or only keys that act as a service account. |
| `created_by` | `string` | No | Return only keys created by this user ID. This is the same person the key's created\_by field describes. |
| `project_id` | `string` | No | Return only keys scoped to this project ID. The value "org" returns keys that are not scoped to a project. |
| `include_deleted` | `boolean` | No | Deprecated: use status=all instead. When true, include deleted (soft-deleted) API keys in the results for audit purposes. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | This page of results. |
| `has_more` | `boolean` | Yes | True when more results follow; pass next\_offset as offset to read them. |
| `next_offset` | `number \| null` | Yes | Value for `offset` that reads the next page, or null on the last page. |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   created_at?: string | null,
>   created_by?: {
>     email?: string | null,
>     id?: string | null,
>     name?: string | null | null
>   } | null | null,
>   deleted_at?: string | null | null,
>   expires_at?: string | null | null,
>   id?: string | null,
>   last_used_at?: string | null | null,
>   masked_key?: string | null,
>   name?: string | null,
>   policy?: {
>     statements?: {
>       action?: string | null,
>       condition?: {
>         key?: string | null,
>         operator?: string | null,
>         values?: string[] | null
>       } | null,
>       resource?: string | null
>     }[] | null
>   } | null | null,
>   principal?: {
>     id?: string | null,
>     type?: string | null
>   } | null,
>   project_id?: string | null | null,
>   project_name?: string | null | null,
>   service_account_id?: string | null
> }[]
> ```

***

### rotate

`apiKeys.rotate`

Replace an API key's secret. The new secret is shown once. The old one keeps working for expire\_in\_days (7 by default); pass expire\_in\_days: 0 to end it now.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.kernel.api.apiKeys.rotate({ id: 'apiKey_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | API key ID |
| `days_to_expire` | `number \| null` | No | Lifetime in days for the new key, up to 3650. Omit to reuse the rotated key's original lifetime, or never-expires if it had none. |
| `expire_in_days` | `number \| null` | No | Grace period in days before the rotated key expires. Use 0 to expire it immediately. Omit for the default grace period of 7 days. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `created_at` | `string \| null` | No | When the API key was created |
| `created_by` | `object \| null` | No | Human audit creator, or null after creator deletion. Not the service credential's principal. |
| `deleted_at` | `string \| null \| null` | No | When the API key was deleted (soft-deleted). Null for keys that have not been deleted. |
| `expires_at` | `string \| null \| null` | No | When the API key expires |
| `id` | `string \| null` | No | Unique API key identifier |
| `last_used_at` | `string \| null \| null` | No | When the API key last authenticated a request, accurate to within about 20 minutes. Null if the key has not been used since last-use tracking began. |
| `masked_key` | `string \| null` | No | Masked version of the API key |
| `name` | `string \| null` | No | Label for the API key. API keys are not addressable by name; use the ID or key identifier for stable references. |
| `policy` | `object \| null` | No | — |
| `principal` | `object \| null` | No | — |
| `project_id` | `string \| null \| null` | No | Project identifier for project-scoped API keys. Null means org-wide. |
| `project_name` | `string \| null \| null` | No | Project name for project-scoped API keys. Null means the key is org-wide or the project name is unavailable. |
| `service_account_id` | `string \| null` | No | Organization-owned service principal, when linked. |
| `key` | `string \| null` | No | Plaintext API key. Only returned once when the key is created. |

> [accordion] created\_by full type
>
> ```ts theme={null}
> {
>   email?: string | null,
>   id?: string | null,
>   name?: string | null | null
> } | null | null
> ```

> [accordion] policy full type
>
> ```ts theme={null}
> {
>   statements?: {
>     action?: string | null,
>     condition?: {
>       key?: string | null,
>       operator?: string | null,
>       values?: string[] | null
>     } | null,
>     resource?: string | null
>   }[] | null
> } | null | null
> ```

> [accordion] principal full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   type?: string | null
> } | null
> ```

***

### update

`apiKeys.update`

Rename an API key or change its settings.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.apiKeys.update({ id: 'apiKey_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | API key ID |
| `name` | `string` | No | New API key name |
| `policy` | `object` | No | — |

> [accordion] policy full type
>
> ```ts theme={null}
> {
>   statements: {
>     action: string,
>     condition?: {
>       key: source_ip,
>       operator: in,
>       values: string[]
>     },
>     resource: string
>   }[]
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `created_at` | `string \| null` | No | When the API key was created |
| `created_by` | `object \| null` | No | Human audit creator, or null after creator deletion. Not the service credential's principal. |
| `deleted_at` | `string \| null \| null` | No | When the API key was deleted (soft-deleted). Null for keys that have not been deleted. |
| `expires_at` | `string \| null \| null` | No | When the API key expires |
| `id` | `string \| null` | No | Unique API key identifier |
| `last_used_at` | `string \| null \| null` | No | When the API key last authenticated a request, accurate to within about 20 minutes. Null if the key has not been used since last-use tracking began. |
| `masked_key` | `string \| null` | No | Masked version of the API key |
| `name` | `string \| null` | No | Label for the API key. API keys are not addressable by name; use the ID or key identifier for stable references. |
| `policy` | `object \| null` | No | — |
| `principal` | `object \| null` | No | — |
| `project_id` | `string \| null \| null` | No | Project identifier for project-scoped API keys. Null means org-wide. |
| `project_name` | `string \| null \| null` | No | Project name for project-scoped API keys. Null means the key is org-wide or the project name is unavailable. |
| `service_account_id` | `string \| null` | No | Organization-owned service principal, when linked. |

> [accordion] created\_by full type
>
> ```ts theme={null}
> {
>   email?: string | null,
>   id?: string | null,
>   name?: string | null | null
> } | null | null
> ```

> [accordion] policy full type
>
> ```ts theme={null}
> {
>   statements?: {
>     action?: string | null,
>     condition?: {
>       key?: string | null,
>       operator?: string | null,
>       values?: string[] | null
>     } | null,
>     resource?: string | null
>   }[] | null
> } | null | null
> ```

> [accordion] principal full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   type?: string | null
> } | null
> ```

***

## Apps

### list

`apps.list`

List deployed Kernel apps and their versions and actions.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.apps.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `app_name` | `string` | No | Filter results by application name. |
| `version` | `string` | No | Filter results by version label. |
| `limit` | `number` | No | Limit the number of apps to return. |
| `offset` | `number` | No | Offset the number of apps to return. |
| `query` | `string` | No | Search apps by name. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | This page of results. |
| `has_more` | `boolean` | Yes | True when more results follow; pass next\_offset as offset to read them. |
| `next_offset` | `number \| null` | Yes | Value for `offset` that reads the next page, or null on the last page. |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   actions?: {
>     input_schema?: {
>     } | null | null,
>     name?: string | null,
>     output_schema?: {
>     } | null | null
>   }[] | null,
>   app_name?: string | null,
>   deployment?: string | null,
>   env_vars?: Record<string, string> | null,
>   id?: string | null,
>   region?: string | null,
>   version?: string | null
> }[]
> ```

***

## Audit Logs

### exportChunk

`auditLogs.exportChunk`

Download one chunk of the audit log as JSONL (gzipped by default). Returns a file plus has\_more and next\_cursor for the next chunk.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.auditLogs.exportChunk({ start: '2026-11-19T00:00:00Z', end: '2026-11-20T00:00:00Z', format: 'jsonl' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `start` | `string` | Yes | Lower bound (inclusive) for the audit record timestamp. |
| `end` | `string` | Yes | Upper bound (exclusive) for the audit record timestamp. |
| `auth_strategy` | `string` | No | Filter by authentication strategy. |
| `service` | `string` | No | Filter by service name. |
| `method` | `string` | No | Filter by HTTP method. |
| `exclude_method` | `string[]` | No | Filter out results by HTTP method. |
| `search` | `string` | No | Free-text search over path, user ID, email, client IP, and status. |
| `search_user_id` | `string[]` | No | Additional user IDs to OR into free-text search. |
| `cursor` | `string` | No | Opaque cursor from X-Next-Cursor for the next chunk of older records. |
| `limit` | `number` | No | Maximum number of records to return in this chunk. |
| `format` | `jsonl \| jsonl.gz` | No | Encoding for the returned chunk. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `contentBase64` | `string` | No | The file, base64-encoded. Missing when the file came back as text or contentOmitted is set. |
| `text` | `string` | No | The file as text, in place of contentBase64, when it is a text file (CSV, JSON, Markdown, XML and the like) in UTF-8. |
| `contentType` | `string` | Yes | Media type of the file, for example application/pdf. |
| `byteLength` | `number` | Yes | Size of the file in bytes. |
| `filename` | `string` | No | The file name, when known. |
| `contentOmitted` | `not_requested \| over_limit` | No | Set when the content was left out: the caller did not ask for it, or the file was over the limit. |
| `fileId` | `string` | No | Where the host saved the file. Over the limit it comes in place of the content; a host that keeps every file sets it beside the content too. On Corsair it is a Files id (fil\_…): pass it to another app wherever that app takes a file URL, or read a text file or PDF with files.read\_text. |
| `has_more` | `boolean` | Yes | True when another chunk follows; pass next\_cursor as cursor to read it. |
| `next_cursor` | `string \| null` | Yes | Pass as cursor to read the next chunk. |

***

### exportDestinations.create

`auditLogs.exportDestinations.create`

Add a destination (such as an S3 bucket) that receives continuous audit log exports.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.auditLogs.exportDestinations.create({
	type: 's3',
	region: 'example',
	bucket: 'example',
	prefix: 'example',
	role_arn: 'example',
	format: 'jsonl.gz',
});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `bucket` | `string` | Yes | — |
| `format` | `jsonl.gz` | Yes | — |
| `kms_key_id` | `string` | No | — |
| `prefix` | `string` | Yes | — |
| `region` | `string` | Yes | — |
| `role_arn` | `string` | Yes | — |
| `type` | `s3` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `bucket` | `string \| null` | No | — |
| `consecutive_failures` | `number \| null` | No | — |
| `created_at` | `string \| null` | No | — |
| `external_id` | `string \| null` | No | — |
| `format` | `string \| null` | No | — |
| `id` | `string \| null` | No | — |
| `kernel_role_arn` | `string \| null` | No | The Kernel role that assumes `role_arn` in your account to deliver logs. Allow this role as the principal in your role's trust policy, and require `external_id` as the `sts:ExternalId` condition. Recreating a destination issues a new `external_id`, which the trust policy has to be updated to match. |
| `kms_key_id` | `string \| null` | No | — |
| `last_error` | `string \| null` | No | Sanitized description of the most recent delivery failure. |
| `last_error_at` | `string \| null` | No | — |
| `last_exported_cursor` | `string \| null` | No | Opaque, versioned checkpoint for forward-only continuous export. This value is not compatible with audit-log list page tokens. Delivery starts at the moment the destination is activated, so events recorded before that are not delivered. Pausing stops delivery and resuming starts again from the time of the resume: events recorded while a destination was paused are never exported, and pausing is not a way to defer delivery. |
| `last_success_at` | `string \| null` | No | — |
| `next_attempt_at` | `string \| null` | No | — |
| `prefix` | `string \| null` | No | — |
| `region` | `string \| null` | No | — |
| `role_arn` | `string \| null` | No | — |
| `status` | `string \| null` | No | Pausing prevents new delivery attempts. An S3 upload already in progress may complete after the pause response; its rows can appear again after the destination is resumed. |
| `type` | `string \| null` | No | — |
| `updated_at` | `string \| null` | No | — |

***

### exportDestinations.delete

`auditLogs.exportDestinations.delete`

Delete an audit log export destination. Cannot be undone.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.kernel.api.auditLogs.exportDestinations.delete({ id: 'auditLog_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### exportDestinations.get

`auditLogs.exportDestinations.get`

Get an audit log export destination.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.auditLogs.exportDestinations.get({ id: 'auditLog_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `bucket` | `string \| null` | No | — |
| `consecutive_failures` | `number \| null` | No | — |
| `created_at` | `string \| null` | No | — |
| `external_id` | `string \| null` | No | — |
| `format` | `string \| null` | No | — |
| `id` | `string \| null` | No | — |
| `kernel_role_arn` | `string \| null` | No | The Kernel role that assumes `role_arn` in your account to deliver logs. Allow this role as the principal in your role's trust policy, and require `external_id` as the `sts:ExternalId` condition. Recreating a destination issues a new `external_id`, which the trust policy has to be updated to match. |
| `kms_key_id` | `string \| null` | No | — |
| `last_error` | `string \| null` | No | Sanitized description of the most recent delivery failure. |
| `last_error_at` | `string \| null` | No | — |
| `last_exported_cursor` | `string \| null` | No | Opaque, versioned checkpoint for forward-only continuous export. This value is not compatible with audit-log list page tokens. Delivery starts at the moment the destination is activated, so events recorded before that are not delivered. Pausing stops delivery and resuming starts again from the time of the resume: events recorded while a destination was paused are never exported, and pausing is not a way to defer delivery. |
| `last_success_at` | `string \| null` | No | — |
| `next_attempt_at` | `string \| null` | No | — |
| `prefix` | `string \| null` | No | — |
| `region` | `string \| null` | No | — |
| `role_arn` | `string \| null` | No | — |
| `status` | `string \| null` | No | Pausing prevents new delivery attempts. An S3 upload already in progress may complete after the pause response; its rows can appear again after the destination is resumed. |
| `type` | `string \| null` | No | — |
| `updated_at` | `string \| null` | No | — |

***

### exportDestinations.list

`auditLogs.exportDestinations.list`

List audit log export destinations.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.auditLogs.exportDestinations.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `limit` | `number` | No | Limit the number of destinations to return. |
| `offset` | `number` | No | Offset the number of destinations to return. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | This page of results. |
| `has_more` | `boolean` | Yes | True when more results follow; pass next\_offset as offset to read them. |
| `next_offset` | `number \| null` | Yes | Value for `offset` that reads the next page, or null on the last page. |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   bucket?: string | null,
>   consecutive_failures?: number | null,
>   created_at?: string | null,
>   external_id?: string | null,
>   format?: string | null,
>   id?: string | null,
>   kernel_role_arn?: string | null,
>   kms_key_id?: string | null,
>   last_error?: string | null,
>   last_error_at?: string | null,
>   last_exported_cursor?: string | null,
>   last_success_at?: string | null,
>   next_attempt_at?: string | null,
>   prefix?: string | null,
>   region?: string | null,
>   role_arn?: string | null,
>   status?: string | null,
>   type?: string | null,
>   updated_at?: string | null
> }[]
> ```

***

### exportDestinations.test

`auditLogs.exportDestinations.test`

Send a test export to an audit log destination to check it works.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.auditLogs.exportDestinations.test({ id: 'auditLog_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `error` | `object \| null` | No | — |
| `stage` | `string \| null` | No | — |
| `success` | `boolean \| null` | No | — |

> [accordion] error full type
>
> ```ts theme={null}
> {
>   code?: string | null,
>   message?: string | null
> } | null
> ```

***

### exportDestinations.update

`auditLogs.exportDestinations.update`

Update an audit log export destination.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.auditLogs.exportDestinations.update({ id: 'auditLog_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |
| `bucket` | `string` | No | — |
| `kms_key_id` | `string \| null` | No | KMS key ID, alias, or ARN. Set to an empty string to remove the configured KMS key; omit or send null to leave unchanged. |
| `prefix` | `string` | No | — |
| `region` | `string` | No | — |
| `role_arn` | `string` | No | — |
| `status` | `active \| paused` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `bucket` | `string \| null` | No | — |
| `consecutive_failures` | `number \| null` | No | — |
| `created_at` | `string \| null` | No | — |
| `external_id` | `string \| null` | No | — |
| `format` | `string \| null` | No | — |
| `id` | `string \| null` | No | — |
| `kernel_role_arn` | `string \| null` | No | The Kernel role that assumes `role_arn` in your account to deliver logs. Allow this role as the principal in your role's trust policy, and require `external_id` as the `sts:ExternalId` condition. Recreating a destination issues a new `external_id`, which the trust policy has to be updated to match. |
| `kms_key_id` | `string \| null` | No | — |
| `last_error` | `string \| null` | No | Sanitized description of the most recent delivery failure. |
| `last_error_at` | `string \| null` | No | — |
| `last_exported_cursor` | `string \| null` | No | Opaque, versioned checkpoint for forward-only continuous export. This value is not compatible with audit-log list page tokens. Delivery starts at the moment the destination is activated, so events recorded before that are not delivered. Pausing stops delivery and resuming starts again from the time of the resume: events recorded while a destination was paused are never exported, and pausing is not a way to defer delivery. |
| `last_success_at` | `string \| null` | No | — |
| `next_attempt_at` | `string \| null` | No | — |
| `prefix` | `string \| null` | No | — |
| `region` | `string \| null` | No | — |
| `role_arn` | `string \| null` | No | — |
| `status` | `string \| null` | No | Pausing prevents new delivery attempts. An S3 upload already in progress may complete after the pause response; its rows can appear again after the destination is resumed. |
| `type` | `string \| null` | No | — |
| `updated_at` | `string \| null` | No | — |

***

### list

`auditLogs.list`

Search the org's audit log (who called what, when), newest first. Pages with page\_token; check has\_more.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.auditLogs.list({ start: '2026-11-19T00:00:00Z', end: '2026-11-20T00:00:00Z', limit: 50 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `start` | `string` | Yes | Lower bound (inclusive) for the audit record timestamp. |
| `end` | `string` | Yes | Upper bound (exclusive) for the audit record timestamp. |
| `auth_strategy` | `string` | No | Filter by authentication strategy. |
| `service` | `string` | No | Filter by service name. |
| `method` | `string` | No | Filter by HTTP method. |
| `exclude_method` | `string[]` | No | Filter out results by HTTP method. |
| `search` | `string` | No | Free-text search over path, user ID, email, client IP, and status. |
| `search_user_id` | `string[]` | No | Additional user IDs to OR into free-text search. |
| `limit` | `number` | No | Maximum number of results to return. |
| `page_token` | `string` | No | Opaque page token from X-Next-Page-Token for the next page of older records. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | This page of results. |
| `has_more` | `boolean` | Yes | True when more results follow; pass next\_page\_token as page\_token to read them. |
| `next_page_token` | `string \| null` | Yes | Value for `page_token` that reads the next page, or null on the last page. |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   auth_strategy?: string | null,
>   client_ip?: string | null,
>   domain?: string | null,
>   duration_ms?: number | null,
>   email?: string | null,
>   method?: string | null,
>   path?: string | null,
>   route?: string | null,
>   status?: number | null,
>   timestamp?: string | null,
>   user_agent?: string | null,
>   user_id?: string | null
> }[]
> ```

***

## Auth

### connections.create

`auth.connections.create`

Set up managed login for a site: one connection per profile and domain (the profile is created if missing). Then start a login with auth.connections.login.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.auth.connections.create({ domain: 'app.acme.com', profile_name: 'acme-login' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `allowed_domains` | `string[]` | No | Additional hostname roots valid for this auth flow, besides the primary domain. Each value allows credential entry on that exact hostname and its subdomains. Leading `www.` and `*.` labels are normalized away. When omitted or empty, credential entry is unrestricted. The following SSO/OAuth provider domains are automatically allowed by default and do not need to be specified: - Google: accounts.google.com - Microsoft/Azure AD: login.microsoftonline.com, login.live.com - Okta: \*.okta.com, \*.oktapreview\.com - Auth0: \*.auth0.com, \*.us.auth0.com, \*.eu.auth0.com, \*.au.auth0.com - Apple: appleid.apple.com - GitHub: github.com - Facebook/Meta: [www.facebook.com](http://www.facebook.com) - LinkedIn: [www.linkedin.com](http://www.linkedin.com) - Amazon Cognito: \*.amazoncognito.com - OneLogin: \*.onelogin.com - Ping Identity: \*.pingone.com, \*.pingidentity.com |
| `auto_reauth` | `boolean` | No | Whether to permit automatic re-authentication when a scheduled health check detects an expired session. This is an opt-in flag only — it does not check whether re-auth is actually feasible. Even when true, re-auth only runs when the system has what it needs to perform it (for example, saved credentials for the required login fields), and only after a scheduled health check detects an expired session — so this flag has no effect when `health_checks` is false. When false, expired sessions are marked as `NEEDS_AUTH` instead of attempting re-auth. Defaults to true. |
| `browser` | `object` | No | — |
| `browser_telemetry` | `object \| null` | No | — |
| `credential` | `object` | No | — |
| `domain` | `string` | Yes | Domain for authentication |
| `health_check_interval` | `number` | No | Interval in seconds between automatic health checks. When set, the system periodically verifies the authentication status and triggers re-authentication if needed. Maximum is 86400 (24 hours). Default is 3600 (1 hour) or your plan minimum, whichever is larger. The minimum depends on your plan: Enterprise: 300 (5 minutes), Startup: 1200 (20 minutes), Hobbyist: 3600 (1 hour), Free: 21600 (6 hours). |
| `health_checks` | `boolean` | No | Whether to enable periodic health checks. When false, the system will not automatically verify authentication status, and `auto_reauth` has no effect on the automatic flow (since re-auth is only triggered by a failed scheduled health check). Defaults to true. |
| `hitl` | `boolean` | No | Whether a login blocked by a CAPTCHA the browser cannot solve pauses for a person instead of failing. The flow moves to AWAITING\_HUMAN\_INTERVENTION with a `human_intervention` choice; the person completes the challenge in `live_view_url`, then submits that choice to resume. Reauthentication never pauses. Defaults to false. |
| `login_url` | `string` | No | Optional login page URL to skip discovery |
| `profile_name` | `string` | Yes | Name of the profile to manage authentication for. If the profile does not exist, it is created automatically. |
| `proxy` | `object` | No | — |
| `record_session` | `boolean` | No | Whether to record browser sessions for this connection by default. Useful for debugging. Can be overridden per-login. Defaults to false. |
| `save_credentials` | `boolean` | No | Whether to save credentials after every successful login. Defaults to true. One-time codes (TOTP, SMS, etc.) are not saved. |

> [accordion] browser full type
>
> ```ts theme={null}
> {
>   captcha_solver?: {
>     enabled: boolean
>   },
>   location?: {
>     locale?: string | null
>   },
>   proxy?: {
>     id?: string,
>     mode?: direct | default,
>     name?: string
>   },
>   region?: us-east | us-west | eu-west | ap-southeast,
>   stealth?: boolean,
>   telemetry?: {
>     browser?: {
>       captcha?: {
>         enabled?: boolean
>       },
>       connection?: {
>         enabled?: boolean
>       },
>       console?: {
>         enabled?: boolean
>       },
>       control?: {
>         cdp?: {
>           excluded_methods?: (Input.dispatchMouseEvent | Input.dispatchKeyEvent | Input.insertText | Input.imeSetComposition | Input.dispatchTouchEvent | Input.dispatchDragEvent | Input.cancelDragging | Input.emulateTouchFromMouseEvent | Input.synthesizePinchGesture | Input.synthesizeScrollGesture | Input.synthesizeTapGesture | DOM.setFileInputFiles | DOM.focus | DOM.scrollIntoViewIfNeeded | Page.bringToFront | Page.captureScreenshot | Page.captureSnapshot | Page.handleJavaScriptDialog | Page.navigate | Page.navigateToHistoryEntry | Page.reload | Page.printToPDF | Page.startScreencast | Page.stopScreencast | Page.stopLoading | Page.close | Page.setWebLifecycleState | Target.activateTarget | Target.closeTarget | Target.createTarget | Target.createBrowserContext | Target.disposeBrowserContext | Target.openDevTools | Browser.cancelDownload | Browser.close | Browser.setWindowBounds | Browser.setContentsSize | Autofill.trigger)[]
>         },
>         enabled?: boolean
>       },
>       interaction?: {
>         enabled?: boolean
>       },
>       network?: {
>         enabled?: boolean
>       },
>       page?: {
>         enabled?: boolean
>       },
>       platform?: {
>         enabled?: boolean
>       },
>       screenshot?: {
>         enabled?: boolean
>       },
>       system?: {
>         enabled?: boolean
>       }
>     },
>     enabled?: boolean,
>     export?: {
>       otlp?: {
>         destination?: {
>           id?: string,
>           name?: string
>         },
>         enabled?: boolean
>       }
>     },
>     storage?: {
>       enabled?: boolean
>     }
>   } | null
> }
> ```

> [accordion] browser\_telemetry full type
>
> ```ts theme={null}
> {
>   browser?: {
>     captcha?: {
>       enabled?: boolean
>     },
>     connection?: {
>       enabled?: boolean
>     },
>     console?: {
>       enabled?: boolean
>     },
>     control?: {
>       cdp?: {
>         excluded_methods?: (Input.dispatchMouseEvent | Input.dispatchKeyEvent | Input.insertText | Input.imeSetComposition | Input.dispatchTouchEvent | Input.dispatchDragEvent | Input.cancelDragging | Input.emulateTouchFromMouseEvent | Input.synthesizePinchGesture | Input.synthesizeScrollGesture | Input.synthesizeTapGesture | DOM.setFileInputFiles | DOM.focus | DOM.scrollIntoViewIfNeeded | Page.bringToFront | Page.captureScreenshot | Page.captureSnapshot | Page.handleJavaScriptDialog | Page.navigate | Page.navigateToHistoryEntry | Page.reload | Page.printToPDF | Page.startScreencast | Page.stopScreencast | Page.stopLoading | Page.close | Page.setWebLifecycleState | Target.activateTarget | Target.closeTarget | Target.createTarget | Target.createBrowserContext | Target.disposeBrowserContext | Target.openDevTools | Browser.cancelDownload | Browser.close | Browser.setWindowBounds | Browser.setContentsSize | Autofill.trigger)[]
>       },
>       enabled?: boolean
>     },
>     interaction?: {
>       enabled?: boolean
>     },
>     network?: {
>       enabled?: boolean
>     },
>     page?: {
>       enabled?: boolean
>     },
>     platform?: {
>       enabled?: boolean
>     },
>     screenshot?: {
>       enabled?: boolean
>     },
>     system?: {
>       enabled?: boolean
>     }
>   },
>   enabled?: boolean,
>   export?: {
>     otlp?: {
>       destination?: {
>         id?: string,
>         name?: string
>       },
>       enabled?: boolean
>     }
>   },
>   storage?: {
>     enabled?: boolean
>   }
> } | null
> ```

> [accordion] credential full type
>
> ```ts theme={null}
> {
>   auto?: boolean,
>   name?: string,
>   path?: string,
>   provider?: string
> }
> ```

> [accordion] proxy full type
>
> ```ts theme={null}
> {
>   id?: string,
>   name?: string
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `allowed_domains` | `string[] \| null` | No | Additional hostname roots valid for this auth flow, besides the primary domain. Each value allows credential entry on that exact hostname and its subdomains. Leading `www.` and `*.` labels are normalized away. When omitted or empty, credential entry is unrestricted. The following SSO/OAuth provider domains are automatically allowed by default and do not need to be specified: - Google: accounts.google.com - Microsoft/Azure AD: login.microsoftonline.com, login.live.com - Okta: \*.okta.com, \*.oktapreview\.com - Auth0: \*.auth0.com, \*.us.auth0.com, \*.eu.auth0.com, \*.au.auth0.com - Apple: appleid.apple.com - GitHub: github.com - Facebook/Meta: [www.facebook.com](http://www.facebook.com) - LinkedIn: [www.linkedin.com](http://www.linkedin.com) - Amazon Cognito: \*.amazoncognito.com - OneLogin: \*.onelogin.com - Ping Identity: \*.pingone.com, \*.pingidentity.com |
| `auto_reauth` | `boolean \| null` | No | Whether automatic re-authentication is permitted for this connection. This is an opt-in flag only — it does not check whether re-auth is actually feasible. Even when true, re-auth only runs when the system has what it needs to perform it (for example, saved credentials for the required login fields), and only after a scheduled health check detects an expired session — so this flag has no effect when `health_checks` is false. When false, expired sessions detected by a health check are marked as `NEEDS_AUTH` instead of attempting re-auth. |
| `browser` | `object \| null` | No | — |
| `browser_session_id` | `string \| null \| null` | No | ID of the underlying browser session driving the current flow (present when flow in progress). Use this to inspect or terminate the browser session via the `/browsers` API. |
| `browser_telemetry` | `object \| null` | No | — |
| `can_reauth` | `boolean \| null` | No | Whether this connection's stored requirements are eligible for unattended re-authentication. A true value can represent either fully satisfiable requirements or a best-effort attempt. It does not account for whether automatic re-authentication is enabled or parent workflow state such as an active flow or circuit-breaker cooldown, so it does not guarantee an attempt on the next health check. See `can_reauth_reason` for the specific outcome. |
| `can_reauth_reason` | `string \| null` | No | Machine-readable reason for the current value of `can_reauth`. Affirmative values (requirements are eligible for unattended re-authentication): - `external_credential` — an external credential provider is attached - `cua_has_credential` — CUA flow with a stored credential - `has_credential` — Kernel credential is attached (optimistic; plan viability not checked) - `viable_plans_found` — at least one stored login plan can be replayed - `no_requirements_recorded` — no recorded credential requirements to fail against - `totp_reauth_allowed` — TOTP is the only recorded requirement and a stored secret can generate the code - `optimistic_totp_attempt` — TOTP was previously required but no reusable secret is stored; the connection remains eligible for a circuit-breaker-bounded attempt because the site may not challenge returning sessions - `requirements_satisfiable` — recorded requirements contain no recognized blocker Negative values (a human must complete the login flow): - `no_prior_successful_login` — connection has never completed a successful login - `no_credential` — no Kernel or external credential attached - `no_viable_plans` — credential attached but no replayable login plan exists yet - `viable_plans_require_external_action` — stored plans need an external step (email link, push, etc.) - `requires_external_action` — recorded requirements include an external step - `requires_totp_without_secret` — flow needs a TOTP code but no TOTP secret is stored - `requires_sms_code` — flow needs an SMS code that cannot be received automatically - `requires_email_code` — flow needs an email code that cannot be received automatically - `requires_customer_input` — flow needs another field or choice that is unavailable during unattended re-authentication |
| `choices` | `object[] \| null` | No | Canonical choices awaiting selection. Prefer this over pending\_sso\_buttons, mfa\_options, and sign\_in\_options when present. |
| `credential` | `object \| null` | No | — |
| `discovered_fields` | `object[] \| null` | No | Fields awaiting input (present when flow\_step=awaiting\_input; may also be present with awaiting\_external\_action as fallback actions) |
| `domain` | `string \| null` | No | Target domain for authentication |
| `error_code` | `string \| null \| null` | No | Machine-readable error code (present when flow\_status=failed) |
| `error_message` | `string \| null \| null` | No | Error message (present when flow\_status=failed) |
| `external_action_message` | `string \| null \| null` | No | Instructions for external action (present when flow\_step=awaiting\_external\_action) |
| `fields` | `object[] \| null` | No | Canonical fields awaiting input. Prefer this over discovered\_fields when present. |
| `flow_expires_at` | `string \| null \| null` | No | When the current flow expires (null when no flow in progress). A flow past this timestamp is no longer valid and its `flow_status` will be `EXPIRED`. Clients may start a new login to supersede a stale `IN_PROGRESS` flow past this timestamp. |
| `flow_status` | `string \| null \| null` | No | Current flow status (null when no flow in progress) |
| `flow_step` | `string \| null \| null` | No | Current step in the flow (null when no flow in progress) |
| `flow_type` | `string \| null \| null` | No | Type of the current flow (null when no flow in progress) |
| `health_check_interval` | `number \| null \| null` | No | Interval in seconds between automatic health checks. When set, the system periodically verifies the authentication status and triggers re-authentication if needed. Maximum is 86400 (24 hours). Default is 3600 (1 hour) or your plan minimum, whichever is larger. The minimum depends on your plan: Enterprise: 300 (5 minutes), Startup: 1200 (20 minutes), Hobbyist: 3600 (1 hour), Free: 21600 (6 hours). |
| `health_check_unavailable_reason` | `string \| null` | No | Why health checks cannot verify this connection. Present when health checks are enabled but no auth check URL is available; a recent last\_auth\_check\_at is not evidence of a valid session. |
| `health_checks` | `boolean \| null` | No | Whether periodic health checks are enabled for this connection. When false, the system will not automatically verify authentication status, and `auto_reauth` has no effect on the automatic flow (since re-auth is only triggered by a failed scheduled health check). Manually triggering a health check via the API still works regardless of this setting. |
| `hitl` | `boolean \| null` | No | Whether a login blocked by a CAPTCHA the browser cannot solve pauses at AWAITING\_HUMAN\_INTERVENTION so a person can complete it in the live view. |
| `hosted_url` | `string \| null \| null` | No | URL to redirect user to for hosted login (present when flow in progress) |
| `id` | `string \| null` | No | Unique identifier for the auth connection |
| `interaction_id` | `string \| null \| null` | No | Opaque identifier for the current canonical interaction. Required when submitting fields or choices and changes for each new actionable pause. |
| `last_auth_at` | `string \| null` | No | Deprecated alias for `last_auth_check_at`. Despite the name, this is the last health-check timestamp, not the last successful authentication. Use `last_auth_check_at` instead. |
| `last_auth_check_at` | `string \| null` | No | When the most recent auth health check ran for this connection, regardless of outcome. Updated on every health check and does not by itself indicate that the profile is currently authenticated - use `status` for that. May be newer than `flow_expires_at` when a flow is still in progress because health checks continue to run in parallel. |
| `live_view_url` | `string \| null \| null` | No | Browser live view URL for debugging (present when flow in progress) |
| `login_url` | `string \| null` | No | Optional login page URL to skip discovery |
| `mfa_options` | `object[] \| null` | No | MFA method options (present when flow\_step=awaiting\_input; may also be present with awaiting\_external\_action as fallback actions) |
| `pending_sso_buttons` | `object[] \| null` | No | SSO buttons available (present when flow\_step=awaiting\_input; may also be present with awaiting\_external\_action as fallback actions) |
| `post_login_url` | `string \| null` | No | URL where the browser landed after successful login |
| `profile_name` | `string \| null` | No | Name of the profile associated with this auth connection |
| `proxy_id` | `string \| null` | No | Deprecated. Read browser.proxy instead. Retained during migration for existing clients. |
| `record_session` | `boolean \| null` | No | Whether to record browser session replays for this connection by default. Useful for debugging login flows. Can be overridden per-login. |
| `save_credentials` | `boolean \| null` | No | Whether credentials are saved after every successful login. One-time codes (TOTP, SMS, etc.) are not saved. |
| `sign_in_options` | `object[] \| null` | No | Non-MFA choices presented during the auth flow, such as account selection or org pickers (present when flow\_step=awaiting\_input; may also be present with awaiting\_external\_action as fallback actions). |
| `sso_provider` | `string \| null \| null` | No | SSO provider being used (e.g., google, github, microsoft) |
| `status` | `string \| null` | No | Last known authentication status of the managed profile. An inconclusive health check preserves this status and does not verify the current session. |
| `website_error` | `string \| null \| null` | No | Visible error message from the website (e.g., 'Incorrect password'). Present when the website displays an error during login. |

> [accordion] browser full type
>
> ```ts theme={null}
> {
>   captcha_solver?: {
>     enabled?: boolean | null
>   } | null,
>   location?: {
>     locale?: string | null | null
>   } | null,
>   proxy?: {
>     id?: string | null,
>     mode?: string | null,
>     name?: string | null
>   } | null,
>   region?: string | null,
>   stealth?: boolean | null,
>   telemetry?: {
>     browser?: {
>       captcha?: {
>         enabled?: boolean | null
>       } | null,
>       connection?: {
>         enabled?: boolean | null
>       } | null,
>       console?: {
>         enabled?: boolean | null
>       } | null,
>       control?: {
>         cdp?: {
>           excluded_methods?: string[] | null
>         } | null,
>         enabled?: boolean | null
>       } | null,
>       interaction?: {
>         enabled?: boolean | null
>       } | null,
>       network?: {
>         enabled?: boolean | null
>       } | null,
>       page?: {
>         enabled?: boolean | null
>       } | null,
>       platform?: {
>         enabled?: boolean | null
>       } | null,
>       screenshot?: {
>         enabled?: boolean | null
>       } | null,
>       system?: {
>         enabled?: boolean | null
>       } | null
>     } | null,
>     enabled?: boolean | null,
>     export?: {
>       otlp?: {
>         destination?: {
>           id?: string | null,
>           name?: string | null
>         } | null,
>         enabled?: boolean | null
>       } | null
>     } | null,
>     storage?: {
>       enabled?: boolean | null
>     } | null
>   } | null | null
> } | null
> ```

> [accordion] browser\_telemetry full type
>
> ```ts theme={null}
> {
>   browser?: {
>     captcha?: {
>       enabled?: boolean | null
>     } | null,
>     connection?: {
>       enabled?: boolean | null
>     } | null,
>     console?: {
>       enabled?: boolean | null
>     } | null,
>     control?: {
>       cdp?: {
>         excluded_methods?: string[] | null
>       } | null,
>       enabled?: boolean | null
>     } | null,
>     interaction?: {
>       enabled?: boolean | null
>     } | null,
>     network?: {
>       enabled?: boolean | null
>     } | null,
>     page?: {
>       enabled?: boolean | null
>     } | null,
>     platform?: {
>       enabled?: boolean | null
>     } | null,
>     screenshot?: {
>       enabled?: boolean | null
>     } | null,
>     system?: {
>       enabled?: boolean | null
>     } | null
>   } | null,
>   enabled?: boolean | null,
>   export?: {
>     otlp?: {
>       destination?: {
>         id?: string | null,
>         name?: string | null
>       } | null,
>       enabled?: boolean | null
>     } | null
>   } | null,
>   storage?: {
>     enabled?: boolean | null
>   } | null
> } | null | null
> ```

> [accordion] choices full type
>
> ```ts theme={null}
> {
>   context?: string | null | null,
>   description?: string | null | null,
>   display_text?: string | null | null,
>   id?: string | null,
>   label?: string | null,
>   masked_destination?: string | null | null,
>   mfa_type?: string | null | null,
>   observed_selector?: string | null | null,
>   type?: string | null
> }[] | null | null
> ```

> [accordion] credential full type
>
> ```ts theme={null}
> {
>   auto?: boolean | null,
>   name?: string | null,
>   path?: string | null,
>   provider?: string | null
> } | null
> ```

> [accordion] discovered\_fields full type
>
> ```ts theme={null}
> {
>   hint?: string | null,
>   label?: string | null,
>   linked_mfa_type?: string | null | null,
>   name?: string | null,
>   placeholder?: string | null,
>   required?: boolean | null,
>   selector?: string | null,
>   type?: string | null
> }[] | null | null
> ```

> [accordion] fields full type
>
> ```ts theme={null}
> {
>   hint?: string | null,
>   id?: string | null,
>   input_mode?: string | null,
>   label?: string | null,
>   observed_selector?: string | null | null,
>   reason?: string | null,
>   ref?: string | null,
>   required?: boolean | null,
>   type?: string | null
> }[] | null | null
> ```

> [accordion] mfa\_options full type
>
> ```ts theme={null}
> {
>   description?: string | null | null,
>   label?: string | null,
>   target?: string | null | null,
>   type?: string | null
> }[] | null | null
> ```

> [accordion] pending\_sso\_buttons full type
>
> ```ts theme={null}
> {
>   label?: string | null,
>   provider?: string | null,
>   selector?: string | null
> }[] | null | null
> ```

> [accordion] sign\_in\_options full type
>
> ```ts theme={null}
> {
>   description?: string | null | null,
>   id?: string | null,
>   label?: string | null
> }[] | null | null
> ```

***

### connections.delete

`auth.connections.delete`

Delete a managed auth connection and stop its health checks and logins. Cannot be undone; the profile stays.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.kernel.api.auth.connections.delete({ id: 'auth_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Auth connection ID |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### connections.exchange

`auth.connections.exchange`

Exchange a login handoff code for a short-lived token, as Kernel's hosted login page does.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.auth.connections.exchange({ id: 'auth_123', code: 'return 1;' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Auth connection ID |
| `code` | `string` | Yes | Handoff code from start endpoint |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `invocation_id` | `string \| null` | No | Invocation ID |
| `jwt` | `string \| null` | No | JWT token with invocation\_id claim (30 minute TTL) |

***

### connections.get

`auth.connections.get`

Get a managed auth connection and its current login flow: status, step, the fields it is waiting for, and hosted\_url or live\_view\_url for a person to finish it. Poll this while a login runs.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.auth.connections.get({ id: 'auth_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Auth connection ID |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `allowed_domains` | `string[] \| null` | No | Additional hostname roots valid for this auth flow, besides the primary domain. Each value allows credential entry on that exact hostname and its subdomains. Leading `www.` and `*.` labels are normalized away. When omitted or empty, credential entry is unrestricted. The following SSO/OAuth provider domains are automatically allowed by default and do not need to be specified: - Google: accounts.google.com - Microsoft/Azure AD: login.microsoftonline.com, login.live.com - Okta: \*.okta.com, \*.oktapreview\.com - Auth0: \*.auth0.com, \*.us.auth0.com, \*.eu.auth0.com, \*.au.auth0.com - Apple: appleid.apple.com - GitHub: github.com - Facebook/Meta: [www.facebook.com](http://www.facebook.com) - LinkedIn: [www.linkedin.com](http://www.linkedin.com) - Amazon Cognito: \*.amazoncognito.com - OneLogin: \*.onelogin.com - Ping Identity: \*.pingone.com, \*.pingidentity.com |
| `auto_reauth` | `boolean \| null` | No | Whether automatic re-authentication is permitted for this connection. This is an opt-in flag only — it does not check whether re-auth is actually feasible. Even when true, re-auth only runs when the system has what it needs to perform it (for example, saved credentials for the required login fields), and only after a scheduled health check detects an expired session — so this flag has no effect when `health_checks` is false. When false, expired sessions detected by a health check are marked as `NEEDS_AUTH` instead of attempting re-auth. |
| `browser` | `object \| null` | No | — |
| `browser_session_id` | `string \| null \| null` | No | ID of the underlying browser session driving the current flow (present when flow in progress). Use this to inspect or terminate the browser session via the `/browsers` API. |
| `browser_telemetry` | `object \| null` | No | — |
| `can_reauth` | `boolean \| null` | No | Whether this connection's stored requirements are eligible for unattended re-authentication. A true value can represent either fully satisfiable requirements or a best-effort attempt. It does not account for whether automatic re-authentication is enabled or parent workflow state such as an active flow or circuit-breaker cooldown, so it does not guarantee an attempt on the next health check. See `can_reauth_reason` for the specific outcome. |
| `can_reauth_reason` | `string \| null` | No | Machine-readable reason for the current value of `can_reauth`. Affirmative values (requirements are eligible for unattended re-authentication): - `external_credential` — an external credential provider is attached - `cua_has_credential` — CUA flow with a stored credential - `has_credential` — Kernel credential is attached (optimistic; plan viability not checked) - `viable_plans_found` — at least one stored login plan can be replayed - `no_requirements_recorded` — no recorded credential requirements to fail against - `totp_reauth_allowed` — TOTP is the only recorded requirement and a stored secret can generate the code - `optimistic_totp_attempt` — TOTP was previously required but no reusable secret is stored; the connection remains eligible for a circuit-breaker-bounded attempt because the site may not challenge returning sessions - `requirements_satisfiable` — recorded requirements contain no recognized blocker Negative values (a human must complete the login flow): - `no_prior_successful_login` — connection has never completed a successful login - `no_credential` — no Kernel or external credential attached - `no_viable_plans` — credential attached but no replayable login plan exists yet - `viable_plans_require_external_action` — stored plans need an external step (email link, push, etc.) - `requires_external_action` — recorded requirements include an external step - `requires_totp_without_secret` — flow needs a TOTP code but no TOTP secret is stored - `requires_sms_code` — flow needs an SMS code that cannot be received automatically - `requires_email_code` — flow needs an email code that cannot be received automatically - `requires_customer_input` — flow needs another field or choice that is unavailable during unattended re-authentication |
| `choices` | `object[] \| null` | No | Canonical choices awaiting selection. Prefer this over pending\_sso\_buttons, mfa\_options, and sign\_in\_options when present. |
| `credential` | `object \| null` | No | — |
| `discovered_fields` | `object[] \| null` | No | Fields awaiting input (present when flow\_step=awaiting\_input; may also be present with awaiting\_external\_action as fallback actions) |
| `domain` | `string \| null` | No | Target domain for authentication |
| `error_code` | `string \| null \| null` | No | Machine-readable error code (present when flow\_status=failed) |
| `error_message` | `string \| null \| null` | No | Error message (present when flow\_status=failed) |
| `external_action_message` | `string \| null \| null` | No | Instructions for external action (present when flow\_step=awaiting\_external\_action) |
| `fields` | `object[] \| null` | No | Canonical fields awaiting input. Prefer this over discovered\_fields when present. |
| `flow_expires_at` | `string \| null \| null` | No | When the current flow expires (null when no flow in progress). A flow past this timestamp is no longer valid and its `flow_status` will be `EXPIRED`. Clients may start a new login to supersede a stale `IN_PROGRESS` flow past this timestamp. |
| `flow_status` | `string \| null \| null` | No | Current flow status (null when no flow in progress) |
| `flow_step` | `string \| null \| null` | No | Current step in the flow (null when no flow in progress) |
| `flow_type` | `string \| null \| null` | No | Type of the current flow (null when no flow in progress) |
| `health_check_interval` | `number \| null \| null` | No | Interval in seconds between automatic health checks. When set, the system periodically verifies the authentication status and triggers re-authentication if needed. Maximum is 86400 (24 hours). Default is 3600 (1 hour) or your plan minimum, whichever is larger. The minimum depends on your plan: Enterprise: 300 (5 minutes), Startup: 1200 (20 minutes), Hobbyist: 3600 (1 hour), Free: 21600 (6 hours). |
| `health_check_unavailable_reason` | `string \| null` | No | Why health checks cannot verify this connection. Present when health checks are enabled but no auth check URL is available; a recent last\_auth\_check\_at is not evidence of a valid session. |
| `health_checks` | `boolean \| null` | No | Whether periodic health checks are enabled for this connection. When false, the system will not automatically verify authentication status, and `auto_reauth` has no effect on the automatic flow (since re-auth is only triggered by a failed scheduled health check). Manually triggering a health check via the API still works regardless of this setting. |
| `hitl` | `boolean \| null` | No | Whether a login blocked by a CAPTCHA the browser cannot solve pauses at AWAITING\_HUMAN\_INTERVENTION so a person can complete it in the live view. |
| `hosted_url` | `string \| null \| null` | No | URL to redirect user to for hosted login (present when flow in progress) |
| `id` | `string \| null` | No | Unique identifier for the auth connection |
| `interaction_id` | `string \| null \| null` | No | Opaque identifier for the current canonical interaction. Required when submitting fields or choices and changes for each new actionable pause. |
| `last_auth_at` | `string \| null` | No | Deprecated alias for `last_auth_check_at`. Despite the name, this is the last health-check timestamp, not the last successful authentication. Use `last_auth_check_at` instead. |
| `last_auth_check_at` | `string \| null` | No | When the most recent auth health check ran for this connection, regardless of outcome. Updated on every health check and does not by itself indicate that the profile is currently authenticated - use `status` for that. May be newer than `flow_expires_at` when a flow is still in progress because health checks continue to run in parallel. |
| `live_view_url` | `string \| null \| null` | No | Browser live view URL for debugging (present when flow in progress) |
| `login_url` | `string \| null` | No | Optional login page URL to skip discovery |
| `mfa_options` | `object[] \| null` | No | MFA method options (present when flow\_step=awaiting\_input; may also be present with awaiting\_external\_action as fallback actions) |
| `pending_sso_buttons` | `object[] \| null` | No | SSO buttons available (present when flow\_step=awaiting\_input; may also be present with awaiting\_external\_action as fallback actions) |
| `post_login_url` | `string \| null` | No | URL where the browser landed after successful login |
| `profile_name` | `string \| null` | No | Name of the profile associated with this auth connection |
| `proxy_id` | `string \| null` | No | Deprecated. Read browser.proxy instead. Retained during migration for existing clients. |
| `record_session` | `boolean \| null` | No | Whether to record browser session replays for this connection by default. Useful for debugging login flows. Can be overridden per-login. |
| `save_credentials` | `boolean \| null` | No | Whether credentials are saved after every successful login. One-time codes (TOTP, SMS, etc.) are not saved. |
| `sign_in_options` | `object[] \| null` | No | Non-MFA choices presented during the auth flow, such as account selection or org pickers (present when flow\_step=awaiting\_input; may also be present with awaiting\_external\_action as fallback actions). |
| `sso_provider` | `string \| null \| null` | No | SSO provider being used (e.g., google, github, microsoft) |
| `status` | `string \| null` | No | Last known authentication status of the managed profile. An inconclusive health check preserves this status and does not verify the current session. |
| `website_error` | `string \| null \| null` | No | Visible error message from the website (e.g., 'Incorrect password'). Present when the website displays an error during login. |

> [accordion] browser full type
>
> ```ts theme={null}
> {
>   captcha_solver?: {
>     enabled?: boolean | null
>   } | null,
>   location?: {
>     locale?: string | null | null
>   } | null,
>   proxy?: {
>     id?: string | null,
>     mode?: string | null,
>     name?: string | null
>   } | null,
>   region?: string | null,
>   stealth?: boolean | null,
>   telemetry?: {
>     browser?: {
>       captcha?: {
>         enabled?: boolean | null
>       } | null,
>       connection?: {
>         enabled?: boolean | null
>       } | null,
>       console?: {
>         enabled?: boolean | null
>       } | null,
>       control?: {
>         cdp?: {
>           excluded_methods?: string[] | null
>         } | null,
>         enabled?: boolean | null
>       } | null,
>       interaction?: {
>         enabled?: boolean | null
>       } | null,
>       network?: {
>         enabled?: boolean | null
>       } | null,
>       page?: {
>         enabled?: boolean | null
>       } | null,
>       platform?: {
>         enabled?: boolean | null
>       } | null,
>       screenshot?: {
>         enabled?: boolean | null
>       } | null,
>       system?: {
>         enabled?: boolean | null
>       } | null
>     } | null,
>     enabled?: boolean | null,
>     export?: {
>       otlp?: {
>         destination?: {
>           id?: string | null,
>           name?: string | null
>         } | null,
>         enabled?: boolean | null
>       } | null
>     } | null,
>     storage?: {
>       enabled?: boolean | null
>     } | null
>   } | null | null
> } | null
> ```

> [accordion] browser\_telemetry full type
>
> ```ts theme={null}
> {
>   browser?: {
>     captcha?: {
>       enabled?: boolean | null
>     } | null,
>     connection?: {
>       enabled?: boolean | null
>     } | null,
>     console?: {
>       enabled?: boolean | null
>     } | null,
>     control?: {
>       cdp?: {
>         excluded_methods?: string[] | null
>       } | null,
>       enabled?: boolean | null
>     } | null,
>     interaction?: {
>       enabled?: boolean | null
>     } | null,
>     network?: {
>       enabled?: boolean | null
>     } | null,
>     page?: {
>       enabled?: boolean | null
>     } | null,
>     platform?: {
>       enabled?: boolean | null
>     } | null,
>     screenshot?: {
>       enabled?: boolean | null
>     } | null,
>     system?: {
>       enabled?: boolean | null
>     } | null
>   } | null,
>   enabled?: boolean | null,
>   export?: {
>     otlp?: {
>       destination?: {
>         id?: string | null,
>         name?: string | null
>       } | null,
>       enabled?: boolean | null
>     } | null
>   } | null,
>   storage?: {
>     enabled?: boolean | null
>   } | null
> } | null | null
> ```

> [accordion] choices full type
>
> ```ts theme={null}
> {
>   context?: string | null | null,
>   description?: string | null | null,
>   display_text?: string | null | null,
>   id?: string | null,
>   label?: string | null,
>   masked_destination?: string | null | null,
>   mfa_type?: string | null | null,
>   observed_selector?: string | null | null,
>   type?: string | null
> }[] | null | null
> ```

> [accordion] credential full type
>
> ```ts theme={null}
> {
>   auto?: boolean | null,
>   name?: string | null,
>   path?: string | null,
>   provider?: string | null
> } | null
> ```

> [accordion] discovered\_fields full type
>
> ```ts theme={null}
> {
>   hint?: string | null,
>   label?: string | null,
>   linked_mfa_type?: string | null | null,
>   name?: string | null,
>   placeholder?: string | null,
>   required?: boolean | null,
>   selector?: string | null,
>   type?: string | null
> }[] | null | null
> ```

> [accordion] fields full type
>
> ```ts theme={null}
> {
>   hint?: string | null,
>   id?: string | null,
>   input_mode?: string | null,
>   label?: string | null,
>   observed_selector?: string | null | null,
>   reason?: string | null,
>   ref?: string | null,
>   required?: boolean | null,
>   type?: string | null
> }[] | null | null
> ```

> [accordion] mfa\_options full type
>
> ```ts theme={null}
> {
>   description?: string | null | null,
>   label?: string | null,
>   target?: string | null | null,
>   type?: string | null
> }[] | null | null
> ```

> [accordion] pending\_sso\_buttons full type
>
> ```ts theme={null}
> {
>   label?: string | null,
>   provider?: string | null,
>   selector?: string | null
> }[] | null | null
> ```

> [accordion] sign\_in\_options full type
>
> ```ts theme={null}
> {
>   description?: string | null | null,
>   id?: string | null,
>   label?: string | null
> }[] | null | null
> ```

***

### connections.list

`auth.connections.list`

List managed auth connections (site logins Kernel keeps signed in), filtered by profile or domain.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.auth.connections.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `profile_name` | `string` | No | Filter by profile name |
| `domain` | `string` | No | Filter by domain |
| `limit` | `number` | No | Maximum number of results to return |
| `offset` | `number` | No | Number of results to skip |
| `query` | `string` | No | Search auth connections by ID, domain, or profile name. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | This page of results. |
| `has_more` | `boolean` | Yes | True when more results follow; pass next\_offset as offset to read them. |
| `next_offset` | `number \| null` | Yes | Value for `offset` that reads the next page, or null on the last page. |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   allowed_domains?: string[] | null,
>   auto_reauth?: boolean | null,
>   browser?: {
>     captcha_solver?: {
>       enabled?: boolean | null
>     } | null,
>     location?: {
>       locale?: string | null | null
>     } | null,
>     proxy?: {
>       id?: string | null,
>       mode?: string | null,
>       name?: string | null
>     } | null,
>     region?: string | null,
>     stealth?: boolean | null,
>     telemetry?: {
>       browser?: {
>         captcha?: {
>           enabled?: boolean | null
>         } | null,
>         connection?: {
>           enabled?: boolean | null
>         } | null,
>         console?: {
>           enabled?: boolean | null
>         } | null,
>         control?: {
>           cdp?: {
>             excluded_methods?: string[] | null
>           } | null,
>           enabled?: boolean | null
>         } | null,
>         interaction?: {
>           enabled?: boolean | null
>         } | null,
>         network?: {
>           enabled?: boolean | null
>         } | null,
>         page?: {
>           enabled?: boolean | null
>         } | null,
>         platform?: {
>           enabled?: boolean | null
>         } | null,
>         screenshot?: {
>           enabled?: boolean | null
>         } | null,
>         system?: {
>           enabled?: boolean | null
>         } | null
>       } | null,
>       enabled?: boolean | null,
>       export?: {
>         otlp?: {
>           destination?: {
>             id?: string | null,
>             name?: string | null
>           } | null,
>           enabled?: boolean | null
>         } | null
>       } | null,
>       storage?: {
>         enabled?: boolean | null
>       } | null
>     } | null | null
>   } | null,
>   browser_session_id?: string | null | null,
>   browser_telemetry?: {
>     browser?: {
>       captcha?: {
>         enabled?: boolean | null
>       } | null,
>       connection?: {
>         enabled?: boolean | null
>       } | null,
>       console?: {
>         enabled?: boolean | null
>       } | null,
>       control?: {
>         cdp?: {
>           excluded_methods?: string[] | null
>         } | null,
>         enabled?: boolean | null
>       } | null,
>       interaction?: {
>         enabled?: boolean | null
>       } | null,
>       network?: {
>         enabled?: boolean | null
>       } | null,
>       page?: {
>         enabled?: boolean | null
>       } | null,
>       platform?: {
>         enabled?: boolean | null
>       } | null,
>       screenshot?: {
>         enabled?: boolean | null
>       } | null,
>       system?: {
>         enabled?: boolean | null
>       } | null
>     } | null,
>     enabled?: boolean | null,
>     export?: {
>       otlp?: {
>         destination?: {
>           id?: string | null,
>           name?: string | null
>         } | null,
>         enabled?: boolean | null
>       } | null
>     } | null,
>     storage?: {
>       enabled?: boolean | null
>     } | null
>   } | null | null,
>   can_reauth?: boolean | null,
>   can_reauth_reason?: string | null,
>   choices?: {
>     context?: string | null | null,
>     description?: string | null | null,
>     display_text?: string | null | null,
>     id?: string | null,
>     label?: string | null,
>     masked_destination?: string | null | null,
>     mfa_type?: string | null | null,
>     observed_selector?: string | null | null,
>     type?: string | null
>   }[] | null | null,
>   credential?: {
>     auto?: boolean | null,
>     name?: string | null,
>     path?: string | null,
>     provider?: string | null
>   } | null,
>   discovered_fields?: {
>     hint?: string | null,
>     label?: string | null,
>     linked_mfa_type?: string | null | null,
>     name?: string | null,
>     placeholder?: string | null,
>     required?: boolean | null,
>     selector?: string | null,
>     type?: string | null
>   }[] | null | null,
>   domain?: string | null,
>   error_code?: string | null | null,
>   error_message?: string | null | null,
>   external_action_message?: string | null | null,
>   fields?: {
>     hint?: string | null,
>     id?: string | null,
>     input_mode?: string | null,
>     label?: string | null,
>     observed_selector?: string | null | null,
>     reason?: string | null,
>     ref?: string | null,
>     required?: boolean | null,
>     type?: string | null
>   }[] | null | null,
>   flow_expires_at?: string | null | null,
>   flow_status?: string | null | null,
>   flow_step?: string | null | null,
>   flow_type?: string | null | null,
>   health_check_interval?: number | null | null,
>   health_check_unavailable_reason?: string | null,
>   health_checks?: boolean | null,
>   hitl?: boolean | null,
>   hosted_url?: string | null | null,
>   id?: string | null,
>   interaction_id?: string | null | null,
>   last_auth_at?: string | null,
>   last_auth_check_at?: string | null,
>   live_view_url?: string | null | null,
>   login_url?: string | null,
>   mfa_options?: {
>     description?: string | null | null,
>     label?: string | null,
>     target?: string | null | null,
>     type?: string | null
>   }[] | null | null,
>   pending_sso_buttons?: {
>     label?: string | null,
>     provider?: string | null,
>     selector?: string | null
>   }[] | null | null,
>   post_login_url?: string | null,
>   profile_name?: string | null,
>   proxy_id?: string | null,
>   record_session?: boolean | null,
>   save_credentials?: boolean | null,
>   sign_in_options?: {
>     description?: string | null | null,
>     id?: string | null,
>     label?: string | null
>   }[] | null | null,
>   sso_provider?: string | null | null,
>   status?: string | null,
>   website_error?: string | null | null
> }[]
> ```

***

### connections.login

`auth.connections.login`

Start a login for a managed auth connection. Returns hosted\_url (and live\_view\_url) for a person to complete it, or logs in by itself when credentials are stored. Then poll auth.connections.get, and send asked-for fields with auth.connections.submit.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.auth.connections.login({ id: 'conn_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Auth connection ID |
| `browser` | `object` | No | — |
| `browser_telemetry` | `object \| null` | No | — |
| `proxy` | `object` | No | — |
| `record_session` | `boolean` | No | Override the connection's default for recording this login's browser session. When omitted, the connection's record\_session default is used. |
| `skill_mode` | `enabled \| disabled` | No | Controls whether this login reads and writes learned domain skills. Automatic reauths inherit the selected mode until a later accepted login sets enabled or omits this field. Defaults to enabled when omitted. |

> [accordion] browser full type
>
> ```ts theme={null}
> {
>   captcha_solver?: {
>     enabled: boolean
>   },
>   location?: {
>     locale?: string | null
>   },
>   proxy?: {
>     id?: string,
>     mode?: direct | default,
>     name?: string
>   },
>   region?: us-east | us-west | eu-west | ap-southeast,
>   stealth?: boolean,
>   telemetry?: {
>     browser?: {
>       captcha?: {
>         enabled?: boolean
>       },
>       connection?: {
>         enabled?: boolean
>       },
>       console?: {
>         enabled?: boolean
>       },
>       control?: {
>         cdp?: {
>           excluded_methods?: (Input.dispatchMouseEvent | Input.dispatchKeyEvent | Input.insertText | Input.imeSetComposition | Input.dispatchTouchEvent | Input.dispatchDragEvent | Input.cancelDragging | Input.emulateTouchFromMouseEvent | Input.synthesizePinchGesture | Input.synthesizeScrollGesture | Input.synthesizeTapGesture | DOM.setFileInputFiles | DOM.focus | DOM.scrollIntoViewIfNeeded | Page.bringToFront | Page.captureScreenshot | Page.captureSnapshot | Page.handleJavaScriptDialog | Page.navigate | Page.navigateToHistoryEntry | Page.reload | Page.printToPDF | Page.startScreencast | Page.stopScreencast | Page.stopLoading | Page.close | Page.setWebLifecycleState | Target.activateTarget | Target.closeTarget | Target.createTarget | Target.createBrowserContext | Target.disposeBrowserContext | Target.openDevTools | Browser.cancelDownload | Browser.close | Browser.setWindowBounds | Browser.setContentsSize | Autofill.trigger)[]
>         },
>         enabled?: boolean
>       },
>       interaction?: {
>         enabled?: boolean
>       },
>       network?: {
>         enabled?: boolean
>       },
>       page?: {
>         enabled?: boolean
>       },
>       platform?: {
>         enabled?: boolean
>       },
>       screenshot?: {
>         enabled?: boolean
>       },
>       system?: {
>         enabled?: boolean
>       }
>     },
>     enabled?: boolean,
>     export?: {
>       otlp?: {
>         destination?: {
>           id?: string,
>           name?: string
>         },
>         enabled?: boolean
>       }
>     },
>     storage?: {
>       enabled?: boolean
>     }
>   } | null
> }
> ```

> [accordion] browser\_telemetry full type
>
> ```ts theme={null}
> {
>   browser?: {
>     captcha?: {
>       enabled?: boolean
>     },
>     connection?: {
>       enabled?: boolean
>     },
>     console?: {
>       enabled?: boolean
>     },
>     control?: {
>       cdp?: {
>         excluded_methods?: (Input.dispatchMouseEvent | Input.dispatchKeyEvent | Input.insertText | Input.imeSetComposition | Input.dispatchTouchEvent | Input.dispatchDragEvent | Input.cancelDragging | Input.emulateTouchFromMouseEvent | Input.synthesizePinchGesture | Input.synthesizeScrollGesture | Input.synthesizeTapGesture | DOM.setFileInputFiles | DOM.focus | DOM.scrollIntoViewIfNeeded | Page.bringToFront | Page.captureScreenshot | Page.captureSnapshot | Page.handleJavaScriptDialog | Page.navigate | Page.navigateToHistoryEntry | Page.reload | Page.printToPDF | Page.startScreencast | Page.stopScreencast | Page.stopLoading | Page.close | Page.setWebLifecycleState | Target.activateTarget | Target.closeTarget | Target.createTarget | Target.createBrowserContext | Target.disposeBrowserContext | Target.openDevTools | Browser.cancelDownload | Browser.close | Browser.setWindowBounds | Browser.setContentsSize | Autofill.trigger)[]
>       },
>       enabled?: boolean
>     },
>     interaction?: {
>       enabled?: boolean
>     },
>     network?: {
>       enabled?: boolean
>     },
>     page?: {
>       enabled?: boolean
>     },
>     platform?: {
>       enabled?: boolean
>     },
>     screenshot?: {
>       enabled?: boolean
>     },
>     system?: {
>       enabled?: boolean
>     }
>   },
>   enabled?: boolean,
>   export?: {
>     otlp?: {
>       destination?: {
>         id?: string,
>         name?: string
>       },
>       enabled?: boolean
>     }
>   },
>   storage?: {
>     enabled?: boolean
>   }
> } | null
> ```

> [accordion] proxy full type
>
> ```ts theme={null}
> {
>   id?: string,
>   name?: string
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `flow_expires_at` | `string \| null` | No | When the login flow expires |
| `flow_type` | `string \| null` | No | Type of login flow started |
| `handoff_code` | `string \| null` | No | One-time code for handoff (internal use) |
| `hosted_url` | `string \| null` | No | URL to redirect user to for login |
| `id` | `string \| null` | No | Auth connection ID |
| `live_view_url` | `string \| null` | No | Browser live view URL for watching the login flow |

***

### connections.submit

`auth.connections.submit`

Send the values a running login asks for (a username, password, one-time code, or a choice) to a managed auth connection. Poll auth.connections.get for the result.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.auth.connections.submit({ id: 'auth_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Auth connection ID |
| `field_values` | `Record<string, string>` | No | Canonical map of field ID to submitted value. |
| `fields` | `Record<string, string>` | No | Map of field name to value |
| `interaction_id` | `string` | No | Opaque interaction ID returned with canonical fields and choices. Required for canonical submissions. |
| `mfa_option_id` | `string` | No | The MFA method type to select (when mfa\_options were returned) |
| `selected_choice_id` | `string` | No | Canonical choice ID selected by the user. |
| `sign_in_option_id` | `string` | No | The sign-in option ID to select (when sign\_in\_options were returned) |
| `sso_button_selector` | `string` | No | XPath selector for the SSO button to click (ODA). Use sso\_provider instead for CUA. |
| `sso_provider` | `string` | No | SSO provider to click, matching the provider field from pending\_sso\_buttons (e.g., "google", "github"). Cannot be used with sso\_button\_selector. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `accepted` | `boolean \| null` | No | Whether the submission was accepted for processing |

***

### connections.timeline

`auth.connections.timeline`

List a managed auth connection's history (logins, re-auths, health checks), newest first.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.auth.connections.timeline({ id: 'auth_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Auth connection ID |
| `type` | `login \| reauth \| health_check` | No | Filter the timeline to a single event type. |
| `limit` | `number` | No | Maximum number of events to return |
| `offset` | `number` | No | Number of events to skip |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | This page of results. |
| `has_more` | `boolean` | Yes | True when more results follow; pass next\_offset as offset to read them. |
| `next_offset` | `number \| null` | Yes | Value for `offset` that reads the next page, or null on the last page. |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   browser_session_id?: string | null,
>   completed_at?: string | null,
>   error_code?: string | null,
>   error_message?: string | null,
>   id?: string | null,
>   previous_status?: string | null,
>   replay_id?: string | null,
>   status?: string | null,
>   step?: string | null,
>   telemetry_captured?: boolean | null,
>   timestamp?: string | null,
>   type?: string | null,
>   updated_at?: string | null,
>   website_error?: string | null
> }[]
> ```

***

### connections.update

`auth.connections.update`

Change a managed auth connection's settings: health checks, auto re-auth, credential, proxy, login URL.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.auth.connections.update({ id: 'auth_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Auth connection ID |
| `allowed_domains` | `string[]` | No | Additional hostname roots valid for this auth flow. Each value allows credential entry on that exact hostname and its subdomains; leading `www.` and `*.` labels are normalized away. An empty list leaves credential entry unrestricted. Replaces the existing list. |
| `auto_reauth` | `boolean` | No | Whether automatic re-authentication is permitted for this connection. This is an opt-in flag only — it does not check whether re-auth is actually feasible. Even when true, re-auth only runs when the system has what it needs to perform it (for example, saved credentials for the required login fields), and only after a scheduled health check detects an expired session — so this flag has no effect when `health_checks` is false. When false, expired sessions detected by a health check are marked as `NEEDS_AUTH` instead of attempting re-auth. |
| `browser` | `object` | No | — |
| `browser_telemetry` | `object \| null` | No | — |
| `credential` | `object` | No | — |
| `health_check_interval` | `number` | No | Interval in seconds between automatic health checks |
| `health_checks` | `boolean` | No | Whether periodic health checks are enabled. When set to false, the system will not automatically verify authentication status, and `auto_reauth` has no effect on the automatic flow (since re-auth is only triggered by a failed scheduled health check). |
| `hitl` | `boolean` | No | Whether a login blocked by a CAPTCHA the browser cannot solve pauses for a person instead of failing |
| `login_url` | `string` | No | Login page URL. Set to empty string to clear. |
| `proxy` | `object` | No | — |
| `record_session` | `boolean` | No | Whether to record browser sessions for this connection by default |
| `save_credentials` | `boolean` | No | Whether to save credentials after every successful login |

> [accordion] browser full type
>
> ```ts theme={null}
> {
>   captcha_solver?: {
>     enabled: boolean
>   },
>   location?: {
>     locale?: string | null
>   },
>   proxy?: {
>     id?: string,
>     mode?: direct | default,
>     name?: string
>   },
>   region?: us-east | us-west | eu-west | ap-southeast,
>   stealth?: boolean,
>   telemetry?: {
>     browser?: {
>       captcha?: {
>         enabled?: boolean
>       },
>       connection?: {
>         enabled?: boolean
>       },
>       console?: {
>         enabled?: boolean
>       },
>       control?: {
>         cdp?: {
>           excluded_methods?: (Input.dispatchMouseEvent | Input.dispatchKeyEvent | Input.insertText | Input.imeSetComposition | Input.dispatchTouchEvent | Input.dispatchDragEvent | Input.cancelDragging | Input.emulateTouchFromMouseEvent | Input.synthesizePinchGesture | Input.synthesizeScrollGesture | Input.synthesizeTapGesture | DOM.setFileInputFiles | DOM.focus | DOM.scrollIntoViewIfNeeded | Page.bringToFront | Page.captureScreenshot | Page.captureSnapshot | Page.handleJavaScriptDialog | Page.navigate | Page.navigateToHistoryEntry | Page.reload | Page.printToPDF | Page.startScreencast | Page.stopScreencast | Page.stopLoading | Page.close | Page.setWebLifecycleState | Target.activateTarget | Target.closeTarget | Target.createTarget | Target.createBrowserContext | Target.disposeBrowserContext | Target.openDevTools | Browser.cancelDownload | Browser.close | Browser.setWindowBounds | Browser.setContentsSize | Autofill.trigger)[]
>         },
>         enabled?: boolean
>       },
>       interaction?: {
>         enabled?: boolean
>       },
>       network?: {
>         enabled?: boolean
>       },
>       page?: {
>         enabled?: boolean
>       },
>       platform?: {
>         enabled?: boolean
>       },
>       screenshot?: {
>         enabled?: boolean
>       },
>       system?: {
>         enabled?: boolean
>       }
>     },
>     enabled?: boolean,
>     export?: {
>       otlp?: {
>         destination?: {
>           id?: string,
>           name?: string
>         },
>         enabled?: boolean
>       }
>     },
>     storage?: {
>       enabled?: boolean
>     }
>   } | null
> }
> ```

> [accordion] browser\_telemetry full type
>
> ```ts theme={null}
> {
>   browser?: {
>     captcha?: {
>       enabled?: boolean
>     },
>     connection?: {
>       enabled?: boolean
>     },
>     console?: {
>       enabled?: boolean
>     },
>     control?: {
>       cdp?: {
>         excluded_methods?: (Input.dispatchMouseEvent | Input.dispatchKeyEvent | Input.insertText | Input.imeSetComposition | Input.dispatchTouchEvent | Input.dispatchDragEvent | Input.cancelDragging | Input.emulateTouchFromMouseEvent | Input.synthesizePinchGesture | Input.synthesizeScrollGesture | Input.synthesizeTapGesture | DOM.setFileInputFiles | DOM.focus | DOM.scrollIntoViewIfNeeded | Page.bringToFront | Page.captureScreenshot | Page.captureSnapshot | Page.handleJavaScriptDialog | Page.navigate | Page.navigateToHistoryEntry | Page.reload | Page.printToPDF | Page.startScreencast | Page.stopScreencast | Page.stopLoading | Page.close | Page.setWebLifecycleState | Target.activateTarget | Target.closeTarget | Target.createTarget | Target.createBrowserContext | Target.disposeBrowserContext | Target.openDevTools | Browser.cancelDownload | Browser.close | Browser.setWindowBounds | Browser.setContentsSize | Autofill.trigger)[]
>       },
>       enabled?: boolean
>     },
>     interaction?: {
>       enabled?: boolean
>     },
>     network?: {
>       enabled?: boolean
>     },
>     page?: {
>       enabled?: boolean
>     },
>     platform?: {
>       enabled?: boolean
>     },
>     screenshot?: {
>       enabled?: boolean
>     },
>     system?: {
>       enabled?: boolean
>     }
>   },
>   enabled?: boolean,
>   export?: {
>     otlp?: {
>       destination?: {
>         id?: string,
>         name?: string
>       },
>       enabled?: boolean
>     }
>   },
>   storage?: {
>     enabled?: boolean
>   }
> } | null
> ```

> [accordion] credential full type
>
> ```ts theme={null}
> {
>   auto?: boolean,
>   name?: string,
>   path?: string,
>   provider?: string
> }
> ```

> [accordion] proxy full type
>
> ```ts theme={null}
> {
>   id?: string,
>   name?: string
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `allowed_domains` | `string[] \| null` | No | Additional hostname roots valid for this auth flow, besides the primary domain. Each value allows credential entry on that exact hostname and its subdomains. Leading `www.` and `*.` labels are normalized away. When omitted or empty, credential entry is unrestricted. The following SSO/OAuth provider domains are automatically allowed by default and do not need to be specified: - Google: accounts.google.com - Microsoft/Azure AD: login.microsoftonline.com, login.live.com - Okta: \*.okta.com, \*.oktapreview\.com - Auth0: \*.auth0.com, \*.us.auth0.com, \*.eu.auth0.com, \*.au.auth0.com - Apple: appleid.apple.com - GitHub: github.com - Facebook/Meta: [www.facebook.com](http://www.facebook.com) - LinkedIn: [www.linkedin.com](http://www.linkedin.com) - Amazon Cognito: \*.amazoncognito.com - OneLogin: \*.onelogin.com - Ping Identity: \*.pingone.com, \*.pingidentity.com |
| `auto_reauth` | `boolean \| null` | No | Whether automatic re-authentication is permitted for this connection. This is an opt-in flag only — it does not check whether re-auth is actually feasible. Even when true, re-auth only runs when the system has what it needs to perform it (for example, saved credentials for the required login fields), and only after a scheduled health check detects an expired session — so this flag has no effect when `health_checks` is false. When false, expired sessions detected by a health check are marked as `NEEDS_AUTH` instead of attempting re-auth. |
| `browser` | `object \| null` | No | — |
| `browser_session_id` | `string \| null \| null` | No | ID of the underlying browser session driving the current flow (present when flow in progress). Use this to inspect or terminate the browser session via the `/browsers` API. |
| `browser_telemetry` | `object \| null` | No | — |
| `can_reauth` | `boolean \| null` | No | Whether this connection's stored requirements are eligible for unattended re-authentication. A true value can represent either fully satisfiable requirements or a best-effort attempt. It does not account for whether automatic re-authentication is enabled or parent workflow state such as an active flow or circuit-breaker cooldown, so it does not guarantee an attempt on the next health check. See `can_reauth_reason` for the specific outcome. |
| `can_reauth_reason` | `string \| null` | No | Machine-readable reason for the current value of `can_reauth`. Affirmative values (requirements are eligible for unattended re-authentication): - `external_credential` — an external credential provider is attached - `cua_has_credential` — CUA flow with a stored credential - `has_credential` — Kernel credential is attached (optimistic; plan viability not checked) - `viable_plans_found` — at least one stored login plan can be replayed - `no_requirements_recorded` — no recorded credential requirements to fail against - `totp_reauth_allowed` — TOTP is the only recorded requirement and a stored secret can generate the code - `optimistic_totp_attempt` — TOTP was previously required but no reusable secret is stored; the connection remains eligible for a circuit-breaker-bounded attempt because the site may not challenge returning sessions - `requirements_satisfiable` — recorded requirements contain no recognized blocker Negative values (a human must complete the login flow): - `no_prior_successful_login` — connection has never completed a successful login - `no_credential` — no Kernel or external credential attached - `no_viable_plans` — credential attached but no replayable login plan exists yet - `viable_plans_require_external_action` — stored plans need an external step (email link, push, etc.) - `requires_external_action` — recorded requirements include an external step - `requires_totp_without_secret` — flow needs a TOTP code but no TOTP secret is stored - `requires_sms_code` — flow needs an SMS code that cannot be received automatically - `requires_email_code` — flow needs an email code that cannot be received automatically - `requires_customer_input` — flow needs another field or choice that is unavailable during unattended re-authentication |
| `choices` | `object[] \| null` | No | Canonical choices awaiting selection. Prefer this over pending\_sso\_buttons, mfa\_options, and sign\_in\_options when present. |
| `credential` | `object \| null` | No | — |
| `discovered_fields` | `object[] \| null` | No | Fields awaiting input (present when flow\_step=awaiting\_input; may also be present with awaiting\_external\_action as fallback actions) |
| `domain` | `string \| null` | No | Target domain for authentication |
| `error_code` | `string \| null \| null` | No | Machine-readable error code (present when flow\_status=failed) |
| `error_message` | `string \| null \| null` | No | Error message (present when flow\_status=failed) |
| `external_action_message` | `string \| null \| null` | No | Instructions for external action (present when flow\_step=awaiting\_external\_action) |
| `fields` | `object[] \| null` | No | Canonical fields awaiting input. Prefer this over discovered\_fields when present. |
| `flow_expires_at` | `string \| null \| null` | No | When the current flow expires (null when no flow in progress). A flow past this timestamp is no longer valid and its `flow_status` will be `EXPIRED`. Clients may start a new login to supersede a stale `IN_PROGRESS` flow past this timestamp. |
| `flow_status` | `string \| null \| null` | No | Current flow status (null when no flow in progress) |
| `flow_step` | `string \| null \| null` | No | Current step in the flow (null when no flow in progress) |
| `flow_type` | `string \| null \| null` | No | Type of the current flow (null when no flow in progress) |
| `health_check_interval` | `number \| null \| null` | No | Interval in seconds between automatic health checks. When set, the system periodically verifies the authentication status and triggers re-authentication if needed. Maximum is 86400 (24 hours). Default is 3600 (1 hour) or your plan minimum, whichever is larger. The minimum depends on your plan: Enterprise: 300 (5 minutes), Startup: 1200 (20 minutes), Hobbyist: 3600 (1 hour), Free: 21600 (6 hours). |
| `health_check_unavailable_reason` | `string \| null` | No | Why health checks cannot verify this connection. Present when health checks are enabled but no auth check URL is available; a recent last\_auth\_check\_at is not evidence of a valid session. |
| `health_checks` | `boolean \| null` | No | Whether periodic health checks are enabled for this connection. When false, the system will not automatically verify authentication status, and `auto_reauth` has no effect on the automatic flow (since re-auth is only triggered by a failed scheduled health check). Manually triggering a health check via the API still works regardless of this setting. |
| `hitl` | `boolean \| null` | No | Whether a login blocked by a CAPTCHA the browser cannot solve pauses at AWAITING\_HUMAN\_INTERVENTION so a person can complete it in the live view. |
| `hosted_url` | `string \| null \| null` | No | URL to redirect user to for hosted login (present when flow in progress) |
| `id` | `string \| null` | No | Unique identifier for the auth connection |
| `interaction_id` | `string \| null \| null` | No | Opaque identifier for the current canonical interaction. Required when submitting fields or choices and changes for each new actionable pause. |
| `last_auth_at` | `string \| null` | No | Deprecated alias for `last_auth_check_at`. Despite the name, this is the last health-check timestamp, not the last successful authentication. Use `last_auth_check_at` instead. |
| `last_auth_check_at` | `string \| null` | No | When the most recent auth health check ran for this connection, regardless of outcome. Updated on every health check and does not by itself indicate that the profile is currently authenticated - use `status` for that. May be newer than `flow_expires_at` when a flow is still in progress because health checks continue to run in parallel. |
| `live_view_url` | `string \| null \| null` | No | Browser live view URL for debugging (present when flow in progress) |
| `login_url` | `string \| null` | No | Optional login page URL to skip discovery |
| `mfa_options` | `object[] \| null` | No | MFA method options (present when flow\_step=awaiting\_input; may also be present with awaiting\_external\_action as fallback actions) |
| `pending_sso_buttons` | `object[] \| null` | No | SSO buttons available (present when flow\_step=awaiting\_input; may also be present with awaiting\_external\_action as fallback actions) |
| `post_login_url` | `string \| null` | No | URL where the browser landed after successful login |
| `profile_name` | `string \| null` | No | Name of the profile associated with this auth connection |
| `proxy_id` | `string \| null` | No | Deprecated. Read browser.proxy instead. Retained during migration for existing clients. |
| `record_session` | `boolean \| null` | No | Whether to record browser session replays for this connection by default. Useful for debugging login flows. Can be overridden per-login. |
| `save_credentials` | `boolean \| null` | No | Whether credentials are saved after every successful login. One-time codes (TOTP, SMS, etc.) are not saved. |
| `sign_in_options` | `object[] \| null` | No | Non-MFA choices presented during the auth flow, such as account selection or org pickers (present when flow\_step=awaiting\_input; may also be present with awaiting\_external\_action as fallback actions). |
| `sso_provider` | `string \| null \| null` | No | SSO provider being used (e.g., google, github, microsoft) |
| `status` | `string \| null` | No | Last known authentication status of the managed profile. An inconclusive health check preserves this status and does not verify the current session. |
| `website_error` | `string \| null \| null` | No | Visible error message from the website (e.g., 'Incorrect password'). Present when the website displays an error during login. |

> [accordion] browser full type
>
> ```ts theme={null}
> {
>   captcha_solver?: {
>     enabled?: boolean | null
>   } | null,
>   location?: {
>     locale?: string | null | null
>   } | null,
>   proxy?: {
>     id?: string | null,
>     mode?: string | null,
>     name?: string | null
>   } | null,
>   region?: string | null,
>   stealth?: boolean | null,
>   telemetry?: {
>     browser?: {
>       captcha?: {
>         enabled?: boolean | null
>       } | null,
>       connection?: {
>         enabled?: boolean | null
>       } | null,
>       console?: {
>         enabled?: boolean | null
>       } | null,
>       control?: {
>         cdp?: {
>           excluded_methods?: string[] | null
>         } | null,
>         enabled?: boolean | null
>       } | null,
>       interaction?: {
>         enabled?: boolean | null
>       } | null,
>       network?: {
>         enabled?: boolean | null
>       } | null,
>       page?: {
>         enabled?: boolean | null
>       } | null,
>       platform?: {
>         enabled?: boolean | null
>       } | null,
>       screenshot?: {
>         enabled?: boolean | null
>       } | null,
>       system?: {
>         enabled?: boolean | null
>       } | null
>     } | null,
>     enabled?: boolean | null,
>     export?: {
>       otlp?: {
>         destination?: {
>           id?: string | null,
>           name?: string | null
>         } | null,
>         enabled?: boolean | null
>       } | null
>     } | null,
>     storage?: {
>       enabled?: boolean | null
>     } | null
>   } | null | null
> } | null
> ```

> [accordion] browser\_telemetry full type
>
> ```ts theme={null}
> {
>   browser?: {
>     captcha?: {
>       enabled?: boolean | null
>     } | null,
>     connection?: {
>       enabled?: boolean | null
>     } | null,
>     console?: {
>       enabled?: boolean | null
>     } | null,
>     control?: {
>       cdp?: {
>         excluded_methods?: string[] | null
>       } | null,
>       enabled?: boolean | null
>     } | null,
>     interaction?: {
>       enabled?: boolean | null
>     } | null,
>     network?: {
>       enabled?: boolean | null
>     } | null,
>     page?: {
>       enabled?: boolean | null
>     } | null,
>     platform?: {
>       enabled?: boolean | null
>     } | null,
>     screenshot?: {
>       enabled?: boolean | null
>     } | null,
>     system?: {
>       enabled?: boolean | null
>     } | null
>   } | null,
>   enabled?: boolean | null,
>   export?: {
>     otlp?: {
>       destination?: {
>         id?: string | null,
>         name?: string | null
>       } | null,
>       enabled?: boolean | null
>     } | null
>   } | null,
>   storage?: {
>     enabled?: boolean | null
>   } | null
> } | null | null
> ```

> [accordion] choices full type
>
> ```ts theme={null}
> {
>   context?: string | null | null,
>   description?: string | null | null,
>   display_text?: string | null | null,
>   id?: string | null,
>   label?: string | null,
>   masked_destination?: string | null | null,
>   mfa_type?: string | null | null,
>   observed_selector?: string | null | null,
>   type?: string | null
> }[] | null | null
> ```

> [accordion] credential full type
>
> ```ts theme={null}
> {
>   auto?: boolean | null,
>   name?: string | null,
>   path?: string | null,
>   provider?: string | null
> } | null
> ```

> [accordion] discovered\_fields full type
>
> ```ts theme={null}
> {
>   hint?: string | null,
>   label?: string | null,
>   linked_mfa_type?: string | null | null,
>   name?: string | null,
>   placeholder?: string | null,
>   required?: boolean | null,
>   selector?: string | null,
>   type?: string | null
> }[] | null | null
> ```

> [accordion] fields full type
>
> ```ts theme={null}
> {
>   hint?: string | null,
>   id?: string | null,
>   input_mode?: string | null,
>   label?: string | null,
>   observed_selector?: string | null | null,
>   reason?: string | null,
>   ref?: string | null,
>   required?: boolean | null,
>   type?: string | null
> }[] | null | null
> ```

> [accordion] mfa\_options full type
>
> ```ts theme={null}
> {
>   description?: string | null | null,
>   label?: string | null,
>   target?: string | null | null,
>   type?: string | null
> }[] | null | null
> ```

> [accordion] pending\_sso\_buttons full type
>
> ```ts theme={null}
> {
>   label?: string | null,
>   provider?: string | null,
>   selector?: string | null
> }[] | null | null
> ```

> [accordion] sign\_in\_options full type
>
> ```ts theme={null}
> {
>   description?: string | null | null,
>   id?: string | null,
>   label?: string | null
> }[] | null | null
> ```

***

### context.get

`auth.context.get`

Show who the API key is: its organization, project and scopes.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.auth.context.get({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `authentication` | `object \| null` | No | — |
| `authorization` | `object \| null` | No | — |
| `organization` | `object \| null` | No | — |
| `principal` | `object \| null` | No | — |
| `workload_identity` | `object \| null` | No | — |

> [accordion] authentication full type
>
> ```ts theme={null}
> {
>   credential_id?: string | null | null,
>   method?: string | null,
>   source?: string | null
> } | null
> ```

> [accordion] authorization full type
>
> ```ts theme={null}
> {
>   credential_scope?: {
>     project_id?: string | null | null
>   } | null,
>   effective_policy?: {
>     statements?: {
>       action?: string | null,
>       condition?: {
>         key?: string | null,
>         operator?: string | null,
>         values?: string[] | null
>       } | null,
>       resource?: string | null
>     }[] | null
>   } | null,
>   effective_scope?: {
>     project_id?: string | null | null
>   } | null
> } | null
> ```

> [accordion] organization full type
>
> ```ts theme={null}
> {
>   id?: string | null
> } | null
> ```

> [accordion] principal full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   type?: string | null
> } | null
> ```

> [accordion] workload\_identity full type
>
> ```ts theme={null}
> {
>   external_subject_digest?: string | null,
>   federation_rule_id?: string | null,
>   issuer_id?: string | null
> } | null
> ```

***

## Browser Pools

### acquire

`browserPools.acquire`

Take a ready browser from a pool (waits up to acquire\_timeout\_seconds). Returns null when none freed up in time; call again. Give it back with browserPools.release.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browserPools.acquire({ id_or_name: 'my-pool' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser pool ID or name |
| `acquire_timeout_seconds` | `number` | No | Maximum number of seconds to wait for a browser to be available. Defaults to the calculated time it would take to fill the pool at the currently configured fill rate. |
| `name` | `string` | No | Optional human-readable name for the acquired browser session, used to find it later in the dashboard. Must be unique among active sessions within the pool's project. Applies to this lease only and is cleared when the browser is released back to the pool. |
| `profile` | `object` | No | Optional profile to load before returning the acquired browser. The pool itself must not already have a profile configured. A browser loaded with an acquire-time profile is destroyed and replaced on release instead of being reused, so profile state cannot leak into another lease. Set save\_changes to persist changes when that browser is destroyed. |
| `start_replay` | `boolean` | No | Start replay recording immediately for the acquired browser. Omit to use the pool's configured default. |
| `start_url` | `string` | No | Optional URL to navigate the acquired browser to. Overrides the pool's start\_url for this acquire only. Best-effort: failures to navigate do not fail the acquire. |
| `tags` | `Record<string, string>` | No | — |
| `telemetry` | `object \| null` | No | — |

> [accordion] profile full type
>
> ```ts theme={null}
> {
>   id?: string,
>   name?: string,
>   save_changes?: boolean
> }
> ```

> [accordion] telemetry full type
>
> ```ts theme={null}
> {
>   browser?: {
>     captcha?: {
>       enabled?: boolean
>     },
>     connection?: {
>       enabled?: boolean
>     },
>     console?: {
>       enabled?: boolean
>     },
>     control?: {
>       cdp?: {
>         excluded_methods?: (Input.dispatchMouseEvent | Input.dispatchKeyEvent | Input.insertText | Input.imeSetComposition | Input.dispatchTouchEvent | Input.dispatchDragEvent | Input.cancelDragging | Input.emulateTouchFromMouseEvent | Input.synthesizePinchGesture | Input.synthesizeScrollGesture | Input.synthesizeTapGesture | DOM.setFileInputFiles | DOM.focus | DOM.scrollIntoViewIfNeeded | Page.bringToFront | Page.captureScreenshot | Page.captureSnapshot | Page.handleJavaScriptDialog | Page.navigate | Page.navigateToHistoryEntry | Page.reload | Page.printToPDF | Page.startScreencast | Page.stopScreencast | Page.stopLoading | Page.close | Page.setWebLifecycleState | Target.activateTarget | Target.closeTarget | Target.createTarget | Target.createBrowserContext | Target.disposeBrowserContext | Target.openDevTools | Browser.cancelDownload | Browser.close | Browser.setWindowBounds | Browser.setContentsSize | Autofill.trigger)[]
>       },
>       enabled?: boolean
>     },
>     interaction?: {
>       enabled?: boolean
>     },
>     network?: {
>       enabled?: boolean
>     },
>     page?: {
>       enabled?: boolean
>     },
>     platform?: {
>       enabled?: boolean
>     },
>     screenshot?: {
>       enabled?: boolean
>     },
>     system?: {
>       enabled?: boolean
>     }
>   },
>   enabled?: boolean,
>   export?: {
>     otlp?: {
>       destination?: {
>         id?: string,
>         name?: string
>       },
>       enabled?: boolean
>     }
>   },
>   storage?: {
>     enabled?: boolean
>   }
> } | null
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `base_url` | `string \| null` | No | Metro-API HTTP base URL for this browser session. |
| `browser_live_view_url` | `string \| null` | No | Remote URL for live viewing the browser session. Only available for non-headless browsers. |
| `captcha_solver` | `object \| null` | No | — |
| `cdp_ws_url` | `string \| null` | No | Websocket URL for Chrome DevTools Protocol connections to the browser session |
| `chrome_policy` | `object \| null` | No | Custom Chrome enterprise policy overrides that were applied to this browser session, if any. Echoed back for verification. Keys are Chrome enterprise policy names. |
| `cost` | `object \| null` | No | — |
| `created_at` | `string \| null` | No | When the browser session was created. |
| `deleted_at` | `string \| null` | No | When the browser session was soft-deleted. Only present for deleted sessions. |
| `fingerprint` | `object \| null` | No | — |
| `gpu` | `boolean \| null` | No | Whether GPU acceleration is enabled for the browser session (only supported for headful sessions). |
| `headless` | `boolean \| null` | No | Whether the browser session is running in headless mode. |
| `kiosk_mode` | `boolean \| null` | No | Whether the browser session is running in kiosk mode. |
| `leased_at` | `string \| null` | No | When the pooled browser session was last leased. Only present for leased pooled sessions. |
| `location` | `object \| null` | No | — |
| `memory` | `string \| null` | No | — |
| `name` | `string \| null` | No | Human-readable name of the browser session, if one was set at creation. |
| `network` | `object \| null` | No | — |
| `pool` | `object \| null` | No | — |
| `profile` | `object \| null` | No | — |
| `profile_save_changes` | `boolean \| null` | No | Whether changes made during this browser session are saved back to its profile when the session ends. Omitted when no profile is attached. |
| `proxy` | `object \| null` | No | — |
| `proxy_id` | `string \| null` | No | ID of the proxy associated with this browser session, if any. Deprecated in favor of proxy. |
| `region` | `string \| null` | No | — |
| `replay` | `object \| null` | No | — |
| `session_id` | `string \| null` | No | Unique identifier for the browser session |
| `start_url` | `string \| null` | No | URL the session was most recently asked to navigate to, if any. Recorded for debugging. Navigation is fire-and-forget — the URL is dispatched to the browser without waiting for it to load, and any errors (DNS failure, bad status, timeout) are silently dropped. Captures what was requested, not what the browser actually loaded. |
| `stealth` | `boolean \| null` | No | Whether the browser session has CAPTCHA solving enabled, in which case proxy.mode=default uses Kernel's default stealth proxy. A browser created with only captcha\_solver reports true with proxy.mode=direct. Deprecated in favor of captcha\_solver and proxy. |
| `tags` | `Record<string, string> \| null` | No | — |
| `telemetry` | `object \| null` | No | — |
| `timeout_seconds` | `number \| null` | No | The number of seconds of inactivity before the browser session is terminated. |
| `usage` | `object \| null` | No | — |
| `usage_status` | `string \| null` | No | — |
| `vaults` | `object[] \| null` | No | Vaults linked when the browser session was created. |
| `video_memory` | `string \| null` | No | — |
| `viewport` | `object \| null` | No | — |
| `webdriver_ws_url` | `string \| null` | No | Websocket URL for WebDriver BiDi connections to the browser session |

> [accordion] captcha\_solver full type
>
> ```ts theme={null}
> {
>   enabled?: boolean | null
> } | null
> ```

> [accordion] chrome\_policy full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] cost full type
>
> ```ts theme={null}
> {
>   as_of?: string | null,
>   estimated_usage_spend_usd?: string | null,
>   status?: string | null
> } | null
> ```

> [accordion] fingerprint full type
>
> ```ts theme={null}
> {
>   os?: string | null
> } | null
> ```

> [accordion] location full type
>
> ```ts theme={null}
> {
>   locale?: string | null,
>   locale_source?: string | null,
>   timezone?: string | null,
>   timezone_source?: string | null
> } | null
> ```

> [accordion] network full type
>
> ```ts theme={null}
> {
>   allowed_hosts?: string[] | null,
>   allowlist_state?: {
>     base_revision?: string | null,
>     mutation_id?: string | null,
>     revision?: string | null
>   } | null,
>   private_hosts?: string[] | null,
>   proxy_routes?: {
>     hosts?: string[] | null,
>     proxy?: {
>       id?: string | null,
>       name?: string | null
>     } | null
>   }[] | null
> } | null
> ```

> [accordion] pool full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   name?: string | null
> } | null
> ```

> [accordion] profile full type
>
> ```ts theme={null}
> {
>   created_at?: string | null,
>   id?: string | null,
>   last_used_at?: string | null,
>   name?: string | null | null,
>   updated_at?: string | null
> } | null
> ```

> [accordion] proxy full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   mode?: string | null,
>   name?: string | null
> } | null
> ```

> [accordion] replay full type
>
> ```ts theme={null}
> {
>   finished_at?: string | null | null,
>   replay_id?: string | null,
>   replay_view_url?: string | null,
>   started_at?: string | null | null
> } | null
> ```

> [accordion] telemetry full type
>
> ```ts theme={null}
> {
>   browser?: {
>     captcha?: {
>       enabled?: boolean | null
>     } | null,
>     connection?: {
>       enabled?: boolean | null
>     } | null,
>     console?: {
>       enabled?: boolean | null
>     } | null,
>     control?: {
>       cdp?: {
>         excluded_methods?: string[] | null
>       } | null,
>       enabled?: boolean | null
>     } | null,
>     interaction?: {
>       enabled?: boolean | null
>     } | null,
>     network?: {
>       enabled?: boolean | null
>     } | null,
>     page?: {
>       enabled?: boolean | null
>     } | null,
>     platform?: {
>       enabled?: boolean | null
>     } | null,
>     screenshot?: {
>       enabled?: boolean | null
>     } | null,
>     system?: {
>       enabled?: boolean | null
>     } | null
>   } | null,
>   export?: {
>     otlp?: {
>       destination?: string | null,
>       enabled?: boolean | null
>     } | null
>   } | null,
>   storage?: {
>     enabled?: boolean | null
>   } | null
> } | null | null
> ```

> [accordion] usage full type
>
> ```ts theme={null}
> {
>   uptime_ms?: number | null
> } | null
> ```

> [accordion] vaults full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   name?: string | null
> }[] | null
> ```

> [accordion] viewport full type
>
> ```ts theme={null}
> {
>   height?: number | null,
>   refresh_rate?: number | null,
>   width?: number | null
> } | null
> ```

***

### create

`browserPools.create`

Create a pool of pre-started browsers with one configuration, for instant browserPools.acquire. Idle pool browsers are not billed but count toward the concurrency limit.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browserPools.create({ size: 1 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `captcha_solver` | `object` | No | — |
| `chrome_policy` | `object` | No | Custom Chrome enterprise policy overrides applied to all browsers in this pool. Keys are Chrome enterprise policy names; values must match their expected types. Blocked: kernel-managed policies (extensions, proxy, CDP/automation). See [https://chromeenterprise.google/policies/](https://chromeenterprise.google/policies/) The serialized JSON payload is capped at 5 MiB. |
| `extensions` | `object[]` | No | List of browser extensions to load into the session. Provide each by id or name. |
| `fill_rate_per_minute` | `number` | No | Percentage of the pool to fill per minute. Defaults to 25. The cap is 25 for most organizations but can be raised per-organization, so only the lower bound is enforced here. |
| `headless` | `boolean` | No | If true, launches the browser using a headless image. Defaults to false. |
| `kiosk_mode` | `boolean` | No | If true, launches the browser in kiosk mode to hide address bar and tabs in live view. Defaults to false. |
| `memory` | `1GiB \| 2GiB \| 4GiB \| 8GiB \| 16GiB` | No | — |
| `name` | `string` | No | Optional name for the browser pool. Must be unique within the project. |
| `network` | `object` | No | — |
| `profile` | `object` | No | Profile selection for browsers in the pool. |
| `proxy_id` | `string` | No | Optional proxy to associate to the browser session. Must reference a proxy in the same project as the browser session. |
| `refresh_on_profile_update` | `boolean` | No | When true, flush idle browsers when the profile the pool uses is updated, so pool browsers pick up the latest profile data. When a profile is provided during creation, this defaults to true. Requires a profile to be set on the pool. |
| `region` | `us-east \| us-west \| eu-west \| ap-southeast` | No | — |
| `size` | `number` | Yes | Number of browsers to maintain in the pool. The maximum size is determined by your organization's pooled sessions limit (the sum of all pool sizes cannot exceed your limit). |
| `start_replay` | `boolean` | No | Start replay recording automatically when a browser is acquired from this pool. |
| `start_url` | `string` | No | Optional URL to navigate to when a new browser is warmed into the pool. Best-effort: failures to navigate do not fail pool fill. Only applied to newly-warmed browsers; browsers reused via release/acquire keep whatever URL the previous lease left them on. Accepts any URL Chromium can resolve, including chrome:// pages. |
| `stealth` | `boolean` | No | If true, enables the CAPTCHA solver and, when proxy\_id is omitted, uses Kernel's default stealth proxy. Defaults to false. Cannot be combined with captcha\_solver.enabled=false. Deprecated in favor of captcha\_solver and proxy\_id. |
| `telemetry` | `object \| null` | No | — |
| `timeout_seconds` | `number` | No | Default idle timeout in seconds for browsers acquired from this pool before they are destroyed. Defaults to 600 seconds. Minimum 10, maximum 259200 (72 hours). |
| `viewport` | `object` | No | Browser viewport used for newly-warmed browsers in this pool. |

> [accordion] captcha\_solver full type
>
> ```ts theme={null}
> {
>   enabled: boolean
> }
> ```

> [accordion] chrome\_policy full type
>
> ```ts theme={null}
> {
> }
> ```

> [accordion] extensions full type
>
> ```ts theme={null}
> {
>   id?: string,
>   name?: string
> }[]
> ```

> [accordion] network full type
>
> ```ts theme={null}
> {
>   allowed_hosts?: string[],
>   allowlist_state?: {
>     base_revision?: string,
>     mutation_id?: string,
>     revision: string
>   },
>   private_hosts?: string[],
>   proxy_routes?: {
>     hosts: string[],
>     proxy: {
>       id?: string,
>       name?: string
>     }
>   }[]
> }
> ```

> [accordion] profile full type
>
> ```ts theme={null}
> {
>   id?: string,
>   name?: string
> }
> ```

> [accordion] telemetry full type
>
> ```ts theme={null}
> {
>   browser?: {
>     captcha?: {
>       enabled?: boolean
>     },
>     connection?: {
>       enabled?: boolean
>     },
>     console?: {
>       enabled?: boolean
>     },
>     control?: {
>       cdp?: {
>         excluded_methods?: (Input.dispatchMouseEvent | Input.dispatchKeyEvent | Input.insertText | Input.imeSetComposition | Input.dispatchTouchEvent | Input.dispatchDragEvent | Input.cancelDragging | Input.emulateTouchFromMouseEvent | Input.synthesizePinchGesture | Input.synthesizeScrollGesture | Input.synthesizeTapGesture | DOM.setFileInputFiles | DOM.focus | DOM.scrollIntoViewIfNeeded | Page.bringToFront | Page.captureScreenshot | Page.captureSnapshot | Page.handleJavaScriptDialog | Page.navigate | Page.navigateToHistoryEntry | Page.reload | Page.printToPDF | Page.startScreencast | Page.stopScreencast | Page.stopLoading | Page.close | Page.setWebLifecycleState | Target.activateTarget | Target.closeTarget | Target.createTarget | Target.createBrowserContext | Target.disposeBrowserContext | Target.openDevTools | Browser.cancelDownload | Browser.close | Browser.setWindowBounds | Browser.setContentsSize | Autofill.trigger)[]
>       },
>       enabled?: boolean
>     },
>     interaction?: {
>       enabled?: boolean
>     },
>     network?: {
>       enabled?: boolean
>     },
>     page?: {
>       enabled?: boolean
>     },
>     platform?: {
>       enabled?: boolean
>     },
>     screenshot?: {
>       enabled?: boolean
>     },
>     system?: {
>       enabled?: boolean
>     }
>   },
>   enabled?: boolean,
>   export?: {
>     otlp?: {
>       destination?: {
>         id?: string,
>         name?: string
>       },
>       enabled?: boolean
>     }
>   },
>   storage?: {
>     enabled?: boolean
>   }
> } | null
> ```

> [accordion] viewport full type
>
> ```ts theme={null}
> {
>   height: number,
>   refresh_rate?: number,
>   width: number
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `acquired_count` | `number \| null` | No | Number of browsers currently acquired from the pool |
| `available_count` | `number \| null` | No | Number of browsers currently available in the pool |
| `browser_pool_config` | `object \| null` | No | — |
| `created_at` | `string \| null` | No | Timestamp when the browser pool was created |
| `extension_ids` | `string[] \| null` | No | Resolved extension IDs attached to the pool, in configured load order. Empty when no extensions are attached. Authoritative for programmatic consumers; the extensions inside `browser_pool_config` reflect the configured selector (echoed as sent on create). |
| `id` | `string \| null` | No | Unique identifier for the browser pool |
| `name` | `string \| null` | No | Browser pool name, if set |
| `profile_id` | `string \| null` | No | Resolved profile ID the pool is attached to. Omitted when no profile is attached. Authoritative for programmatic consumers; the profile inside `browser_pool_config` reflects the configured selector (echoed as sent on create). |
| `region` | `string \| null` | No | — |

> [accordion] browser\_pool\_config full type
>
> ```ts theme={null}
> {
>   captcha_solver?: {
>     enabled?: boolean | null
>   } | null,
>   chrome_policy?: {
>   } | null,
>   extensions?: {
>     id?: string | null,
>     name?: string | null
>   }[] | null,
>   fill_rate_per_minute?: number | null,
>   headless?: boolean | null,
>   kiosk_mode?: boolean | null,
>   memory?: string | null,
>   name?: string | null,
>   network?: {
>     allowed_hosts?: string[] | null,
>     allowlist_state?: {
>       base_revision?: string | null,
>       mutation_id?: string | null,
>       revision?: string | null
>     } | null,
>     private_hosts?: string[] | null,
>     proxy_routes?: {
>       hosts?: string[] | null,
>       proxy?: {
>         id?: string | null,
>         name?: string | null
>       } | null
>     }[] | null
>   } | null,
>   profile?: {
>     id?: string | null,
>     name?: string | null
>   } | null,
>   proxy_id?: string | null,
>   refresh_on_profile_update?: boolean | null,
>   size?: number | null,
>   start_replay?: boolean | null,
>   start_url?: string | null,
>   stealth?: boolean | null,
>   telemetry?: {
>     browser?: {
>       captcha?: {
>         enabled?: boolean | null
>       } | null,
>       connection?: {
>         enabled?: boolean | null
>       } | null,
>       console?: {
>         enabled?: boolean | null
>       } | null,
>       control?: {
>         cdp?: {
>           excluded_methods?: string[] | null
>         } | null,
>         enabled?: boolean | null
>       } | null,
>       interaction?: {
>         enabled?: boolean | null
>       } | null,
>       network?: {
>         enabled?: boolean | null
>       } | null,
>       page?: {
>         enabled?: boolean | null
>       } | null,
>       platform?: {
>         enabled?: boolean | null
>       } | null,
>       screenshot?: {
>         enabled?: boolean | null
>       } | null,
>       system?: {
>         enabled?: boolean | null
>       } | null
>     } | null,
>     export?: {
>       otlp?: {
>         destination?: string | null,
>         enabled?: boolean | null
>       } | null
>     } | null,
>     storage?: {
>       enabled?: boolean | null
>     } | null
>   } | null | null,
>   timeout_seconds?: number | null,
>   viewport?: {
>     height?: number | null,
>     refresh_rate?: number | null,
>     width?: number | null
>   } | null
> } | null
> ```

***

### delete

`browserPools.delete`

Delete a browser pool and its browsers. Cannot be undone.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.kernel.api.browserPools.delete({ id_or_name: 'my-pool' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser pool ID or name |
| `force` | `boolean` | No | If true, force delete even if browsers are currently leased. Leased browsers will be terminated. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### flush

`browserPools.flush`

Delete a pool's idle browsers so it refills with fresh ones.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browserPools.flush({ id_or_name: 'my-pool' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser pool ID or name |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### get

`browserPools.get`

Get a browser pool: configuration, size, and how many browsers are available or leased.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.browserPools.get({ id_or_name: 'my-pool' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser pool ID or name |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `acquired_count` | `number \| null` | No | Number of browsers currently acquired from the pool |
| `available_count` | `number \| null` | No | Number of browsers currently available in the pool |
| `browser_pool_config` | `object \| null` | No | — |
| `created_at` | `string \| null` | No | Timestamp when the browser pool was created |
| `extension_ids` | `string[] \| null` | No | Resolved extension IDs attached to the pool, in configured load order. Empty when no extensions are attached. Authoritative for programmatic consumers; the extensions inside `browser_pool_config` reflect the configured selector (echoed as sent on create). |
| `id` | `string \| null` | No | Unique identifier for the browser pool |
| `name` | `string \| null` | No | Browser pool name, if set |
| `profile_id` | `string \| null` | No | Resolved profile ID the pool is attached to. Omitted when no profile is attached. Authoritative for programmatic consumers; the profile inside `browser_pool_config` reflects the configured selector (echoed as sent on create). |
| `region` | `string \| null` | No | — |

> [accordion] browser\_pool\_config full type
>
> ```ts theme={null}
> {
>   captcha_solver?: {
>     enabled?: boolean | null
>   } | null,
>   chrome_policy?: {
>   } | null,
>   extensions?: {
>     id?: string | null,
>     name?: string | null
>   }[] | null,
>   fill_rate_per_minute?: number | null,
>   headless?: boolean | null,
>   kiosk_mode?: boolean | null,
>   memory?: string | null,
>   name?: string | null,
>   network?: {
>     allowed_hosts?: string[] | null,
>     allowlist_state?: {
>       base_revision?: string | null,
>       mutation_id?: string | null,
>       revision?: string | null
>     } | null,
>     private_hosts?: string[] | null,
>     proxy_routes?: {
>       hosts?: string[] | null,
>       proxy?: {
>         id?: string | null,
>         name?: string | null
>       } | null
>     }[] | null
>   } | null,
>   profile?: {
>     id?: string | null,
>     name?: string | null
>   } | null,
>   proxy_id?: string | null,
>   refresh_on_profile_update?: boolean | null,
>   size?: number | null,
>   start_replay?: boolean | null,
>   start_url?: string | null,
>   stealth?: boolean | null,
>   telemetry?: {
>     browser?: {
>       captcha?: {
>         enabled?: boolean | null
>       } | null,
>       connection?: {
>         enabled?: boolean | null
>       } | null,
>       console?: {
>         enabled?: boolean | null
>       } | null,
>       control?: {
>         cdp?: {
>           excluded_methods?: string[] | null
>         } | null,
>         enabled?: boolean | null
>       } | null,
>       interaction?: {
>         enabled?: boolean | null
>       } | null,
>       network?: {
>         enabled?: boolean | null
>       } | null,
>       page?: {
>         enabled?: boolean | null
>       } | null,
>       platform?: {
>         enabled?: boolean | null
>       } | null,
>       screenshot?: {
>         enabled?: boolean | null
>       } | null,
>       system?: {
>         enabled?: boolean | null
>       } | null
>     } | null,
>     export?: {
>       otlp?: {
>         destination?: string | null,
>         enabled?: boolean | null
>       } | null
>     } | null,
>     storage?: {
>       enabled?: boolean | null
>     } | null
>   } | null | null,
>   timeout_seconds?: number | null,
>   viewport?: {
>     height?: number | null,
>     refresh_rate?: number | null,
>     width?: number | null
>   } | null
> } | null
> ```

***

### list

`browserPools.list`

List browser pools and their sizes.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.browserPools.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `limit` | `number` | No | Limit the number of browser pools to return. |
| `offset` | `number` | No | Offset the number of browser pools to return. |
| `query` | `string` | No | Case-insensitive substring match against browser pool name. IDs match by exact value. |
| `name` | `string` | No | Exact-match filter on browser pool name using the database collation. In production, matching is case- and accent-insensitive. During the default-project migration, unscoped requests prefer a concrete default-project browser pool over a legacy unscoped browser pool with the same name. |
| `region` | `us-east \| us-west \| eu-west \| ap-southeast` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | This page of results. |
| `has_more` | `boolean` | Yes | True when more results follow; pass next\_offset as offset to read them. |
| `next_offset` | `number \| null` | Yes | Value for `offset` that reads the next page, or null on the last page. |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   acquired_count?: number | null,
>   available_count?: number | null,
>   browser_pool_config?: {
>     captcha_solver?: {
>       enabled?: boolean | null
>     } | null,
>     chrome_policy?: {
>     } | null,
>     extensions?: {
>       id?: string | null,
>       name?: string | null
>     }[] | null,
>     fill_rate_per_minute?: number | null,
>     headless?: boolean | null,
>     kiosk_mode?: boolean | null,
>     memory?: string | null,
>     name?: string | null,
>     network?: {
>       allowed_hosts?: string[] | null,
>       allowlist_state?: {
>         base_revision?: string | null,
>         mutation_id?: string | null,
>         revision?: string | null
>       } | null,
>       private_hosts?: string[] | null,
>       proxy_routes?: {
>         hosts?: string[] | null,
>         proxy?: {
>           id?: string | null,
>           name?: string | null
>         } | null
>       }[] | null
>     } | null,
>     profile?: {
>       id?: string | null,
>       name?: string | null
>     } | null,
>     proxy_id?: string | null,
>     refresh_on_profile_update?: boolean | null,
>     size?: number | null,
>     start_replay?: boolean | null,
>     start_url?: string | null,
>     stealth?: boolean | null,
>     telemetry?: {
>       browser?: {
>         captcha?: {
>           enabled?: boolean | null
>         } | null,
>         connection?: {
>           enabled?: boolean | null
>         } | null,
>         console?: {
>           enabled?: boolean | null
>         } | null,
>         control?: {
>           cdp?: {
>             excluded_methods?: string[] | null
>           } | null,
>           enabled?: boolean | null
>         } | null,
>         interaction?: {
>           enabled?: boolean | null
>         } | null,
>         network?: {
>           enabled?: boolean | null
>         } | null,
>         page?: {
>           enabled?: boolean | null
>         } | null,
>         platform?: {
>           enabled?: boolean | null
>         } | null,
>         screenshot?: {
>           enabled?: boolean | null
>         } | null,
>         system?: {
>           enabled?: boolean | null
>         } | null
>       } | null,
>       export?: {
>         otlp?: {
>           destination?: string | null,
>           enabled?: boolean | null
>         } | null
>       } | null,
>       storage?: {
>         enabled?: boolean | null
>       } | null
>     } | null | null,
>     timeout_seconds?: number | null,
>     viewport?: {
>       height?: number | null,
>       refresh_rate?: number | null,
>       width?: number | null
>     } | null
>   } | null,
>   created_at?: string | null,
>   extension_ids?: string[] | null,
>   id?: string | null,
>   name?: string | null,
>   profile_id?: string | null,
>   region?: string | null
> }[]
> ```

***

### release

`browserPools.release`

Return an acquired browser to its pool (optionally reusing it rather than replacing it).

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browserPools.release({ id_or_name: 'my-pool', session_id: 'htzv5orfit78e1m2biiifpbv' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser pool ID or name |
| `reuse` | `boolean` | No | Whether to reuse the browser instance or destroy it and create a new one. Defaults to true. A reused browser keeps the configuration it was created with, so it does not pick up pool configuration changes made while it was in use. Release with `reuse: false`, or flush the pool afterward, to rebuild it with the current configuration. Browsers loaded with an acquire-time profile are always destroyed and replaced, even when reuse is true. |
| `session_id` | `string` | Yes | Browser session ID to release back to the pool |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### update

`browserPools.update`

Change a browser pool's size or browser configuration. A change applies to browsers the pool creates afterwards: pass discard\_all\_idle: true to rebuild idle ones now, and release leased ones with reuse: false. To stop loading a profile, send profile: \{ id: "" }; browsers already in the pool keep the old profile until rebuilt.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browserPools.update({ id_or_name: 'my-pool' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser pool ID or name |
| `captcha_solver` | `object` | No | — |
| `chrome_policy` | `object` | No | If provided, replaces the custom Chrome enterprise policy overrides applied to all browsers in this pool. Empty object clears any previously-set policy. Keys are Chrome enterprise policy names; values must match their expected types. Blocked: kernel-managed policies (extensions, proxy, CDP/automation). See [https://chromeenterprise.google/policies/](https://chromeenterprise.google/policies/) The serialized JSON payload is capped at 5 MiB. |
| `discard_all_idle` | `boolean` | No | Whether to discard all idle browsers and rebuild them immediately with the new configuration. Defaults to false. Only browsers that are idle when the update runs are rebuilt. A browser that is in use during the update keeps its original configuration, except that its allowlist is reset to the current pool baseline on release or the browser is replaced. For other configuration fields, if it is later released with `reuse: true` it returns to the pool with that stale configuration until it is discarded (by this flag on a later update, or by flushing the pool). |
| `expected_network` | `object` | No | — |
| `extensions` | `object[]` | No | If provided, replaces the extension list. Empty array clears all previously-selected extensions. Omit this field to leave extensions unchanged. |
| `fill_rate_per_minute` | `number` | No | If provided, replaces the percentage of the pool to fill per minute. The cap is 25 for most organizations but can be raised per-organization, so only the lower bound is enforced here. |
| `headless` | `boolean` | No | If provided, replaces whether browsers launch using a headless image. |
| `kiosk_mode` | `boolean` | No | If provided, replaces whether browsers launch in kiosk mode. |
| `memory` | `1GiB \| 2GiB \| 4GiB \| 8GiB \| 16GiB` | No | Memory requested for newly-warmed browsers in this pool: 1GiB, 2GiB, or 4GiB for headless, 8GiB or 16GiB for headful. Existing browsers retain their original allocation. Use discard\_all\_idle to replace idle browsers. |
| `name` | `string` | No | If provided, replaces the pool name. Empty string is a no-op; the pool name cannot be cleared or reset to empty once assigned. |
| `network` | `object` | No | — |
| `profile` | `object` | No | If provided, replaces the previously-selected profile. To clear the profile reference, send `{ "id": "" }` or `{ "name": "" }`. An empty object (no id or name) is rejected as 400. |
| `proxy_id` | `string` | No | Empty string clears the previously-selected proxy. Omit this field to leave the proxy unchanged. |
| `refresh_on_profile_update` | `boolean` | No | If provided, replaces whether idle browsers are flushed when the profile the pool uses is updated. When the pool's profile reference is changed (including newly attached) and this field is omitted, it defaults to true. Re-sending the same profile reference leaves this setting unchanged. Clearing the profile also disables this setting. Requires a profile to be set on the pool. |
| `size` | `number` | No | If provided, replaces the number of browsers to maintain in the pool. The maximum size is determined by your organization's pooled sessions limit (the sum of all pool sizes cannot exceed your limit). |
| `start_replay` | `boolean` | No | If provided, replaces whether replay recording starts automatically for future acquired browsers. |
| `start_url` | `string` | No | If provided, replaces the URL to navigate to when a new browser is warmed into the pool. Empty string clears the previously-set URL. Omit this field to leave it unchanged. |
| `stealth` | `boolean` | No | If provided, replaces whether browsers launch in stealth mode. stealth=true without proxy\_id moves a pool on direct egress to Kernel's default stealth proxy. Cannot be combined with captcha\_solver.enabled=false. Deprecated in favor of captcha\_solver and proxy\_id. |
| `telemetry` | `object \| null` | No | — |
| `timeout_seconds` | `number` | No | If provided, replaces the default idle timeout in seconds for browsers acquired from this pool before they are destroyed. Minimum 10, maximum 259200 (72 hours). |
| `viewport` | `object` | No | If provided, replaces the viewport with the new width/height/refresh\_rate. Because width and height are required and must be positive, the viewport cannot be cleared; omit this field to leave it unchanged. |

> [accordion] captcha\_solver full type
>
> ```ts theme={null}
> {
>   enabled: boolean
> }
> ```

> [accordion] chrome\_policy full type
>
> ```ts theme={null}
> {
> }
> ```

> [accordion] expected\_network full type
>
> ```ts theme={null}
> {
>   allowed_hosts?: string[],
>   allowlist_state?: {
>     base_revision?: string,
>     mutation_id?: string,
>     revision: string
>   },
>   private_hosts?: string[],
>   proxy_routes?: {
>     hosts: string[],
>     proxy: {
>       id?: string,
>       name?: string
>     }
>   }[]
> }
> ```

> [accordion] extensions full type
>
> ```ts theme={null}
> {
>   id?: string,
>   name?: string
> }[]
> ```

> [accordion] network full type
>
> ```ts theme={null}
> {
>   allowed_hosts?: string[],
>   allowlist_state?: {
>     base_revision?: string,
>     mutation_id?: string,
>     revision: string
>   },
>   private_hosts?: string[],
>   proxy_routes?: {
>     hosts: string[],
>     proxy: {
>       id?: string,
>       name?: string
>     }
>   }[]
> }
> ```

> [accordion] profile full type
>
> ```ts theme={null}
> {
>   id?: string,
>   name?: string
> }
> ```

> [accordion] telemetry full type
>
> ```ts theme={null}
> {
>   browser?: {
>     captcha?: {
>       enabled?: boolean
>     },
>     connection?: {
>       enabled?: boolean
>     },
>     console?: {
>       enabled?: boolean
>     },
>     control?: {
>       cdp?: {
>         excluded_methods?: (Input.dispatchMouseEvent | Input.dispatchKeyEvent | Input.insertText | Input.imeSetComposition | Input.dispatchTouchEvent | Input.dispatchDragEvent | Input.cancelDragging | Input.emulateTouchFromMouseEvent | Input.synthesizePinchGesture | Input.synthesizeScrollGesture | Input.synthesizeTapGesture | DOM.setFileInputFiles | DOM.focus | DOM.scrollIntoViewIfNeeded | Page.bringToFront | Page.captureScreenshot | Page.captureSnapshot | Page.handleJavaScriptDialog | Page.navigate | Page.navigateToHistoryEntry | Page.reload | Page.printToPDF | Page.startScreencast | Page.stopScreencast | Page.stopLoading | Page.close | Page.setWebLifecycleState | Target.activateTarget | Target.closeTarget | Target.createTarget | Target.createBrowserContext | Target.disposeBrowserContext | Target.openDevTools | Browser.cancelDownload | Browser.close | Browser.setWindowBounds | Browser.setContentsSize | Autofill.trigger)[]
>       },
>       enabled?: boolean
>     },
>     interaction?: {
>       enabled?: boolean
>     },
>     network?: {
>       enabled?: boolean
>     },
>     page?: {
>       enabled?: boolean
>     },
>     platform?: {
>       enabled?: boolean
>     },
>     screenshot?: {
>       enabled?: boolean
>     },
>     system?: {
>       enabled?: boolean
>     }
>   },
>   enabled?: boolean,
>   export?: {
>     otlp?: {
>       destination?: {
>         id?: string,
>         name?: string
>       },
>       enabled?: boolean
>     }
>   },
>   storage?: {
>     enabled?: boolean
>   }
> } | null
> ```

> [accordion] viewport full type
>
> ```ts theme={null}
> {
>   height: number,
>   refresh_rate?: number,
>   width: number
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `acquired_count` | `number \| null` | No | Number of browsers currently acquired from the pool |
| `available_count` | `number \| null` | No | Number of browsers currently available in the pool |
| `browser_pool_config` | `object \| null` | No | — |
| `created_at` | `string \| null` | No | Timestamp when the browser pool was created |
| `extension_ids` | `string[] \| null` | No | Resolved extension IDs attached to the pool, in configured load order. Empty when no extensions are attached. Authoritative for programmatic consumers; the extensions inside `browser_pool_config` reflect the configured selector (echoed as sent on create). |
| `id` | `string \| null` | No | Unique identifier for the browser pool |
| `name` | `string \| null` | No | Browser pool name, if set |
| `profile_id` | `string \| null` | No | Resolved profile ID the pool is attached to. Omitted when no profile is attached. Authoritative for programmatic consumers; the profile inside `browser_pool_config` reflects the configured selector (echoed as sent on create). |
| `region` | `string \| null` | No | — |

> [accordion] browser\_pool\_config full type
>
> ```ts theme={null}
> {
>   captcha_solver?: {
>     enabled?: boolean | null
>   } | null,
>   chrome_policy?: {
>   } | null,
>   extensions?: {
>     id?: string | null,
>     name?: string | null
>   }[] | null,
>   fill_rate_per_minute?: number | null,
>   headless?: boolean | null,
>   kiosk_mode?: boolean | null,
>   memory?: string | null,
>   name?: string | null,
>   network?: {
>     allowed_hosts?: string[] | null,
>     allowlist_state?: {
>       base_revision?: string | null,
>       mutation_id?: string | null,
>       revision?: string | null
>     } | null,
>     private_hosts?: string[] | null,
>     proxy_routes?: {
>       hosts?: string[] | null,
>       proxy?: {
>         id?: string | null,
>         name?: string | null
>       } | null
>     }[] | null
>   } | null,
>   profile?: {
>     id?: string | null,
>     name?: string | null
>   } | null,
>   proxy_id?: string | null,
>   refresh_on_profile_update?: boolean | null,
>   size?: number | null,
>   start_replay?: boolean | null,
>   start_url?: string | null,
>   stealth?: boolean | null,
>   telemetry?: {
>     browser?: {
>       captcha?: {
>         enabled?: boolean | null
>       } | null,
>       connection?: {
>         enabled?: boolean | null
>       } | null,
>       console?: {
>         enabled?: boolean | null
>       } | null,
>       control?: {
>         cdp?: {
>           excluded_methods?: string[] | null
>         } | null,
>         enabled?: boolean | null
>       } | null,
>       interaction?: {
>         enabled?: boolean | null
>       } | null,
>       network?: {
>         enabled?: boolean | null
>       } | null,
>       page?: {
>         enabled?: boolean | null
>       } | null,
>       platform?: {
>         enabled?: boolean | null
>       } | null,
>       screenshot?: {
>         enabled?: boolean | null
>       } | null,
>       system?: {
>         enabled?: boolean | null
>       } | null
>     } | null,
>     export?: {
>       otlp?: {
>         destination?: string | null,
>         enabled?: boolean | null
>       } | null
>     } | null,
>     storage?: {
>       enabled?: boolean | null
>     } | null
>   } | null | null,
>   timeout_seconds?: number | null,
>   viewport?: {
>     height?: number | null,
>     refresh_rate?: number | null,
>     width?: number | null
>   } | null
> } | null
> ```

***

## Browsers

### computer.batch

`browsers.computer.batch`

Run a list of computer actions (click\_mouse, type\_text, press\_key, scroll, move\_mouse, drag\_mouse, sleep and more) in order in one call; stops at the first error. Faster than one call per action.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.computer.batch({
	id_or_name: 'htzv5orfit78e1m2biiifpbv',
	actions: [{
		type: 'click_mouse',
		click_mouse: { x: 640, y: 360 },
	}, {
		type: 'type_text',
		type_text: { text: 'hello' },
	}, {
		type: 'press_key',
		press_key: {
			keys: ['Return'],
		},
	}],
});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `actions` | `object[]` | Yes | Ordered list of actions to execute. Execution stops on the first error. |

> [accordion] actions full type
>
> ```ts theme={null}
> {
>   click_mouse?: {
>     button?: left | right | middle | back | forward,
>     click_type?: down | up | click,
>     hold_keys?: string[],
>     num_clicks?: number,
>     y: number,
>     x: number
>   },
>   drag_mouse?: {
>     button?: left | middle | right,
>     delay?: number,
>     duration_ms?: number,
>     hold_keys?: string[],
>     path: number[][],
>     smooth?: boolean,
>     step_delay_ms?: number,
>     steps_per_segment?: number
>   },
>   move_mouse?: {
>     duration_ms?: number,
>     hold_keys?: string[],
>     smooth?: boolean,
>     y: number,
>     x: number
>   },
>   press_key?: {
>     duration?: number,
>     hold_keys?: string[],
>     keys: string[]
>   },
>   scroll?: {
>     delta_x?: number,
>     delta_y?: number,
>     hold_keys?: string[],
>     y: number,
>     x: number
>   },
>   set_cursor?: {
>     hidden: boolean
>   },
>   sleep?: {
>     duration_ms: number
>   },
>   type: click_mouse | move_mouse | type_text | press_key | scroll | drag_mouse | set_cursor | sleep,
>   type_text?: {
>     delay?: number,
>     text: string
>   }
> }[]
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### computer.captureScreenshot

`browsers.computer.captureScreenshot`

Take a PNG screenshot of the browser screen (optionally a region). Headful browsers only: a headless browser has no window, so this returns an empty screen; there, use page.screenshot() inside browsers.playwright.execute. Returns a file: on Corsair it is saved to Files and comes back with a fileId.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.browsers.computer.captureScreenshot({ id_or_name: 'htzv5orfit78e1m2biiifpbv' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `region` | `object` | No | — |

> [accordion] region full type
>
> ```ts theme={null}
> {
>   height: number,
>   y: number,
>   width: number,
>   x: number
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `contentBase64` | `string` | No | The file, base64-encoded. Missing when the file came back as text or contentOmitted is set. |
| `text` | `string` | No | The file as text, in place of contentBase64, when it is a text file (CSV, JSON, Markdown, XML and the like) in UTF-8. |
| `contentType` | `string` | Yes | Media type of the file, for example application/pdf. |
| `byteLength` | `number` | Yes | Size of the file in bytes. |
| `filename` | `string` | No | The file name, when known. |
| `contentOmitted` | `not_requested \| over_limit` | No | Set when the content was left out: the caller did not ask for it, or the file was over the limit. |
| `fileId` | `string` | No | Where the host saved the file. Over the limit it comes in place of the content; a host that keeps every file sets it beside the content too. On Corsair it is a Files id (fil\_…): pass it to another app wherever that app takes a file URL, or read a text file or PDF with files.read\_text. |

***

### computer.clickMouse

`browsers.computer.clickMouse`

Click at screen coordinates x, y (left, right or middle button; num\_clicks for double-click).

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.computer.clickMouse({ id_or_name: 'htzv5orfit78e1m2biiifpbv', x: 640, y: 360 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `button` | `left \| right \| middle \| back \| forward` | No | Mouse button to interact with |
| `click_type` | `down \| up \| click` | No | Type of click action |
| `hold_keys` | `string[]` | No | Modifier keys to hold during the click |
| `num_clicks` | `number` | No | Number of times to repeat the click |
| `y` | `number` | Yes | Y coordinate of the click position |
| `x` | `number` | Yes | X coordinate of the click position |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### computer.dragMouse

`browsers.computer.dragMouse`

Press the mouse, drag it along a path of \[x, y] points, and release.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.computer.dragMouse({
	id_or_name: 'htzv5orfit78e1m2biiifpbv',
	path: [[100, 100], [300, 100]],
});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `button` | `left \| middle \| right` | No | Mouse button to drag with |
| `delay` | `number` | No | Delay in milliseconds between button down and starting to move along the path. |
| `duration_ms` | `number` | No | Target total duration in milliseconds for the entire drag movement when smooth=true. Omit for automatic timing based on total path length. |
| `hold_keys` | `string[]` | No | Modifier keys to hold during the drag |
| `path` | `number[][]` | Yes | Ordered list of \[x, y] coordinate pairs to move through while dragging. Must contain at least 2 points. |
| `smooth` | `boolean` | No | Use human-like Bezier curves between path waypoints instead of linear interpolation. When true, steps\_per\_segment and step\_delay\_ms are ignored. |
| `step_delay_ms` | `number` | No | Delay in milliseconds between relative steps while dragging (not the initial delay). |
| `steps_per_segment` | `number` | No | Number of relative move steps per segment in the path. Minimum 1. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### computer.getMousePosition

`browsers.computer.getMousePosition`

Get the mouse cursor's current screen coordinates.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.browsers.computer.getMousePosition({ id_or_name: 'htzv5orfit78e1m2biiifpbv' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `y` | `number \| null` | No | Y coordinate of the cursor |
| `x` | `number \| null` | No | X coordinate of the cursor |

***

### computer.moveMouse

`browsers.computer.moveMouse`

Move the mouse cursor to screen coordinates x, y (hover).

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.computer.moveMouse({ id_or_name: 'htzv5orfit78e1m2biiifpbv', x: 640, y: 360 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `duration_ms` | `number` | No | Target total duration in milliseconds for the mouse movement when smooth=true. Omit for automatic timing based on distance. |
| `hold_keys` | `string[]` | No | Modifier keys to hold during the move |
| `smooth` | `boolean` | No | Use human-like Bezier curve path instead of instant mouse movement. |
| `y` | `number` | Yes | Y coordinate to move the cursor to |
| `x` | `number` | Yes | X coordinate to move the cursor to |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### computer.pressKey

`browsers.computer.pressKey`

Press keys or a combination on the browser's keyboard, e.g. \["Return"] or \["Ctrl+a"] (X keysym names).

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.computer.pressKey({
	id_or_name: 'htzv5orfit78e1m2biiifpbv',
	keys: ['Ctrl+a'],
});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `duration` | `number` | No | Duration to hold the keys down in milliseconds. If omitted or 0, keys are tapped. |
| `hold_keys` | `string[]` | No | Optional modifier keys to hold during the key press sequence. |
| `keys` | `string[]` | Yes | List of key symbols to press. Each item should be a key symbol supported by xdotool (see X11 keysym definitions). Examples include "Return", "Shift", "Ctrl", "Alt", "F5". Items in this list could also be combinations, e.g. "Ctrl+t" or "Ctrl+Shift+Tab". Use X11 names for punctuation in combinations, such as "Ctrl+minus" or "Ctrl+plus". A literal hyphen is also accepted as an alias, so "Ctrl+-" is normalized to "Ctrl+minus". |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### computer.readClipboard

`browsers.computer.readClipboard`

Read the text on the browser VM's clipboard.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.browsers.computer.readClipboard({ id_or_name: 'htzv5orfit78e1m2biiifpbv' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `text` | `string \| null` | No | Current clipboard text content |

***

### computer.scroll

`browsers.computer.scroll`

Scroll the mouse wheel by delta\_x/delta\_y at screen coordinates x, y.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.computer.scroll({
	id_or_name: 'htzv5orfit78e1m2biiifpbv',
	x: 640,
	y: 360,
	delta_y: 5,
});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `delta_x` | `number` | No | Horizontal scroll amount in xdotool "wheel units." Positive scrolls right, negative scrolls left. |
| `delta_y` | `number` | No | Vertical scroll amount in xdotool "wheel units." Positive scrolls down, negative scrolls up. |
| `hold_keys` | `string[]` | No | Modifier keys to hold during the scroll |
| `y` | `number` | Yes | Y coordinate at which to perform the scroll |
| `x` | `number` | Yes | X coordinate at which to perform the scroll |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### computer.setCursorVisibility

`browsers.computer.setCursorVisibility`

Show or hide the mouse cursor in screenshots and live view.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.computer.setCursorVisibility({ id_or_name: 'htzv5orfit78e1m2biiifpbv', hidden: true });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `hidden` | `boolean` | Yes | Whether the cursor should be hidden or visible |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `ok` | `boolean \| null` | No | Indicates success. |

***

### computer.typeText

`browsers.computer.typeText`

Type text into the focused field, as keystrokes (optional delay between keys).

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.computer.typeText({ id_or_name: 'htzv5orfit78e1m2biiifpbv', text: 'hello' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `delay` | `number` | No | Delay in milliseconds between keystrokes |
| `text` | `string` | Yes | Text to type on the browser instance |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### computer.writeClipboard

`browsers.computer.writeClipboard`

Put text on the browser VM's clipboard.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.computer.writeClipboard({ id_or_name: 'htzv5orfit78e1m2biiifpbv', text: 'hello' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `text` | `string` | Yes | Text to write to the system clipboard |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### create

`browsers.create`

Start a cloud Chromium browser and get its session\_id, cdp\_ws\_url and browser\_live\_view\_url. Use headless: true unless a person must watch or take over: headless costs about 8x less ($0.06/h vs $0.48/h) and has no live view. stealth: true (or captcha\_solver + proxy) helps on bot-protected sites. Pass profile \{name, save\_changes: true} to start signed in and keep new cookies; the profile is saved when the browser is deleted. start\_url opens a page. A browser bills per second while it is active (a CDP, live view or computer-control connection), drops to unbilled standby after about 10 s idle, and is deleted after timeout\_seconds of standby (default 60). It holds one of the org's concurrent-browser slots until deleted, so call browsers.delete when done.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.create({
	headless: true,
	stealth: true,
	timeout_seconds: 120,
	start_url: 'https://example.com',
	profile: { name: 'acme-login', save_changes: true },
});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `captcha_solver` | `object` | No | — |
| `chrome_policy` | `object` | No | Custom Chrome enterprise policy overrides applied to this browser session. Keys are Chrome enterprise policy names; values must match their expected types. Blocked: kernel-managed policies (extensions, proxy, CDP/automation). See [https://chromeenterprise.google/policies/](https://chromeenterprise.google/policies/) |
| `extensions` | `object[]` | No | List of browser extensions to load into the session. Provide each by id or name. |
| `fingerprint` | `object` | No | — |
| `gpu` | `boolean` | No | If true, enables GPU acceleration for the browser session. Requires Start-Up or Enterprise plan, headless=false, and region=us-east. |
| `headless` | `boolean` | No | If true, launches the browser using a headless image (no VNC/GUI). Defaults to false. |
| `invocation_id` | `string` | No | action invocation ID |
| `kiosk_mode` | `boolean` | No | If true, launches the browser in kiosk mode to hide address bar and tabs in live view. |
| `location` | `object` | No | — |
| `memory` | `1GiB \| 2GiB \| 4GiB \| 8GiB \| 16GiB` | No | — |
| `name` | `string` | No | Optional human-readable name for the browser session, used to find it later in the dashboard. Must be unique among active sessions within the project. Can be changed later via PATCH /browsers/\{id\_or\_name}. |
| `network` | `object` | No | — |
| `profile` | `object` | No | — |
| `proxy` | `object` | No | — |
| `proxy_id` | `string` | No | Optional proxy to associate to the browser session. Must reference a proxy in the same project as the browser session. Deprecated in favor of proxy. |
| `region` | `us-east \| us-west \| eu-west \| ap-southeast` | No | — |
| `start_replay` | `boolean` | No | Start replay recording as part of creating this browser session. |
| `start_url` | `string` | No | Optional URL to open when the browser session is created. Navigation is best-effort, so navigation failures do not prevent the session from being created. |
| `stealth` | `boolean` | No | If true, enables the CAPTCHA solver and, when proxy is omitted, uses Kernel's default stealth proxy. Defaults to false. Equivalent to captcha\_solver.enabled=true with proxy.mode=default. Cannot be combined with captcha\_solver.enabled=false. Deprecated in favor of captcha\_solver and proxy. |
| `tags` | `Record<string, string>` | No | — |
| `telemetry` | `object \| null` | No | — |
| `timeout_seconds` | `number` | No | The number of seconds of inactivity before the browser session is terminated. Activity includes CDP connections and live view connections. Defaults to 60 seconds. Minimum allowed is 10 seconds. Maximum allowed is 259200 (72 hours). We check for inactivity every 5 seconds, so the actual timeout behavior you will see is +/- 5 seconds around the specified value. |
| `vaults` | `object[]` | No | Project-scoped vaults to link to the browser session. Links are immutable after creation. |
| `video_memory` | `3GiB \| 6GiB \| 2GiB \| 4GiB` | No | — |
| `viewport` | `object` | No | — |

> [accordion] captcha\_solver full type
>
> ```ts theme={null}
> {
>   enabled: boolean
> }
> ```

> [accordion] chrome\_policy full type
>
> ```ts theme={null}
> {
> }
> ```

> [accordion] extensions full type
>
> ```ts theme={null}
> {
>   id?: string,
>   name?: string
> }[]
> ```

> [accordion] fingerprint full type
>
> ```ts theme={null}
> {
>   os: linux | macos
> }
> ```

> [accordion] location full type
>
> ```ts theme={null}
> {
>   locale?: string,
>   timezone?: string
> }
> ```

> [accordion] network full type
>
> ```ts theme={null}
> {
>   allowed_hosts?: string[],
>   allowlist_state?: {
>     base_revision?: string,
>     mutation_id?: string,
>     revision: string
>   },
>   private_hosts?: string[],
>   proxy_routes?: {
>     hosts: string[],
>     proxy: {
>       id?: string,
>       name?: string
>     }
>   }[]
> }
> ```

> [accordion] profile full type
>
> ```ts theme={null}
> {
>   id?: string,
>   name?: string,
>   save_changes?: boolean
> }
> ```

> [accordion] proxy full type
>
> ```ts theme={null}
> {
>   id?: string,
>   mode?: direct | default,
>   name?: string
> }
> ```

> [accordion] telemetry full type
>
> ```ts theme={null}
> {
>   browser?: {
>     captcha?: {
>       enabled?: boolean
>     },
>     connection?: {
>       enabled?: boolean
>     },
>     console?: {
>       enabled?: boolean
>     },
>     control?: {
>       cdp?: {
>         excluded_methods?: (Input.dispatchMouseEvent | Input.dispatchKeyEvent | Input.insertText | Input.imeSetComposition | Input.dispatchTouchEvent | Input.dispatchDragEvent | Input.cancelDragging | Input.emulateTouchFromMouseEvent | Input.synthesizePinchGesture | Input.synthesizeScrollGesture | Input.synthesizeTapGesture | DOM.setFileInputFiles | DOM.focus | DOM.scrollIntoViewIfNeeded | Page.bringToFront | Page.captureScreenshot | Page.captureSnapshot | Page.handleJavaScriptDialog | Page.navigate | Page.navigateToHistoryEntry | Page.reload | Page.printToPDF | Page.startScreencast | Page.stopScreencast | Page.stopLoading | Page.close | Page.setWebLifecycleState | Target.activateTarget | Target.closeTarget | Target.createTarget | Target.createBrowserContext | Target.disposeBrowserContext | Target.openDevTools | Browser.cancelDownload | Browser.close | Browser.setWindowBounds | Browser.setContentsSize | Autofill.trigger)[]
>       },
>       enabled?: boolean
>     },
>     interaction?: {
>       enabled?: boolean
>     },
>     network?: {
>       enabled?: boolean
>     },
>     page?: {
>       enabled?: boolean
>     },
>     platform?: {
>       enabled?: boolean
>     },
>     screenshot?: {
>       enabled?: boolean
>     },
>     system?: {
>       enabled?: boolean
>     }
>   },
>   enabled?: boolean,
>   export?: {
>     otlp?: {
>       destination?: {
>         id?: string,
>         name?: string
>       },
>       enabled?: boolean
>     }
>   },
>   storage?: {
>     enabled?: boolean
>   }
> } | null
> ```

> [accordion] vaults full type
>
> ```ts theme={null}
> {
>   id?: string,
>   name?: string
> }[]
> ```

> [accordion] viewport full type
>
> ```ts theme={null}
> {
>   height: number,
>   refresh_rate?: number,
>   width: number
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `base_url` | `string \| null` | No | Metro-API HTTP base URL for this browser session. |
| `browser_live_view_url` | `string \| null` | No | Remote URL for live viewing the browser session. Only available for non-headless browsers. |
| `captcha_solver` | `object \| null` | No | — |
| `cdp_ws_url` | `string \| null` | No | Websocket URL for Chrome DevTools Protocol connections to the browser session |
| `chrome_policy` | `object \| null` | No | Custom Chrome enterprise policy overrides that were applied to this browser session, if any. Echoed back for verification. Keys are Chrome enterprise policy names. |
| `cost` | `object \| null` | No | — |
| `created_at` | `string \| null` | No | When the browser session was created. |
| `deleted_at` | `string \| null` | No | When the browser session was soft-deleted. Only present for deleted sessions. |
| `fingerprint` | `object \| null` | No | — |
| `gpu` | `boolean \| null` | No | Whether GPU acceleration is enabled for the browser session (only supported for headful sessions). |
| `headless` | `boolean \| null` | No | Whether the browser session is running in headless mode. |
| `kiosk_mode` | `boolean \| null` | No | Whether the browser session is running in kiosk mode. |
| `leased_at` | `string \| null` | No | When the pooled browser session was last leased. Only present for leased pooled sessions. |
| `location` | `object \| null` | No | — |
| `memory` | `string \| null` | No | — |
| `name` | `string \| null` | No | Human-readable name of the browser session, if one was set at creation. |
| `network` | `object \| null` | No | — |
| `pool` | `object \| null` | No | — |
| `profile` | `object \| null` | No | — |
| `profile_save_changes` | `boolean \| null` | No | Whether changes made during this browser session are saved back to its profile when the session ends. Omitted when no profile is attached. |
| `proxy` | `object \| null` | No | — |
| `proxy_id` | `string \| null` | No | ID of the proxy associated with this browser session, if any. Deprecated in favor of proxy. |
| `region` | `string \| null` | No | — |
| `replay` | `object \| null` | No | — |
| `session_id` | `string \| null` | No | Unique identifier for the browser session |
| `start_url` | `string \| null` | No | URL the session was most recently asked to navigate to, if any. Recorded for debugging. Navigation is fire-and-forget — the URL is dispatched to the browser without waiting for it to load, and any errors (DNS failure, bad status, timeout) are silently dropped. Captures what was requested, not what the browser actually loaded. |
| `stealth` | `boolean \| null` | No | Whether the browser session has CAPTCHA solving enabled, in which case proxy.mode=default uses Kernel's default stealth proxy. A browser created with only captcha\_solver reports true with proxy.mode=direct. Deprecated in favor of captcha\_solver and proxy. |
| `tags` | `Record<string, string> \| null` | No | — |
| `telemetry` | `object \| null` | No | — |
| `timeout_seconds` | `number \| null` | No | The number of seconds of inactivity before the browser session is terminated. |
| `usage` | `object \| null` | No | — |
| `usage_status` | `string \| null` | No | — |
| `vaults` | `object[] \| null` | No | Vaults linked when the browser session was created. |
| `video_memory` | `string \| null` | No | — |
| `viewport` | `object \| null` | No | — |
| `webdriver_ws_url` | `string \| null` | No | Websocket URL for WebDriver BiDi connections to the browser session |

> [accordion] captcha\_solver full type
>
> ```ts theme={null}
> {
>   enabled?: boolean | null
> } | null
> ```

> [accordion] chrome\_policy full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] cost full type
>
> ```ts theme={null}
> {
>   as_of?: string | null,
>   estimated_usage_spend_usd?: string | null,
>   status?: string | null
> } | null
> ```

> [accordion] fingerprint full type
>
> ```ts theme={null}
> {
>   os?: string | null
> } | null
> ```

> [accordion] location full type
>
> ```ts theme={null}
> {
>   locale?: string | null,
>   locale_source?: string | null,
>   timezone?: string | null,
>   timezone_source?: string | null
> } | null
> ```

> [accordion] network full type
>
> ```ts theme={null}
> {
>   allowed_hosts?: string[] | null,
>   allowlist_state?: {
>     base_revision?: string | null,
>     mutation_id?: string | null,
>     revision?: string | null
>   } | null,
>   private_hosts?: string[] | null,
>   proxy_routes?: {
>     hosts?: string[] | null,
>     proxy?: {
>       id?: string | null,
>       name?: string | null
>     } | null
>   }[] | null
> } | null
> ```

> [accordion] pool full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   name?: string | null
> } | null
> ```

> [accordion] profile full type
>
> ```ts theme={null}
> {
>   created_at?: string | null,
>   id?: string | null,
>   last_used_at?: string | null,
>   name?: string | null | null,
>   updated_at?: string | null
> } | null
> ```

> [accordion] proxy full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   mode?: string | null,
>   name?: string | null
> } | null
> ```

> [accordion] replay full type
>
> ```ts theme={null}
> {
>   finished_at?: string | null | null,
>   replay_id?: string | null,
>   replay_view_url?: string | null,
>   started_at?: string | null | null
> } | null
> ```

> [accordion] telemetry full type
>
> ```ts theme={null}
> {
>   browser?: {
>     captcha?: {
>       enabled?: boolean | null
>     } | null,
>     connection?: {
>       enabled?: boolean | null
>     } | null,
>     console?: {
>       enabled?: boolean | null
>     } | null,
>     control?: {
>       cdp?: {
>         excluded_methods?: string[] | null
>       } | null,
>       enabled?: boolean | null
>     } | null,
>     interaction?: {
>       enabled?: boolean | null
>     } | null,
>     network?: {
>       enabled?: boolean | null
>     } | null,
>     page?: {
>       enabled?: boolean | null
>     } | null,
>     platform?: {
>       enabled?: boolean | null
>     } | null,
>     screenshot?: {
>       enabled?: boolean | null
>     } | null,
>     system?: {
>       enabled?: boolean | null
>     } | null
>   } | null,
>   export?: {
>     otlp?: {
>       destination?: string | null,
>       enabled?: boolean | null
>     } | null
>   } | null,
>   storage?: {
>     enabled?: boolean | null
>   } | null
> } | null | null
> ```

> [accordion] usage full type
>
> ```ts theme={null}
> {
>   uptime_ms?: number | null
> } | null
> ```

> [accordion] vaults full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   name?: string | null
> }[] | null
> ```

> [accordion] viewport full type
>
> ```ts theme={null}
> {
>   height?: number | null,
>   refresh_rate?: number | null,
>   width?: number | null
> } | null
> ```

***

### curl

`browsers.curl`

Send an HTTP request from inside the browser (its cookies, proxy and network fingerprint) and get status, headers and body back. Handy for an API call that needs the signed-in session.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.curl({ id_or_name: 'htzv5orfit78e1m2biiifpbv', url: 'https://example.com/api/me', method: 'GET' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `body` | `string` | No | Request body (for POST/PUT/PATCH). |
| `headers` | `Record<string, string>` | No | Custom headers merged with browser defaults. |
| `method` | `GET \| HEAD \| POST \| PUT \| PATCH \| DELETE \| OPTIONS` | No | HTTP method. |
| `response_encoding` | `utf8 \| base64` | No | Encoding for the response body. Use base64 for binary content. |
| `timeout_ms` | `number` | No | Request timeout in milliseconds. |
| `url` | `string` | Yes | Target URL (must be http or https). |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `body` | `string \| null` | No | Response body (UTF-8 string or base64 depending on request). |
| `duration_ms` | `number \| null` | No | Total request duration in milliseconds. |
| `headers` | `Record<string, string[]> \| null` | No | Response headers (multi-value). |
| `status` | `number \| null` | No | HTTP status code from target. |

***

### delete

`browsers.delete`

End a browser session now and stop its billing; frees its concurrency slot. If it was started with profile save\_changes: true, the cookies and storage are saved to the profile first. Cannot be undone: the session, its tabs and its files are gone.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.delete({ id_or_name: 'htzv5orfit78e1m2biiifpbv' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### fs.createDirectory

`browsers.fs.createDirectory`

Create a directory (and its parents) in the browser VM.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.fs.createDirectory({ id_or_name: 'htzv5orfit78e1m2biiifpbv', path: '/tmp/downloads/report.pdf' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `mode` | `string` | No | Optional directory mode (octal string, e.g. 755). Defaults to 755. |
| `path` | `string` | Yes | Absolute directory path to create. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### fs.deleteDirectory

`browsers.fs.deleteDirectory`

Delete a directory and everything in it from the browser VM.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.kernel.api.browsers.fs.deleteDirectory({ id_or_name: 'htzv5orfit78e1m2biiifpbv', path: '/tmp/downloads/report.pdf' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `path` | `string` | Yes | Absolute path to delete. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### fs.deleteFile

`browsers.fs.deleteFile`

Delete a file from the browser VM.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.kernel.api.browsers.fs.deleteFile({ id_or_name: 'htzv5orfit78e1m2biiifpbv', path: '/tmp/downloads/report.pdf' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `path` | `string` | Yes | Absolute path to delete. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### fs.downloadDirZip

`browsers.fs.downloadDirZip`

Download a directory from the browser VM as a zip. Returns a file: on Corsair it is saved to Files and comes back with a fileId.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.browsers.fs.downloadDirZip({ id_or_name: 'htzv5orfit78e1m2biiifpbv', path: '/tmp/downloads/report.pdf' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `path` | `string` | Yes | Absolute directory path to archive and download. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `contentBase64` | `string` | No | The file, base64-encoded. Missing when the file came back as text or contentOmitted is set. |
| `text` | `string` | No | The file as text, in place of contentBase64, when it is a text file (CSV, JSON, Markdown, XML and the like) in UTF-8. |
| `contentType` | `string` | Yes | Media type of the file, for example application/pdf. |
| `byteLength` | `number` | Yes | Size of the file in bytes. |
| `filename` | `string` | No | The file name, when known. |
| `contentOmitted` | `not_requested \| over_limit` | No | Set when the content was left out: the caller did not ask for it, or the file was over the limit. |
| `fileId` | `string` | No | Where the host saved the file. Over the limit it comes in place of the content; a host that keeps every file sets it beside the content too. On Corsair it is a Files id (fil\_…): pass it to another app wherever that app takes a file URL, or read a text file or PDF with files.read\_text. |

***

### fs.fileInfo

`browsers.fs.fileInfo`

Get a file's or directory's size, mode and modified time in the browser VM.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.browsers.fs.fileInfo({ id_or_name: 'htzv5orfit78e1m2biiifpbv', path: '/tmp/downloads/report.pdf' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `path` | `string` | Yes | Absolute path of the file or directory. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `is_dir` | `boolean \| null` | No | Whether the path is a directory. |
| `mod_time` | `string \| null` | No | Last modification time. |
| `mode` | `string \| null` | No | File mode bits (e.g., "drwxr-xr-x" or "-rw-r--r--"). |
| `name` | `string \| null` | No | Base name of the file or directory. |
| `path` | `string \| null` | No | Absolute path. |
| `size_bytes` | `number \| null` | No | Size in bytes. 0 for directories. |

***

### fs.listFiles

`browsers.fs.listFiles`

List the files and folders in a directory of the browser VM, with sizes and times.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.browsers.fs.listFiles({ id_or_name: 'htzv5orfit78e1m2biiifpbv', path: '/tmp/downloads' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `path` | `string` | Yes | Absolute directory path. |

**Output:** `object[]`

> [accordion] Output full type
>
> ```ts theme={null}
> {
>   is_dir?: boolean | null,
>   mod_time?: string | null,
>   mode?: string | null,
>   name?: string | null,
>   path?: string | null,
>   size_bytes?: number | null
> }[]
> ```

***

### fs.move

`browsers.fs.move`

Move or rename a file or directory in the browser VM.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.fs.move({ id_or_name: 'htzv5orfit78e1m2biiifpbv', src_path: '/tmp/downloads/report.pdf', dest_path: '/tmp/archive/report.pdf' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `dest_path` | `string` | Yes | Absolute destination path. |
| `src_path` | `string` | Yes | Absolute source path. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### fs.readFile

`browsers.fs.readFile`

Read a file from the browser VM (for example a download in /tmp/downloads). Returns a file: on Corsair it is saved to Files and comes back with a fileId.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.browsers.fs.readFile({ id_or_name: 'htzv5orfit78e1m2biiifpbv', path: '/tmp/downloads/report.pdf' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `path` | `string` | Yes | Absolute file path to read. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `contentBase64` | `string` | No | The file, base64-encoded. Missing when the file came back as text or contentOmitted is set. |
| `text` | `string` | No | The file as text, in place of contentBase64, when it is a text file (CSV, JSON, Markdown, XML and the like) in UTF-8. |
| `contentType` | `string` | Yes | Media type of the file, for example application/pdf. |
| `byteLength` | `number` | Yes | Size of the file in bytes. |
| `filename` | `string` | No | The file name, when known. |
| `contentOmitted` | `not_requested \| over_limit` | No | Set when the content was left out: the caller did not ask for it, or the file was over the limit. |
| `fileId` | `string` | No | Where the host saved the file. Over the limit it comes in place of the content; a host that keeps every file sets it beside the content too. On Corsair it is a Files id (fil\_…): pass it to another app wherever that app takes a file URL, or read a text file or PDF with files.read\_text. |

***

### fs.setFilePermissions

`browsers.fs.setFilePermissions`

Change a file's mode or owner in the browser VM.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.fs.setFilePermissions({ id_or_name: 'htzv5orfit78e1m2biiifpbv', path: '/tmp/downloads/report.pdf', mode: '0644' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `group` | `string` | No | New group name or GID. |
| `mode` | `string` | Yes | File mode bits (octal string, e.g. 644). |
| `owner` | `string` | No | New owner username or UID. |
| `path` | `string` | Yes | Absolute path whose permissions are to be changed. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### fs.upload

`browsers.fs.upload`

Upload one or more files into the browser VM, each \{file, dest\_path}; a file is a public URL, \{url} or \{base64}.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.fs.upload({
	id_or_name: 'htzv5orfit78e1m2biiifpbv',
	files: [{ dest_path: '/tmp/uploads/invoice.pdf', file: 'https://example.com/invoice.pdf' }],
});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `files` | `object[]` | Yes | — |

> [accordion] files full type
>
> ```ts theme={null}
> {
>   dest_path: string,
>   file: string | {
>     url: string,
>     filename?: string,
>     contentType?: string
>   } | {
>     base64: string,
>     filename?: string,
>     contentType?: string
>   } | custom
> }[]
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### fs.uploadZip

`browsers.fs.uploadZip`

Upload a zip archive and unpack it into dest\_path in the browser VM.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.fs.uploadZip({ id_or_name: 'htzv5orfit78e1m2biiifpbv', zip_file: 'https://example.com/archive.zip', dest_path: '/tmp/archive/report.pdf' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `dest_path` | `string` | Yes | Absolute destination directory to extract the archive to. |
| `zip_file` | `string \| object \| custom` | Yes | A file: a public URL to it, or \{url, filename?, contentType?}, or \{base64, filename?, contentType?} for a small one. |

> [accordion] zip\_file full type
>
> ```ts theme={null}
> string | {
>   url: string,
>   filename?: string,
>   contentType?: string
> } | {
>   base64: string,
>   filename?: string,
>   contentType?: string
> } | custom
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### fs.watch.start

`browsers.fs.watch.start`

Start watching a directory in the browser VM for changes; returns a watch\_id. Kernel streams the events (not available here), so poll browsers.fs.listFiles instead when you can.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.fs.watch.start({ id_or_name: 'htzv5orfit78e1m2biiifpbv', path: '/tmp/downloads/report.pdf' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `path` | `string` | Yes | Directory to watch. |
| `recursive` | `boolean` | No | Whether to watch recursively. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `watch_id` | `string \| null` | No | Unique identifier for the directory watch |

***

### fs.watch.stop

`browsers.fs.watch.stop`

Stop a directory watch by its watch\_id.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.fs.watch.stop({ id_or_name: 'htzv5orfit78e1m2biiifpbv', watch_id: 'watch_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `watch_id` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### fs.writeFile

`browsers.fs.writeFile`

Write a file into the browser VM at path (creates or replaces it). Pass the contents as a URL or \{base64}.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.fs.writeFile({
	id_or_name: 'htzv5orfit78e1m2biiifpbv',
	path: '/tmp/notes.txt',
	file: { base64: 'aGVsbG8=', filename: 'notes.txt' },
});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `path` | `string` | Yes | Destination absolute file path. |
| `mode` | `string` | No | Optional file mode (octal string, e.g. 644). Defaults to 644. |
| `file` | `string \| object \| custom` | Yes | The file contents to write. |

> [accordion] file full type
>
> ```ts theme={null}
> string | {
>   url: string,
>   filename?: string,
>   contentType?: string
> } | {
>   base64: string,
>   filename?: string,
>   contentType?: string
> } | custom
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### get

`browsers.get`

Get a browser session: status, URLs (cdp\_ws\_url, browser\_live\_view\_url), profile, proxy, timeout and usage cost so far.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.browsers.get({ id_or_name: 'htzv5orfit78e1m2biiifpbv' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `include_deleted` | `boolean` | No | When true, includes soft-deleted browser sessions in the lookup. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `base_url` | `string \| null` | No | Metro-API HTTP base URL for this browser session. |
| `browser_live_view_url` | `string \| null` | No | Remote URL for live viewing the browser session. Only available for non-headless browsers. |
| `captcha_solver` | `object \| null` | No | — |
| `cdp_ws_url` | `string \| null` | No | Websocket URL for Chrome DevTools Protocol connections to the browser session |
| `chrome_policy` | `object \| null` | No | Custom Chrome enterprise policy overrides that were applied to this browser session, if any. Echoed back for verification. Keys are Chrome enterprise policy names. |
| `cost` | `object \| null` | No | — |
| `created_at` | `string \| null` | No | When the browser session was created. |
| `deleted_at` | `string \| null` | No | When the browser session was soft-deleted. Only present for deleted sessions. |
| `fingerprint` | `object \| null` | No | — |
| `gpu` | `boolean \| null` | No | Whether GPU acceleration is enabled for the browser session (only supported for headful sessions). |
| `headless` | `boolean \| null` | No | Whether the browser session is running in headless mode. |
| `kiosk_mode` | `boolean \| null` | No | Whether the browser session is running in kiosk mode. |
| `leased_at` | `string \| null` | No | When the pooled browser session was last leased. Only present for leased pooled sessions. |
| `location` | `object \| null` | No | — |
| `memory` | `string \| null` | No | — |
| `name` | `string \| null` | No | Human-readable name of the browser session, if one was set at creation. |
| `network` | `object \| null` | No | — |
| `pool` | `object \| null` | No | — |
| `profile` | `object \| null` | No | — |
| `profile_save_changes` | `boolean \| null` | No | Whether changes made during this browser session are saved back to its profile when the session ends. Omitted when no profile is attached. |
| `proxy` | `object \| null` | No | — |
| `proxy_id` | `string \| null` | No | ID of the proxy associated with this browser session, if any. Deprecated in favor of proxy. |
| `region` | `string \| null` | No | — |
| `replay` | `object \| null` | No | — |
| `session_id` | `string \| null` | No | Unique identifier for the browser session |
| `start_url` | `string \| null` | No | URL the session was most recently asked to navigate to, if any. Recorded for debugging. Navigation is fire-and-forget — the URL is dispatched to the browser without waiting for it to load, and any errors (DNS failure, bad status, timeout) are silently dropped. Captures what was requested, not what the browser actually loaded. |
| `stealth` | `boolean \| null` | No | Whether the browser session has CAPTCHA solving enabled, in which case proxy.mode=default uses Kernel's default stealth proxy. A browser created with only captcha\_solver reports true with proxy.mode=direct. Deprecated in favor of captcha\_solver and proxy. |
| `tags` | `Record<string, string> \| null` | No | — |
| `telemetry` | `object \| null` | No | — |
| `timeout_seconds` | `number \| null` | No | The number of seconds of inactivity before the browser session is terminated. |
| `usage` | `object \| null` | No | — |
| `usage_status` | `string \| null` | No | — |
| `vaults` | `object[] \| null` | No | Vaults linked when the browser session was created. |
| `video_memory` | `string \| null` | No | — |
| `viewport` | `object \| null` | No | — |
| `webdriver_ws_url` | `string \| null` | No | Websocket URL for WebDriver BiDi connections to the browser session |

> [accordion] captcha\_solver full type
>
> ```ts theme={null}
> {
>   enabled?: boolean | null
> } | null
> ```

> [accordion] chrome\_policy full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] cost full type
>
> ```ts theme={null}
> {
>   as_of?: string | null,
>   estimated_usage_spend_usd?: string | null,
>   status?: string | null
> } | null
> ```

> [accordion] fingerprint full type
>
> ```ts theme={null}
> {
>   os?: string | null
> } | null
> ```

> [accordion] location full type
>
> ```ts theme={null}
> {
>   locale?: string | null,
>   locale_source?: string | null,
>   timezone?: string | null,
>   timezone_source?: string | null
> } | null
> ```

> [accordion] network full type
>
> ```ts theme={null}
> {
>   allowed_hosts?: string[] | null,
>   allowlist_state?: {
>     base_revision?: string | null,
>     mutation_id?: string | null,
>     revision?: string | null
>   } | null,
>   private_hosts?: string[] | null,
>   proxy_routes?: {
>     hosts?: string[] | null,
>     proxy?: {
>       id?: string | null,
>       name?: string | null
>     } | null
>   }[] | null
> } | null
> ```

> [accordion] pool full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   name?: string | null
> } | null
> ```

> [accordion] profile full type
>
> ```ts theme={null}
> {
>   created_at?: string | null,
>   id?: string | null,
>   last_used_at?: string | null,
>   name?: string | null | null,
>   updated_at?: string | null
> } | null
> ```

> [accordion] proxy full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   mode?: string | null,
>   name?: string | null
> } | null
> ```

> [accordion] replay full type
>
> ```ts theme={null}
> {
>   finished_at?: string | null | null,
>   replay_id?: string | null,
>   replay_view_url?: string | null,
>   started_at?: string | null | null
> } | null
> ```

> [accordion] telemetry full type
>
> ```ts theme={null}
> {
>   browser?: {
>     captcha?: {
>       enabled?: boolean | null
>     } | null,
>     connection?: {
>       enabled?: boolean | null
>     } | null,
>     console?: {
>       enabled?: boolean | null
>     } | null,
>     control?: {
>       cdp?: {
>         excluded_methods?: string[] | null
>       } | null,
>       enabled?: boolean | null
>     } | null,
>     interaction?: {
>       enabled?: boolean | null
>     } | null,
>     network?: {
>       enabled?: boolean | null
>     } | null,
>     page?: {
>       enabled?: boolean | null
>     } | null,
>     platform?: {
>       enabled?: boolean | null
>     } | null,
>     screenshot?: {
>       enabled?: boolean | null
>     } | null,
>     system?: {
>       enabled?: boolean | null
>     } | null
>   } | null,
>   export?: {
>     otlp?: {
>       destination?: string | null,
>       enabled?: boolean | null
>     } | null
>   } | null,
>   storage?: {
>     enabled?: boolean | null
>   } | null
> } | null | null
> ```

> [accordion] usage full type
>
> ```ts theme={null}
> {
>   uptime_ms?: number | null
> } | null
> ```

> [accordion] vaults full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   name?: string | null
> }[] | null
> ```

> [accordion] viewport full type
>
> ```ts theme={null}
> {
>   height?: number | null,
>   refresh_rate?: number | null,
>   width?: number | null
> } | null
> ```

***

### list

`browsers.list`

List browser sessions in the project, newest first; filter by status (active, deleted, all), tags or name query. Pages with offset/limit; check has\_more.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.browsers.list({ status: 'active', limit: 20 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `status` | `active \| deleted \| all` | No | Filter sessions by status. "active" returns only active sessions (default), "deleted" returns only soft-deleted sessions, "all" returns both. |
| `include_deleted` | `boolean` | No | Deprecated: Use status=all instead. When true, includes soft-deleted browser sessions in the results alongside active sessions. |
| `limit` | `number` | No | Maximum number of results to return. Defaults to 20, maximum 100. |
| `offset` | `number` | No | Number of results to skip. Defaults to 0. |
| `query` | `string` | No | Search browsers by name, session ID, profile name or ID, proxy ID, or pool name. |
| `tags` | `Record<string, string>` | No | Filter sessions by tag key-value pairs using deepObject style, e.g. ?tags\[team]=backend\&tags\[env]=staging. Multiple pairs are ANDed: a session must match every supplied pair exactly. |
| `region` | `us-east \| us-west \| eu-west \| ap-southeast` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | This page of results. |
| `has_more` | `boolean` | Yes | True when more results follow; pass next\_offset as offset to read them. |
| `next_offset` | `number \| null` | Yes | Value for `offset` that reads the next page, or null on the last page. |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   base_url?: string | null,
>   browser_live_view_url?: string | null,
>   captcha_solver?: {
>     enabled?: boolean | null
>   } | null,
>   cdp_ws_url?: string | null,
>   chrome_policy?: {
>   } | null,
>   cost?: {
>     as_of?: string | null,
>     estimated_usage_spend_usd?: string | null,
>     status?: string | null
>   } | null,
>   created_at?: string | null,
>   deleted_at?: string | null,
>   fingerprint?: {
>     os?: string | null
>   } | null,
>   gpu?: boolean | null,
>   headless?: boolean | null,
>   kiosk_mode?: boolean | null,
>   leased_at?: string | null,
>   location?: {
>     locale?: string | null,
>     locale_source?: string | null,
>     timezone?: string | null,
>     timezone_source?: string | null
>   } | null,
>   memory?: string | null,
>   name?: string | null,
>   network?: {
>     allowed_hosts?: string[] | null,
>     allowlist_state?: {
>       base_revision?: string | null,
>       mutation_id?: string | null,
>       revision?: string | null
>     } | null,
>     private_hosts?: string[] | null,
>     proxy_routes?: {
>       hosts?: string[] | null,
>       proxy?: {
>         id?: string | null,
>         name?: string | null
>       } | null
>     }[] | null
>   } | null,
>   pool?: {
>     id?: string | null,
>     name?: string | null
>   } | null,
>   profile?: {
>     created_at?: string | null,
>     id?: string | null,
>     last_used_at?: string | null,
>     name?: string | null | null,
>     updated_at?: string | null
>   } | null,
>   profile_save_changes?: boolean | null,
>   proxy?: {
>     id?: string | null,
>     mode?: string | null,
>     name?: string | null
>   } | null,
>   proxy_id?: string | null,
>   region?: string | null,
>   replay?: {
>     finished_at?: string | null | null,
>     replay_id?: string | null,
>     replay_view_url?: string | null,
>     started_at?: string | null | null
>   } | null,
>   session_id?: string | null,
>   start_url?: string | null,
>   stealth?: boolean | null,
>   tags?: Record<string, string> | null,
>   telemetry?: {
>     browser?: {
>       captcha?: {
>         enabled?: boolean | null
>       } | null,
>       connection?: {
>         enabled?: boolean | null
>       } | null,
>       console?: {
>         enabled?: boolean | null
>       } | null,
>       control?: {
>         cdp?: {
>           excluded_methods?: string[] | null
>         } | null,
>         enabled?: boolean | null
>       } | null,
>       interaction?: {
>         enabled?: boolean | null
>       } | null,
>       network?: {
>         enabled?: boolean | null
>       } | null,
>       page?: {
>         enabled?: boolean | null
>       } | null,
>       platform?: {
>         enabled?: boolean | null
>       } | null,
>       screenshot?: {
>         enabled?: boolean | null
>       } | null,
>       system?: {
>         enabled?: boolean | null
>       } | null
>     } | null,
>     export?: {
>       otlp?: {
>         destination?: string | null,
>         enabled?: boolean | null
>       } | null
>     } | null,
>     storage?: {
>       enabled?: boolean | null
>     } | null
>   } | null | null,
>   timeout_seconds?: number | null,
>   usage?: {
>     uptime_ms?: number | null
>   } | null,
>   usage_status?: string | null,
>   vaults?: {
>     id?: string | null,
>     name?: string | null
>   }[] | null,
>   video_memory?: string | null,
>   viewport?: {
>     height?: number | null,
>     refresh_rate?: number | null,
>     width?: number | null
>   } | null,
>   webdriver_ws_url?: string | null
> }[]
> ```

***

### liveView\.create

`browsers.liveView.create`

Make a live view link for a headful browser so a person can watch (scope read) or take over (scope control): log in, solve a captcha, approve a step. The link lasts until the browser is deleted or ttl\_seconds passes and cannot be revoked, so treat it as a credential and share it only with the person who needs it. Headless browsers have no live view.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.liveView.create({ id_or_name: 'htzv5orfit78e1m2biiifpbv', scope: 'control', ttl_seconds: 900 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `scope` | `read \| control` | No | — |
| `ttl_seconds` | `number` | No | Seconds until the URL expires. Omit to keep it valid until the browser is deleted. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `expires_at` | `string \| null` | No | When the URL expires. Absent when it stays valid until the browser is deleted. |
| `scope` | `string \| null` | No | — |
| `url` | `string \| null` | No | Live view URL. Treat it as a credential. |

***

### loadExtensions

`browsers.loadExtensions`

Load unpacked Chrome extensions (each a zip, as a URL or base64) into a running browser.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.loadExtensions({
	id_or_name: 'htzv5orfit78e1m2biiifpbv',
	extensions: [{ zip_file: 'https://example.com/archive.zip', name: 'my-name' }],
});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `extensions` | `object[]` | Yes | List of extensions to upload and activate |

> [accordion] extensions full type
>
> ```ts theme={null}
> {
>   name: string,
>   zip_file: string | {
>     url: string,
>     filename?: string,
>     contentType?: string
>   } | {
>     base64: string,
>     filename?: string,
>     contentType?: string
>   } | custom
> }[]
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### playwright.execute

`browsers.playwright.execute`

The simplest way to act on a page: run Playwright code in the browser's VM in one call and get its return value as result (plus stdout/stderr and error). The code gets page, context, browser and webmcp, e.g. `await page.goto('https://example.com'); return await page.title();`. timeout\_sec defaults to 60 (max 300). Calls with the same executor name run one at a time in a shared process; pass idempotency\_key to make a retry safe.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.playwright.execute({ id_or_name: 'htzv5orfit78e1m2biiifpbv', code: 'await page.goto(\'https://example.com\'); return await page.title();', timeout_sec: 60 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `idempotency_key` | `string` | No | Makes retrying the call safe. A call with a key already used on this browser returns the first call's response instead of running the code again, waiting for it if it is still running. A call with a key keeps running for 10 seconds after its last caller disconnects, so a retry can collect its response; after that it is cancelled like a call without a key. A response is kept for 10 minutes once the call finishes, and only the most recent responses are kept. A call rejected before the code runs, such as with 400, 409 or 429, does not use up its key. The Kernel SDKs send a key automatically and reuse it when they retry. |
| `code` | `string` | Yes | TypeScript/JavaScript code to execute. The code has access to 'page', 'context', and 'browser' variables. It runs within a function, so you can use a return statement at the end to return a value. This value is returned as the `result` property in the response. Example: "await page.goto('[https://example.com](https://example.com)'); return await page.title();" |
| `executor` | `string` | No | — |
| `timeout_sec` | `number` | No | Maximum execution time in seconds. Default is 60. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `error` | `string \| null` | No | Error message if execution failed |
| `result` | `any \| null` | No | The value returned by the code (if any) |
| `stderr` | `string \| null` | No | Standard error from the execution |
| `stdout` | `string \| null` | No | Standard output from the execution |
| `success` | `boolean \| null` | No | Whether the code executed successfully |
| `tab` | `object \| null` | No | — |

> [accordion] tab full type
>
> ```ts theme={null}
> {
>   created?: boolean | null,
>   target_id?: string | null
> } | null
> ```

***

### playwright.executors.delete

`browsers.playwright.executors.delete`

Stop and remove a named Playwright executor on a browser; a later call with that name starts a fresh one.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.kernel.api.browsers.playwright.executors.delete({ id_or_name: 'htzv5orfit78e1m2biiifpbv', name: 'my-name' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `name` | `string` | Yes | — |
| `close_tab` | `boolean` | No | Close the executor's tab. Defaults to true. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### playwright.executors.list

`browsers.playwright.executors.list`

List the Playwright executors (worker processes) on a browser and whether each is busy.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.browsers.playwright.executors.list({ id_or_name: 'htzv5orfit78e1m2biiifpbv' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `executors` | `object[] \| null` | No | — |

> [accordion] executors full type
>
> ```ts theme={null}
> {
>   busy?: boolean | null,
>   created_at?: string | null,
>   last_used_at?: string | null,
>   name?: string | null,
>   target_id?: string | null,
>   url?: string | null
> }[] | null
> ```

***

### process.exec

`browsers.process.exec`

Run a shell command in the browser VM and wait for it: returns exit code, stdout and stderr (base64). Set timeout\_sec for long commands.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.process.exec({
	id_or_name: 'htzv5orfit78e1m2biiifpbv',
	command: 'ls',
	args: ['-la', '/tmp/downloads'],
	timeout_sec: 30,
});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `args` | `string[]` | No | Command arguments. |
| `as_root` | `boolean` | No | Run the process with root privileges. |
| `as_user` | `string \| null` | No | Run the process as this user. |
| `command` | `string` | Yes | Executable or shell command to run. |
| `cwd` | `string \| null` | No | Working directory (absolute path) to run the command in. |
| `env` | `Record<string, string>` | No | Environment variables to set for the process. |
| `timeout_sec` | `number \| null` | No | Maximum execution time in seconds. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `duration_ms` | `number \| null` | No | Execution duration in milliseconds. |
| `exit_code` | `number \| null` | No | Process exit code. |
| `stderr_b64` | `string \| null` | No | Base64-encoded stderr buffer. |
| `stdout_b64` | `string \| null` | No | Base64-encoded stdout buffer. |

***

### process.kill

`browsers.process.kill`

Send a signal to a spawned process. signal is required: TERM to end it, KILL to force it, or INT, HUP.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.process.kill({ id_or_name: 'htzv5orfit78e1m2biiifpbv', process_id: 'proc_123', signal: 'TERM' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `process_id` | `string` | Yes | — |
| `signal` | `TERM \| KILL \| INT \| HUP` | Yes | Signal to send. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `ok` | `boolean \| null` | No | Indicates success. |

***

### process.resize

`browsers.process.resize`

Resize the terminal of a process spawned with allocate\_tty.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.process.resize({
	id_or_name: 'htzv5orfit78e1m2biiifpbv',
	process_id: 'proc_123',
	rows: 1,
	cols: 1,
});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `process_id` | `string` | Yes | — |
| `cols` | `number` | Yes | New terminal columns. |
| `rows` | `number` | Yes | New terminal rows. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `ok` | `boolean \| null` | No | Indicates success. |

***

### process.spawn

`browsers.process.spawn`

Start a command in the browser VM without waiting; returns a process\_id for browsers.process.status, stdin and kill.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.process.spawn({ id_or_name: 'htzv5orfit78e1m2biiifpbv', command: 'ls' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `args` | `string[]` | No | Command arguments. |
| `as_root` | `boolean` | No | Run the process with root privileges. |
| `as_user` | `string \| null` | No | Run the process as this user. |
| `command` | `string` | Yes | Executable or shell command to run. |
| `cwd` | `string \| null` | No | Working directory (absolute path) to run the command in. |
| `env` | `Record<string, string>` | No | Environment variables to set for the process. |
| `timeout_sec` | `number \| null` | No | Maximum execution time in seconds. |
| `allocate_tty` | `boolean` | No | Allocate a pseudo-terminal (PTY) for interactive shells. |
| `cols` | `number` | No | Initial terminal columns. Only used when allocate\_tty is true. |
| `rows` | `number` | No | Initial terminal rows. Only used when allocate\_tty is true. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `pid` | `number \| null` | No | OS process ID. |
| `process_id` | `string \| null` | No | Server-assigned identifier for the process. |
| `started_at` | `string \| null` | No | Timestamp when the process started. |

***

### process.status

`browsers.process.status`

Get a spawned process's state, exit code and resource use.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.browsers.process.status({ id_or_name: 'htzv5orfit78e1m2biiifpbv', process_id: 'proc_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `process_id` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `cpu_pct` | `number \| null` | No | Estimated CPU usage percentage. |
| `exit_code` | `number \| null \| null` | No | Exit code if the process has exited. |
| `mem_bytes` | `number \| null` | No | Estimated resident memory usage in bytes. |
| `state` | `string \| null` | No | Process state. |

***

### process.stdin

`browsers.process.stdin`

Write data (base64) to a spawned process's stdin.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.process.stdin({ id_or_name: 'htzv5orfit78e1m2biiifpbv', process_id: 'proc_123', data_b64: 'aGVsbG8K' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `process_id` | `string` | Yes | — |
| `data_b64` | `string` | Yes | Base64-encoded data to write. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `written_bytes` | `number \| null` | No | Number of bytes written. |

***

### repl

`browsers.repl`

Run JavaScript in a persistent Node.js REPL inside the browser VM; variables persist between calls (reset: true starts fresh). Start with repl.help(). Output comes from repl.write, console or repl.emitImage.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.repl({ id_or_name: 'htzv5orfit78e1m2biiifpbv', code: 'repl.help()' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `idempotency_key` | `string` | No | Makes retrying the call safe. A call with a key already used on this browser returns the first call's response instead of running the code again, waiting for it if it is still running. A call with a key keeps running for 10 seconds after its last caller disconnects, so a retry can collect its response; after that it is cancelled like a call without a key. A response is kept for 10 minutes once the call finishes, and only the most recent responses are kept. A call rejected before the code runs, such as with 400, 409 or 429, does not use up its key. The Kernel SDKs send a key automatically and reuse it when they retry. |
| `code` | `string` | Yes | JavaScript evaluated in a persistent Node.js runtime. Top-level bindings persist until the browser VM's API process exits, the REPL is reset, or the REPL is terminated after a crash or timeout. Static top-level imports are unsupported; use dynamic `import()`. Expression values are ignored; emit output with `repl.write(...)`, console methods, or `repl.emitImage(...)`. May be empty only when `reset` is true. |
| `reset` | `boolean` | No | Terminate the current REPL, start a fresh one, and then evaluate code. |
| `timeout_sec` | `number` | No | Maximum execution time in seconds. Default is 60. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `content` | `object[] \| null` | No | Optional ordered text/image output produced by the execution. |
| `content_truncated` | `boolean \| null` | No | True if text or image output was dropped or truncated due to response limits. |
| `duration_ms` | `number \| null` | No | Wall-clock execution time in milliseconds. |
| `error` | `string \| null` | No | Error message if execution failed. |
| `repl_id` | `string \| null` | No | CUID2 identifying the exact state-holding REPL process used for this execution. Stable across calls and Chromium reconnects; changes after an API restart, explicit reset, execution timeout, or REPL crash. |
| `repl_terminated` | `boolean \| null` | No | True if the REPL identified by `repl_id` was terminated by this request. The next request lazily starts a fresh REPL with a new `repl_id`. |
| `stack` | `string \| null` | No | Stack trace if execution failed. |
| `success` | `boolean \| null` | No | Whether the code executed successfully. |

> [accordion] content full type
>
> ```ts theme={null}
> (
>   {
>     channel?: string | null,
>     text?: string | null,
>     type?: string | null
>   } | {
>     data_b64?: string | null,
>     mime_type?: string | null,
>     type?: string | null
>   }
> )[] | null
> ```

***

### replays.download

`browsers.replays.download`

Download a replay recording as MP4. Returns a file: on Corsair it is saved to Files and comes back with a fileId. Errors with "still preparing" for a few seconds after the recording stops.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.browsers.replays.download({ id_or_name: 'htzv5orfit78e1m2biiifpbv', replay_id: 'replay_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `replay_id` | `string` | Yes | Replay recording identifier |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `contentBase64` | `string` | No | The file, base64-encoded. Missing when the file came back as text or contentOmitted is set. |
| `text` | `string` | No | The file as text, in place of contentBase64, when it is a text file (CSV, JSON, Markdown, XML and the like) in UTF-8. |
| `contentType` | `string` | Yes | Media type of the file, for example application/pdf. |
| `byteLength` | `number` | Yes | Size of the file in bytes. |
| `filename` | `string` | No | The file name, when known. |
| `contentOmitted` | `not_requested \| over_limit` | No | Set when the content was left out: the caller did not ask for it, or the file was over the limit. |
| `fileId` | `string` | No | Where the host saved the file. Over the limit it comes in place of the content; a host that keeps every file sets it beside the content too. On Corsair it is a Files id (fil\_…): pass it to another app wherever that app takes a file URL, or read a text file or PDF with files.read\_text. |

***

### replays.list

`browsers.replays.list`

List a browser's replay recordings with their ids and view URLs.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.browsers.replays.list({ id_or_name: 'htzv5orfit78e1m2biiifpbv' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |

**Output:** `object[]`

> [accordion] Output full type
>
> ```ts theme={null}
> {
>   finished_at?: string | null | null,
>   replay_id?: string | null,
>   replay_view_url?: string | null,
>   started_at?: string | null | null
> }[]
> ```

***

### replays.start

`browsers.replays.start`

Start recording the browser screen as a video replay (headful browsers); returns a replay\_id.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.replays.start({ id_or_name: 'htzv5orfit78e1m2biiifpbv' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `framerate` | `number` | No | Recording framerate in fps. Values above 20 require GPU to be enabled on the browser session. |
| `max_duration_in_seconds` | `number` | No | Maximum recording duration in seconds. |
| `record_audio` | `boolean` | No | Record audio in addition to video. When false (the default), the recording is video-only. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `finished_at` | `string \| null \| null` | No | Timestamp when replay finished |
| `replay_id` | `string \| null` | No | Unique identifier for the replay recording. |
| `replay_view_url` | `string \| null` | No | URL for viewing the replay recording. |
| `started_at` | `string \| null \| null` | No | Timestamp when replay started |

***

### replays.stop

`browsers.replays.stop`

Stop a replay recording; download it with browsers.replays.download once it is processed.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.replays.stop({ id_or_name: 'htzv5orfit78e1m2biiifpbv', replay_id: 'replay_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `replay_id` | `string` | Yes | Replay recording identifier |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### saveProfile

`browsers.saveProfile`

Save the running browser's cookies and storage to a profile now, without ending the session: by id (overwrite) or by name (overwrite or create).

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.saveProfile({ id_or_name: 'htzv5orfit78e1m2biiifpbv' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `id` | `string` | No | Existing profile ID to overwrite. |
| `name` | `string` | No | Profile name to overwrite or create. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `created_at` | `string \| null` | No | Timestamp when the profile was created |
| `id` | `string \| null` | No | Unique identifier for the profile |
| `last_used_at` | `string \| null` | No | Timestamp when the profile was last used |
| `name` | `string \| null \| null` | No | Optional, easier-to-reference name for the profile |
| `updated_at` | `string \| null` | No | Timestamp when the profile was last updated |

***

### telemetry.events

`browsers.telemetry.events`

Read a page of telemetry events for a browser (console, network, page, interaction, captcha and more), filtered by category, type and time. Pages with offset; check has\_more.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.browsers.telemetry.events({ id_or_name: 'htzv5orfit78e1m2biiifpbv' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `offset` | `number` | No | Opaque pagination cursor: pass the X-Next-Offset value from the previous response to fetch the next page. When set, paging continues from this cursor and since is ignored, while until still bounds the page. It is not an event's seq field, so do not derive it from the response body. |
| `since` | `string` | No | Start of the window: an RFC-3339 timestamp, or a duration like 5m meaning that long ago. Defaults to 5m. Ignored when offset is set. |
| `until` | `string` | No | End of the window (exclusive): an RFC-3339 timestamp, or a duration like 5m meaning that long ago. |
| `limit` | `number` | No | Maximum number of events per page. Defaults to 20. |
| `category` | `(console \| network \| page \| interaction \| control \| platform \| connection \| system \| screenshot \| captcha \| monitor)[]` | No | Restrict results to these event categories. Repeat the parameter for multiple values. |
| `type` | `string[]` | No | Restrict results to these event types, such as page\_crashed or captcha\_challenge\_result. Repeat the parameter for multiple values. Combines with category: when both are set an event must match both. |
| `order` | `string` | No | Read direction. asc (default) reads oldest first, starting from since or the offset cursor. desc reads newest first: each request returns one page of up to limit records ending at the offset cursor (or until, or the newest archived event); combining desc with since is rejected with a 400. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | This page of results. |
| `has_more` | `boolean` | Yes | True when more results follow; pass next\_offset as offset to read them. |
| `next_offset` | `number \| null` | Yes | Value for `offset` that reads the next page, or null on the last page. |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   event?: {
>     category?: string | null,
>     data?: {
>       frame_id?: string | null,
>       loader_id?: string | null,
>       nav_seq?: number | null,
>       session_id?: string | null,
>       target_id?: string | null,
>       target_type?: string | null,
>       url?: string | null,
>       args?: string[] | null,
>       level?: string | null,
>       stack_trace?: {
>         callFrames?: {
>           columnNumber?: number | null,
>           functionName?: string | null,
>           lineNumber?: number | null,
>           scriptId?: string | null,
>           url?: string | null
>         }[] | null,
>         description?: string | null,
>         parent?: (recursive) | null
>       } | null,
>       text?: string | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       frame_id?: string | null,
>       loader_id?: string | null,
>       nav_seq?: number | null,
>       session_id?: string | null,
>       target_id?: string | null,
>       target_type?: string | null,
>       url?: string | null,
>       args?: string[] | null,
>       column?: number | null,
>       level?: string | null,
>       line?: number | null,
>       source_url?: string | null,
>       stack_trace?: {
>         callFrames?: {
>           columnNumber?: number | null,
>           functionName?: string | null,
>           lineNumber?: number | null,
>           scriptId?: string | null,
>           url?: string | null
>         }[] | null,
>         description?: string | null,
>         parent?: (recursive) | null
>       } | null,
>       text?: string | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       frame_id?: string | null,
>       loader_id?: string | null,
>       nav_seq?: number | null,
>       session_id?: string | null,
>       target_id?: string | null,
>       target_type?: string | null,
>       url?: string | null,
>       document_url?: string | null,
>       headers?: {
>       } | null,
>       initiator_type?: string | null,
>       is_redirect?: boolean | null,
>       method?: string | null,
>       post_data?: string | null,
>       redirect_url?: string | null,
>       request_id?: string | null,
>       resource_type?: string | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       frame_id?: string | null,
>       loader_id?: string | null,
>       nav_seq?: number | null,
>       session_id?: string | null,
>       target_id?: string | null,
>       target_type?: string | null,
>       url?: string | null,
>       body?: string | null,
>       headers?: {
>       } | null,
>       method?: string | null,
>       mime_type?: string | null,
>       request_id?: string | null,
>       resource_type?: string | null,
>       status?: number | null,
>       status_text?: string | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       frame_id?: string | null,
>       loader_id?: string | null,
>       nav_seq?: number | null,
>       session_id?: string | null,
>       target_id?: string | null,
>       target_type?: string | null,
>       url?: string | null,
>       canceled?: boolean | null,
>       error_text?: string | null,
>       request_id?: string | null,
>       resource_type?: string | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       frame_id?: string | null,
>       loader_id?: string | null,
>       nav_seq?: number | null,
>       session_id?: string | null,
>       target_id?: string | null,
>       target_type?: string | null,
>       url?: string | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       frame_id?: string | null,
>       loader_id?: string | null,
>       nav_seq?: number | null,
>       session_id?: string | null,
>       target_id?: string | null,
>       target_type?: string | null,
>       url?: string | null,
>       code?: string | null,
>       method?: string | null,
>       raw_code?: string | null,
>       request_id?: string | null,
>       resource_type?: string | null,
>       status?: number | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       frame_id?: string | null,
>       loader_id?: string | null,
>       parent_frame_id?: string | null,
>       session_id?: string | null,
>       target_id?: string | null,
>       target_type?: string | null,
>       url?: string | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       frame_id?: string | null,
>       loader_id?: string | null,
>       nav_seq?: number | null,
>       session_id?: string | null,
>       target_id?: string | null,
>       target_type?: string | null,
>       url?: string | null,
>       cdp_timestamp?: number | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       frame_id?: string | null,
>       loader_id?: string | null,
>       nav_seq?: number | null,
>       session_id?: string | null,
>       target_id?: string | null,
>       target_type?: string | null,
>       url?: string | null,
>       cdp_timestamp?: number | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       opener_id?: string | null,
>       target_id?: string | null,
>       target_type?: string | null,
>       title?: string | null,
>       url?: string | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       target_id?: string | null,
>       target_type?: string | null,
>       url?: string | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       frame_id?: string | null,
>       loader_id?: string | null,
>       nav_seq?: number | null,
>       session_id?: string | null,
>       target_id?: string | null,
>       target_type?: string | null,
>       url?: string | null,
>       duration?: number | null,
>       layout_shift_details?: {
>         had_recent_input?: boolean | null,
>         value?: number | null
>       } | null,
>       source_frame_id?: string | null,
>       time?: number | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       frame_id?: string | null,
>       loader_id?: string | null,
>       nav_seq?: number | null,
>       session_id?: string | null,
>       target_id?: string | null,
>       target_type?: string | null,
>       url?: string | null,
>       lcp_details?: {
>         element_id?: string | null,
>         load_time?: number | null,
>         node_id?: number | null,
>         render_time?: number | null,
>         size?: number | null,
>         url?: string | null
>       } | null,
>       source_frame_id?: string | null,
>       time?: number | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       frame_id?: string | null,
>       loader_id?: string | null,
>       nav_seq?: number | null,
>       session_id?: string | null,
>       target_id?: string | null,
>       target_type?: string | null,
>       url?: string | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       frame_id?: string | null,
>       loader_id?: string | null,
>       nav_seq?: number | null,
>       session_id?: string | null,
>       target_id?: string | null,
>       target_type?: string | null,
>       url?: string | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       frame_id?: string | null,
>       loader_id?: string | null,
>       nav_seq?: number | null,
>       session_id?: string | null,
>       target_id?: string | null,
>       target_type?: string | null,
>       url?: string | null,
>       selector?: string | null,
>       tag?: string | null,
>       text?: string | null,
>       y?: number | null,
>       x?: number | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       frame_id?: string | null,
>       loader_id?: string | null,
>       nav_seq?: number | null,
>       session_id?: string | null,
>       target_id?: string | null,
>       target_type?: string | null,
>       url?: string | null,
>       key?: string | null,
>       selector?: string | null,
>       tag?: string | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       frame_id?: string | null,
>       loader_id?: string | null,
>       nav_seq?: number | null,
>       session_id?: string | null,
>       target_id?: string | null,
>       target_type?: string | null,
>       url?: string | null,
>       from_x?: number | null,
>       from_y?: number | null,
>       target_selector?: string | null,
>       to_x?: number | null,
>       to_y?: number | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       png?: string | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       reason?: string | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       reconnect_duration_ms?: number | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       reason?: string | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       step?: string | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       code?: string | null,
>       duration_ms?: number | null,
>       operation_id?: string | null,
>       request_id?: string | null,
>       status?: number | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       duration_ms?: number | null,
>       operation_id?: string | null,
>       request_id?: string | null,
>       status?: number | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       button?: string | null,
>       buttons?: number | null,
>       click_count?: number | null,
>       command_id?: number | null,
>       connection_id?: string | null,
>       delta_x?: number | null,
>       delta_y?: number | null,
>       event_type?: string | null,
>       force?: number | null,
>       method?: string | null,
>       modifiers?: number | null,
>       pointer_type?: string | null,
>       session_id?: string | null,
>       tangential_pressure?: number | null,
>       tilt_x?: number | null,
>       tilt_y?: number | null,
>       y?: number | null,
>       twist?: number | null,
>       x?: number | null
>     } | {
>       auto_repeat?: boolean | null,
>       command_count?: number | null,
>       command_id?: number | null,
>       connection_id?: string | null,
>       event_type?: string | null,
>       is_keypad?: boolean | null,
>       is_system_key?: boolean | null,
>       location?: number | null,
>       method?: string | null,
>       modifiers?: number | null,
>       named_key?: string | null,
>       session_id?: string | null,
>       text_length?: number | null
>     } | {
>       command_id?: number | null,
>       connection_id?: string | null,
>       method?: string | null,
>       session_id?: string | null,
>       text_length?: number | null
>     } | {
>       command_id?: number | null,
>       connection_id?: string | null,
>       method?: string | null,
>       replacement_end?: number | null,
>       replacement_start?: number | null,
>       selection_end?: number | null,
>       selection_start?: number | null,
>       session_id?: string | null,
>       text_length?: number | null
>     } | {
>       command_id?: number | null,
>       connection_id?: string | null,
>       event_type?: string | null,
>       force?: number | null,
>       method?: string | null,
>       modifiers?: number | null,
>       radius_x?: number | null,
>       radius_y?: number | null,
>       rotation_angle?: number | null,
>       session_id?: string | null,
>       tangential_pressure?: number | null,
>       tilt_x?: number | null,
>       tilt_y?: number | null,
>       touch_point_count?: number | null,
>       y?: number | null,
>       twist?: number | null,
>       x?: number | null
>     } | {
>       command_id?: number | null,
>       connection_id?: string | null,
>       drag_file_count?: number | null,
>       drag_item_count?: number | null,
>       drag_mime_categories?: string[] | null,
>       drag_operations_mask?: number | null,
>       event_type?: string | null,
>       method?: string | null,
>       modifiers?: number | null,
>       session_id?: string | null,
>       y?: number | null,
>       x?: number | null
>     } | {
>       command_id?: number | null,
>       connection_id?: string | null,
>       method?: string | null,
>       session_id?: string | null
>     } | {
>       button?: string | null,
>       click_count?: number | null,
>       command_id?: number | null,
>       connection_id?: string | null,
>       delta_x?: number | null,
>       delta_y?: number | null,
>       event_type?: string | null,
>       method?: string | null,
>       modifiers?: number | null,
>       session_id?: string | null,
>       y?: number | null,
>       x?: number | null
>     } | {
>       command_id?: number | null,
>       connection_id?: string | null,
>       gesture_source_type?: string | null,
>       method?: string | null,
>       relative_speed?: number | null,
>       scale_factor?: number | null,
>       session_id?: string | null,
>       y?: number | null,
>       x?: number | null
>     } | {
>       command_id?: number | null,
>       connection_id?: string | null,
>       gesture_source_type?: string | null,
>       method?: string | null,
>       prevent_fling?: boolean | null,
>       repeat_count?: number | null,
>       repeat_delay_ms?: number | null,
>       session_id?: string | null,
>       speed?: number | null,
>       y?: number | null,
>       x?: number | null,
>       x_distance?: number | null,
>       x_overscroll?: number | null,
>       y_distance?: number | null,
>       y_overscroll?: number | null
>     } | {
>       command_id?: number | null,
>       connection_id?: string | null,
>       duration?: number | null,
>       gesture_source_type?: string | null,
>       method?: string | null,
>       session_id?: string | null,
>       tap_count?: number | null,
>       y?: number | null,
>       x?: number | null
>     } | {
>       backend_node_id?: number | null,
>       command_id?: number | null,
>       connection_id?: string | null,
>       file_count?: number | null,
>       method?: string | null,
>       node_id?: number | null,
>       object_id?: string | null,
>       session_id?: string | null
>     } | {
>       backend_node_id?: number | null,
>       command_id?: number | null,
>       connection_id?: string | null,
>       method?: string | null,
>       node_id?: number | null,
>       object_id?: string | null,
>       session_id?: string | null
>     } | {
>       backend_node_id?: number | null,
>       command_id?: number | null,
>       connection_id?: string | null,
>       method?: string | null,
>       node_id?: number | null,
>       object_id?: string | null,
>       rect_height?: number | null,
>       rect_width?: number | null,
>       rect_x?: number | null,
>       rect_y?: number | null,
>       session_id?: string | null
>     } | {
>       command_id?: number | null,
>       connection_id?: string | null,
>       method?: string | null,
>       session_id?: string | null
>     } | {
>       capture_beyond_viewport?: boolean | null,
>       clip_height?: number | null,
>       clip_scale?: number | null,
>       clip_width?: number | null,
>       clip_x?: number | null,
>       clip_y?: number | null,
>       command_id?: number | null,
>       connection_id?: string | null,
>       format?: string | null,
>       from_surface?: boolean | null,
>       method?: string | null,
>       optimize_for_speed?: boolean | null,
>       quality?: number | null,
>       session_id?: string | null
>     } | {
>       command_id?: number | null,
>       connection_id?: string | null,
>       format?: string | null,
>       method?: string | null,
>       session_id?: string | null
>     } | {
>       accept?: boolean | null,
>       command_id?: number | null,
>       connection_id?: string | null,
>       method?: string | null,
>       prompt_text_length?: number | null,
>       session_id?: string | null
>     } | {
>       command_id?: number | null,
>       connection_id?: string | null,
>       frame_id?: string | null,
>       method?: string | null,
>       referrer_policy?: string | null,
>       referrer_present?: boolean | null,
>       session_id?: string | null,
>       transition_type?: string | null,
>       url_scheme?: string | null
>     } | {
>       command_id?: number | null,
>       connection_id?: string | null,
>       entry_id?: number | null,
>       method?: string | null,
>       session_id?: string | null
>     } | {
>       command_id?: number | null,
>       connection_id?: string | null,
>       ignore_cache?: boolean | null,
>       loader_id?: string | null,
>       method?: string | null,
>       script_length?: number | null,
>       session_id?: string | null
>     } | {
>       command_id?: number | null,
>       connection_id?: string | null,
>       display_header_footer?: boolean | null,
>       footer_template_present?: boolean | null,
>       generate_document_outline?: boolean | null,
>       generate_tagged_pdf?: boolean | null,
>       header_template_present?: boolean | null,
>       landscape?: boolean | null,
>       margin_bottom?: number | null,
>       margin_left?: number | null,
>       margin_right?: number | null,
>       margin_top?: number | null,
>       method?: string | null,
>       page_ranges_present?: boolean | null,
>       paper_height?: number | null,
>       paper_width?: number | null,
>       prefer_css_page_size?: boolean | null,
>       print_background?: boolean | null,
>       scale?: number | null,
>       session_id?: string | null,
>       transfer_mode?: string | null
>     } | {
>       command_id?: number | null,
>       connection_id?: string | null,
>       every_nth_frame?: number | null,
>       format?: string | null,
>       max_height?: number | null,
>       max_width?: number | null,
>       method?: string | null,
>       quality?: number | null,
>       session_id?: string | null
>     } | {
>       command_id?: number | null,
>       connection_id?: string | null,
>       method?: string | null,
>       session_id?: string | null
>     } | {
>       command_id?: number | null,
>       connection_id?: string | null,
>       method?: string | null,
>       session_id?: string | null
>     } | {
>       command_id?: number | null,
>       connection_id?: string | null,
>       method?: string | null,
>       session_id?: string | null
>     } | {
>       command_id?: number | null,
>       connection_id?: string | null,
>       method?: string | null,
>       session_id?: string | null,
>       state?: string | null
>     } | {
>       command_id?: number | null,
>       connection_id?: string | null,
>       method?: string | null,
>       session_id?: string | null,
>       target_id?: string | null
>     } | {
>       command_id?: number | null,
>       connection_id?: string | null,
>       method?: string | null,
>       session_id?: string | null,
>       target_id?: string | null
>     } | {
>       background?: boolean | null,
>       browser_context_id?: string | null,
>       command_id?: number | null,
>       connection_id?: string | null,
>       enable_begin_frame_control?: boolean | null,
>       focus?: boolean | null,
>       for_tab?: boolean | null,
>       height?: number | null,
>       hidden?: boolean | null,
>       left?: number | null,
>       method?: string | null,
>       new_window?: boolean | null,
>       session_id?: string | null,
>       top?: number | null,
>       url_scheme?: string | null,
>       width?: number | null,
>       window_state?: string | null
>     } | {
>       command_id?: number | null,
>       connection_id?: string | null,
>       dispose_on_detach?: boolean | null,
>       method?: string | null,
>       proxy_bypass_list_present?: boolean | null,
>       proxy_server_present?: boolean | null,
>       session_id?: string | null,
>       universal_network_access_origin_count?: number | null
>     } | {
>       browser_context_id?: string | null,
>       command_id?: number | null,
>       connection_id?: string | null,
>       method?: string | null,
>       session_id?: string | null
>     } | {
>       command_id?: number | null,
>       connection_id?: string | null,
>       method?: string | null,
>       panel_id?: string | null,
>       session_id?: string | null,
>       target_id?: string | null
>     } | {
>       browser_context_id?: string | null,
>       command_id?: number | null,
>       connection_id?: string | null,
>       download_guid?: string | null,
>       method?: string | null,
>       session_id?: string | null
>     } | {
>       command_id?: number | null,
>       connection_id?: string | null,
>       method?: string | null,
>       session_id?: string | null
>     } | {
>       command_id?: number | null,
>       connection_id?: string | null,
>       height?: number | null,
>       left?: number | null,
>       method?: string | null,
>       session_id?: string | null,
>       top?: number | null,
>       width?: number | null,
>       window_id?: number | null,
>       window_state?: string | null
>     } | {
>       command_id?: number | null,
>       connection_id?: string | null,
>       height?: number | null,
>       method?: string | null,
>       session_id?: string | null,
>       width?: number | null,
>       window_id?: number | null
>     } | {
>       address_field_count?: number | null,
>       command_id?: number | null,
>       connection_id?: string | null,
>       field_id?: number | null,
>       frame_id?: string | null,
>       method?: string | null,
>       mode?: string | null,
>       session_id?: string | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       connection_id?: string | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       connection_id?: string | null,
>       duration_ms?: number | null,
>       message_count?: number | null,
>       reason?: string | null,
>       telemetry_dropped?: number | null,
>       telemetry_excluded?: number | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       session_id?: string | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       duration_ms?: number | null,
>       session_id?: string | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       captcha_provider?: string | null,
>       captcha_type?: string | null,
>       challenge_id?: string | null,
>       media?: string | null,
>       task_id?: string | null,
>       task_kind?: string | null,
>       website_host?: string | null,
>       website_path?: string | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       captcha_provider?: string | null,
>       captcha_type?: string | null,
>       challenge_id?: string | null,
>       duration_ms?: number | null,
>       error_code?: string | null,
>       media?: string | null,
>       status?: string | null,
>       task_id?: string | null,
>       task_kind?: string | null,
>       website_host?: string | null,
>       website_path?: string | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       captcha_provider?: string | null,
>       captcha_type?: string | null,
>       challenge_id?: string | null,
>       duration_ms?: number | null,
>       inferred?: boolean | null,
>       status?: string | null,
>       task_id?: string | null,
>       website_host?: string | null,
>       website_path?: string | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       constraint?: string | null,
>       mem_free_kb?: number | null,
>       mem_total_kb?: number | null,
>       pid?: number | null,
>       process_name?: string | null,
>       rss_kb?: number | null,
>       top_tasks?: {
>         name?: string | null,
>         pid?: number | null,
>         rss_kb?: number | null
>       }[] | null,
>       trigger_pid?: number | null,
>       trigger_process_name?: string | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | {
>     category?: string | null,
>     data?: {
>       phase?: string | null,
>       pid?: number | null,
>       service_name?: string | null
>     } | null,
>     source?: {
>       event?: string | null,
>       kind?: string | null,
>       metadata?: Record<string, string> | null
>     } | null,
>     truncated?: boolean | null,
>     ts?: number | null,
>     type?: string | null
>   } | null,
>   seq?: number | null
> }[]
> ```

***

### update

`browsers.update`

Change a running browser: rename it, change its proxy, viewport or tags, or attach a profile it was started without.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.update({ id_or_name: 'htzv5orfit78e1m2biiifpbv' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `disable_default_proxy` | `boolean` | No | If true, stealth browsers connect directly instead of using the default stealth proxy. Deprecated in favor of proxy.mode. |
| `location` | `object` | No | — |
| `name` | `string \| null` | No | Human-readable name for the browser session. Omit to leave unchanged, set to an empty string to clear the name. When set, must be unique among active sessions within the project. |
| `network` | `object` | No | — |
| `profile` | `object` | No | — |
| `proxy` | `object` | No | — |
| `proxy_id` | `string \| null` | No | ID of the proxy to use. Omit to leave unchanged, set to empty string to remove proxy. Deprecated in favor of proxy. |
| `start_url` | `string` | No | Optional URL to navigate the browser to after applying this update. When a profile is loaded in the same update, this overrides the profile's restored tabs. Navigation is best-effort, so failures do not fail the update. Omit or set to an empty string to leave the current page unchanged. |
| `tags` | `Record<string, string> \| null` | No | — |
| `telemetry` | `object \| null` | No | — |
| `viewport` | `object` | No | — |

> [accordion] location full type
>
> ```ts theme={null}
> {
>   locale?: string | null,
>   timezone?: string | null
> }
> ```

> [accordion] network full type
>
> ```ts theme={null}
> {
>   allowed_hosts?: string[] | null,
>   expected_allowlist_revision?: string,
>   mutation_id?: string
> }
> ```

> [accordion] profile full type
>
> ```ts theme={null}
> {
>   id?: string,
>   name?: string,
>   save_changes?: boolean
> }
> ```

> [accordion] proxy full type
>
> ```ts theme={null}
> {
>   id?: string,
>   mode?: direct | default,
>   name?: string
> }
> ```

> [accordion] telemetry full type
>
> ```ts theme={null}
> {
>   browser?: {
>     captcha?: {
>       enabled?: boolean
>     },
>     connection?: {
>       enabled?: boolean
>     },
>     console?: {
>       enabled?: boolean
>     },
>     control?: {
>       cdp?: {
>         excluded_methods?: (Input.dispatchMouseEvent | Input.dispatchKeyEvent | Input.insertText | Input.imeSetComposition | Input.dispatchTouchEvent | Input.dispatchDragEvent | Input.cancelDragging | Input.emulateTouchFromMouseEvent | Input.synthesizePinchGesture | Input.synthesizeScrollGesture | Input.synthesizeTapGesture | DOM.setFileInputFiles | DOM.focus | DOM.scrollIntoViewIfNeeded | Page.bringToFront | Page.captureScreenshot | Page.captureSnapshot | Page.handleJavaScriptDialog | Page.navigate | Page.navigateToHistoryEntry | Page.reload | Page.printToPDF | Page.startScreencast | Page.stopScreencast | Page.stopLoading | Page.close | Page.setWebLifecycleState | Target.activateTarget | Target.closeTarget | Target.createTarget | Target.createBrowserContext | Target.disposeBrowserContext | Target.openDevTools | Browser.cancelDownload | Browser.close | Browser.setWindowBounds | Browser.setContentsSize | Autofill.trigger)[]
>       },
>       enabled?: boolean
>     },
>     interaction?: {
>       enabled?: boolean
>     },
>     network?: {
>       enabled?: boolean
>     },
>     page?: {
>       enabled?: boolean
>     },
>     platform?: {
>       enabled?: boolean
>     },
>     screenshot?: {
>       enabled?: boolean
>     },
>     system?: {
>       enabled?: boolean
>     }
>   },
>   enabled?: boolean,
>   export?: {
>     otlp?: {
>       destination?: {
>         id?: string,
>         name?: string
>       },
>       enabled?: boolean
>     }
>   },
>   storage?: {
>     enabled?: boolean
>   }
> } | null
> ```

> [accordion] viewport full type
>
> ```ts theme={null}
> {
>   height: number,
>   refresh_rate?: number,
>   width: number,
>   force?: boolean
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `base_url` | `string \| null` | No | Metro-API HTTP base URL for this browser session. |
| `browser_live_view_url` | `string \| null` | No | Remote URL for live viewing the browser session. Only available for non-headless browsers. |
| `captcha_solver` | `object \| null` | No | — |
| `cdp_ws_url` | `string \| null` | No | Websocket URL for Chrome DevTools Protocol connections to the browser session |
| `chrome_policy` | `object \| null` | No | Custom Chrome enterprise policy overrides that were applied to this browser session, if any. Echoed back for verification. Keys are Chrome enterprise policy names. |
| `cost` | `object \| null` | No | — |
| `created_at` | `string \| null` | No | When the browser session was created. |
| `deleted_at` | `string \| null` | No | When the browser session was soft-deleted. Only present for deleted sessions. |
| `fingerprint` | `object \| null` | No | — |
| `gpu` | `boolean \| null` | No | Whether GPU acceleration is enabled for the browser session (only supported for headful sessions). |
| `headless` | `boolean \| null` | No | Whether the browser session is running in headless mode. |
| `kiosk_mode` | `boolean \| null` | No | Whether the browser session is running in kiosk mode. |
| `leased_at` | `string \| null` | No | When the pooled browser session was last leased. Only present for leased pooled sessions. |
| `location` | `object \| null` | No | — |
| `memory` | `string \| null` | No | — |
| `name` | `string \| null` | No | Human-readable name of the browser session, if one was set at creation. |
| `network` | `object \| null` | No | — |
| `pool` | `object \| null` | No | — |
| `profile` | `object \| null` | No | — |
| `profile_save_changes` | `boolean \| null` | No | Whether changes made during this browser session are saved back to its profile when the session ends. Omitted when no profile is attached. |
| `proxy` | `object \| null` | No | — |
| `proxy_id` | `string \| null` | No | ID of the proxy associated with this browser session, if any. Deprecated in favor of proxy. |
| `region` | `string \| null` | No | — |
| `replay` | `object \| null` | No | — |
| `session_id` | `string \| null` | No | Unique identifier for the browser session |
| `start_url` | `string \| null` | No | URL the session was most recently asked to navigate to, if any. Recorded for debugging. Navigation is fire-and-forget — the URL is dispatched to the browser without waiting for it to load, and any errors (DNS failure, bad status, timeout) are silently dropped. Captures what was requested, not what the browser actually loaded. |
| `stealth` | `boolean \| null` | No | Whether the browser session has CAPTCHA solving enabled, in which case proxy.mode=default uses Kernel's default stealth proxy. A browser created with only captcha\_solver reports true with proxy.mode=direct. Deprecated in favor of captcha\_solver and proxy. |
| `tags` | `Record<string, string> \| null` | No | — |
| `telemetry` | `object \| null` | No | — |
| `timeout_seconds` | `number \| null` | No | The number of seconds of inactivity before the browser session is terminated. |
| `usage` | `object \| null` | No | — |
| `usage_status` | `string \| null` | No | — |
| `vaults` | `object[] \| null` | No | Vaults linked when the browser session was created. |
| `video_memory` | `string \| null` | No | — |
| `viewport` | `object \| null` | No | — |
| `webdriver_ws_url` | `string \| null` | No | Websocket URL for WebDriver BiDi connections to the browser session |

> [accordion] captcha\_solver full type
>
> ```ts theme={null}
> {
>   enabled?: boolean | null
> } | null
> ```

> [accordion] chrome\_policy full type
>
> ```ts theme={null}
> {
> } | null
> ```

> [accordion] cost full type
>
> ```ts theme={null}
> {
>   as_of?: string | null,
>   estimated_usage_spend_usd?: string | null,
>   status?: string | null
> } | null
> ```

> [accordion] fingerprint full type
>
> ```ts theme={null}
> {
>   os?: string | null
> } | null
> ```

> [accordion] location full type
>
> ```ts theme={null}
> {
>   locale?: string | null,
>   locale_source?: string | null,
>   timezone?: string | null,
>   timezone_source?: string | null
> } | null
> ```

> [accordion] network full type
>
> ```ts theme={null}
> {
>   allowed_hosts?: string[] | null,
>   allowlist_state?: {
>     base_revision?: string | null,
>     mutation_id?: string | null,
>     revision?: string | null
>   } | null,
>   private_hosts?: string[] | null,
>   proxy_routes?: {
>     hosts?: string[] | null,
>     proxy?: {
>       id?: string | null,
>       name?: string | null
>     } | null
>   }[] | null
> } | null
> ```

> [accordion] pool full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   name?: string | null
> } | null
> ```

> [accordion] profile full type
>
> ```ts theme={null}
> {
>   created_at?: string | null,
>   id?: string | null,
>   last_used_at?: string | null,
>   name?: string | null | null,
>   updated_at?: string | null
> } | null
> ```

> [accordion] proxy full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   mode?: string | null,
>   name?: string | null
> } | null
> ```

> [accordion] replay full type
>
> ```ts theme={null}
> {
>   finished_at?: string | null | null,
>   replay_id?: string | null,
>   replay_view_url?: string | null,
>   started_at?: string | null | null
> } | null
> ```

> [accordion] telemetry full type
>
> ```ts theme={null}
> {
>   browser?: {
>     captcha?: {
>       enabled?: boolean | null
>     } | null,
>     connection?: {
>       enabled?: boolean | null
>     } | null,
>     console?: {
>       enabled?: boolean | null
>     } | null,
>     control?: {
>       cdp?: {
>         excluded_methods?: string[] | null
>       } | null,
>       enabled?: boolean | null
>     } | null,
>     interaction?: {
>       enabled?: boolean | null
>     } | null,
>     network?: {
>       enabled?: boolean | null
>     } | null,
>     page?: {
>       enabled?: boolean | null
>     } | null,
>     platform?: {
>       enabled?: boolean | null
>     } | null,
>     screenshot?: {
>       enabled?: boolean | null
>     } | null,
>     system?: {
>       enabled?: boolean | null
>     } | null
>   } | null,
>   export?: {
>     otlp?: {
>       destination?: string | null,
>       enabled?: boolean | null
>     } | null
>   } | null,
>   storage?: {
>     enabled?: boolean | null
>   } | null
> } | null | null
> ```

> [accordion] usage full type
>
> ```ts theme={null}
> {
>   uptime_ms?: number | null
> } | null
> ```

> [accordion] vaults full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   name?: string | null
> }[] | null
> ```

> [accordion] viewport full type
>
> ```ts theme={null}
> {
>   height?: number | null,
>   refresh_rate?: number | null,
>   width?: number | null
> } | null
> ```

***

### webmcp.customTools.add

`browsers.webmcp.customTools.add`

Register custom WebMCP tools (JavaScript run in a page) on a browser's tabs.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.webmcp.customTools.add({ id_or_name: 'htzv5orfit78e1m2biiifpbv', namespace: 'acme', source: 'export default { name: "ping", execute: () => "pong" };' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `force_overwrite_namespace` | `boolean` | No | Atomically replace all existing tools in this namespace with this batch when true. |
| `namespace` | `string` | Yes | — |
| `source` | `string` | Yes | JavaScript expression that evaluates to a non-empty array of custom tool definitions. Limited to 8,000,000 bytes when UTF-8 encoded, so multi-byte characters reduce the allowed character count. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `tools` | `object[] \| null` | No | — |

> [accordion] tools full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   kind?: string | null,
>   match?: {
>     url_patterns?: string[] | null
>   } | null,
>   namespace?: string | null,
>   tool?: {
>     annotations?: {
>       autosubmit?: boolean | null,
>       consequentialHint?: boolean | null,
>       destructiveHint?: boolean | null,
>       idempotentHint?: boolean | null,
>       openWorldHint?: boolean | null,
>       readOnlyHint?: boolean | null,
>       untrustedContentHint?: boolean | null
>     } | null,
>     description?: string | null,
>     inputSchema?: {
>     } | null,
>     name?: string | null,
>     outputSchema?: {
>     } | null,
>     title?: string | null
>   } | null
> }[] | null
> ```

***

### webmcp.customTools.list

`browsers.webmcp.customTools.list`

List the custom WebMCP tools registered on a browser.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.browsers.webmcp.customTools.list({ id_or_name: 'htzv5orfit78e1m2biiifpbv' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `tools` | `object[] \| null` | No | — |

> [accordion] tools full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   kind?: string | null,
>   match?: {
>     url_patterns?: string[] | null
>   } | null,
>   namespace?: string | null,
>   tool?: {
>     annotations?: {
>       autosubmit?: boolean | null,
>       consequentialHint?: boolean | null,
>       destructiveHint?: boolean | null,
>       idempotentHint?: boolean | null,
>       openWorldHint?: boolean | null,
>       readOnlyHint?: boolean | null,
>       untrustedContentHint?: boolean | null
>     } | null,
>     description?: string | null,
>     inputSchema?: {
>     } | null,
>     name?: string | null,
>     outputSchema?: {
>     } | null,
>     title?: string | null
>   } | null
> }[] | null
> ```

***

### webmcp.customTools.remove

`browsers.webmcp.customTools.remove`

Remove a custom WebMCP tool from a browser by its id.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.kernel.api.browsers.webmcp.customTools.remove({ id_or_name: 'htzv5orfit78e1m2biiifpbv', id: 'browser_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `id` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### webmcp.invokeTool

`browsers.webmcp.invokeTool`

Call a WebMCP tool a page exposes, by the tool\_ref from browsers.webmcp.listTools, with its input.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.browsers.webmcp.invokeTool({
	id_or_name: 'htzv5orfit78e1m2biiifpbv',
	tool_ref: 'tool_ref_from_list_tools',
	input: { key: 'value' },
});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Browser session ID or name |
| `input` | `object` | Yes | Tool input, limited to 4 MiB after JSON serialization. |
| `timeout_sec` | `number` | No | — |
| `tool_ref` | `string` | Yes | — |

> [accordion] input full type
>
> ```ts theme={null}
> {
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `error_text` | `string \| null` | No | — |
| `invocation_id` | `string \| null` | No | — |
| `output` | `any \| null` | No | Untrusted page-provided output. Callers must treat it as potentially malicious input. |
| `status` | `string \| null` | No | awaiting\_submission means a non-autosubmit declarative form was populated but not submitted. Inspect the form, obtain any required confirmation, then submit through Playwright or computer interaction without invoking the tool again. The other statuses are terminal results. |

***

### webmcp.listTools

`browsers.webmcp.listTools`

List the WebMCP tools that open pages expose (native and custom), each with a tool\_ref to call it with browsers.webmcp.invokeTool. Tools vanish when their page navigates away.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.browsers.webmcp.listTools({ id_or_name: 'htzv5orfit78e1m2biiifpbv' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `exclude_custom` | `boolean` | No | Exclude custom tools when true. |
| `id_or_name` | `string` | Yes | Browser session ID or name |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `tools` | `object[] \| null` | No | — |

> [accordion] tools full type
>
> ```ts theme={null}
> {
>   source?: {
>     custom?: {
>       id?: string | null,
>       namespace?: string | null
>     } | null,
>     frame?: {
>       frame_id?: number | null,
>       url?: string | null
>     } | null | null,
>     page_title?: string | null,
>     page_url?: string | null,
>     tab_id?: number | null,
>     target_id?: string | null,
>     window_id?: number | null
>   } | null,
>   tool?: {
>     annotations?: {
>       autosubmit?: boolean | null,
>       consequentialHint?: boolean | null,
>       destructiveHint?: boolean | null,
>       idempotentHint?: boolean | null,
>       openWorldHint?: boolean | null,
>       readOnlyHint?: boolean | null,
>       untrustedContentHint?: boolean | null
>     } | null,
>     description?: string | null,
>     inputSchema?: {
>     } | null,
>     name?: string | null,
>     outputSchema?: {
>     } | null,
>     title?: string | null
>   } | null,
>   tool_ref?: string | null
> }[] | null
> ```

***

## Config Registry

### analyses.cancel

`configRegistry.analyses.cancel`

Cancel a running config analysis.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.configRegistry.analyses.cancel({ id: 'configRegistry_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `analysis` | `object \| null` | No | Pollable analysis after workflow submission is acknowledged. Null when no refresh was submitted. |
| `guidance` | `string \| null \| null` | No | Short advisory markdown to facilitate navigating this target. Returned even when no configuration reached the target, since knowing what prevented success is useful without a configuration. Not verified against this target. Null when nothing applicable was observed or no notes exist. |
| `recommendation` | `object \| null` | No | Recommendation or structured no-recommendation result for a completed analysis. Null before the analysis produces an outcome. |
| `target` | `object \| null` | No | — |
| `working_configurations` | `object[] \| null` | No | Working configurations for the target, ordered with the recommended configuration first. |
| `workload_outcome` | `string \| null \| null` | No | How far the workload pass got, when an intent was supplied and a pass ran. A run outcome rather than advice, so it is reported whether or not any guidance could be assembled. Null when no intent was supplied or no pass ran. |

> [accordion] analysis full type
>
> ```ts theme={null}
> {
>   created_at?: string | null,
>   expires_at?: string | null,
>   failure?: {
>     code?: string | null,
>     details?: {
>       code?: string | null,
>       message?: string | null
>     }[] | null,
>     inner_error?: {
>       code?: string | null,
>       message?: string | null
>     } | null,
>     message?: string | null
>   } | null | null,
>   finished_at?: string | null | null,
>   id?: string | null,
>   intent?: string | null | null,
>   status?: string | null
> } | null | null
> ```

> [accordion] recommendation full type
>
> ```ts theme={null}
> {
>   browser?: {
>     gpu?: boolean | null,
>     headless?: boolean | null,
>     stealth?: boolean | null,
>     viewport?: {
>       height?: number | null,
>       refresh_rate?: number | null,
>       width?: number | null
>     } | null
>   } | null,
>   evidence?: {
>     accessed?: number | null,
>     blocked?: number | null,
>     inconclusive?: number | null,
>     last_observed_at?: string | null,
>     last_supported_at?: string | null | null,
>     run_count?: number | null,
>     sample_size?: number | null,
>     success_rate?: number | null
>   } | null,
>   match_scope?: string | null,
>   matched_target?: string | null,
>   proxy?: {
>     mode?: string | null
>   } | {
>     create?: {
>       bypass_hosts?: string[] | null,
>       config?: {
>         country?: string | null
>       } | {
>         country?: string | null,
>         ip_address?: string | null
>       } | {
>         asn?: string | null,
>         city?: string | null,
>         country?: string | null,
>         os?: string | null,
>         state?: string | null,
>         zip?: string | null
>       } | {
>         city?: string | null,
>         country?: string | null,
>         state?: string | null
>       } | {
>         ca_bundle?: string | null,
>         host?: string | null,
>         password?: string | null,
>         port?: number | null,
>         username?: string | null
>       } | null,
>       name?: string | null,
>       protocol?: string | null,
>       type?: string | null
>     } | null,
>     mode?: string | null
>   } | null,
>   type?: string | null
> } | {
>   code?: string | null,
>   message?: string | null,
>   type?: string | null
> } | null | null
> ```

> [accordion] target full type
>
> ```ts theme={null}
> {
>   domain?: string | null,
>   host?: string | null,
>   normalized?: string | null
> } | null
> ```

> [accordion] working\_configurations full type
>
> ```ts theme={null}
> {
>   browser?: {
>     gpu?: boolean | null,
>     headless?: boolean | null,
>     stealth?: boolean | null,
>     viewport?: {
>       height?: number | null,
>       refresh_rate?: number | null,
>       width?: number | null
>     } | null
>   } | null,
>   evidence?: {
>     accessed?: number | null,
>     blocked?: number | null,
>     inconclusive?: number | null,
>     last_observed_at?: string | null,
>     last_supported_at?: string | null | null,
>     run_count?: number | null,
>     sample_size?: number | null,
>     success_rate?: number | null
>   } | null,
>   match_scope?: string | null,
>   matched_target?: string | null,
>   proxy?: {
>     mode?: string | null
>   } | {
>     create?: {
>       bypass_hosts?: string[] | null,
>       config?: {
>         country?: string | null
>       } | {
>         country?: string | null,
>         ip_address?: string | null
>       } | {
>         asn?: string | null,
>         city?: string | null,
>         country?: string | null,
>         os?: string | null,
>         state?: string | null,
>         zip?: string | null
>       } | {
>         city?: string | null,
>         country?: string | null,
>         state?: string | null
>       } | {
>         ca_bundle?: string | null,
>         host?: string | null,
>         password?: string | null,
>         port?: number | null,
>         username?: string | null
>       } | null,
>       name?: string | null,
>       protocol?: string | null,
>       type?: string | null
>     } | null,
>     mode?: string | null
>   } | null,
>   type?: string | null
> }[] | null
> ```

***

### analyses.get

`configRegistry.analyses.get`

Get a config analysis and its result.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.configRegistry.analyses.get({ id: 'configRegistry_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `analysis` | `object \| null` | No | Pollable analysis after workflow submission is acknowledged. Null when no refresh was submitted. |
| `guidance` | `string \| null \| null` | No | Short advisory markdown to facilitate navigating this target. Returned even when no configuration reached the target, since knowing what prevented success is useful without a configuration. Not verified against this target. Null when nothing applicable was observed or no notes exist. |
| `recommendation` | `object \| null` | No | Recommendation or structured no-recommendation result for a completed analysis. Null before the analysis produces an outcome. |
| `target` | `object \| null` | No | — |
| `working_configurations` | `object[] \| null` | No | Working configurations for the target, ordered with the recommended configuration first. |
| `workload_outcome` | `string \| null \| null` | No | How far the workload pass got, when an intent was supplied and a pass ran. A run outcome rather than advice, so it is reported whether or not any guidance could be assembled. Null when no intent was supplied or no pass ran. |

> [accordion] analysis full type
>
> ```ts theme={null}
> {
>   created_at?: string | null,
>   expires_at?: string | null,
>   failure?: {
>     code?: string | null,
>     details?: {
>       code?: string | null,
>       message?: string | null
>     }[] | null,
>     inner_error?: {
>       code?: string | null,
>       message?: string | null
>     } | null,
>     message?: string | null
>   } | null | null,
>   finished_at?: string | null | null,
>   id?: string | null,
>   intent?: string | null | null,
>   status?: string | null
> } | null | null
> ```

> [accordion] recommendation full type
>
> ```ts theme={null}
> {
>   browser?: {
>     gpu?: boolean | null,
>     headless?: boolean | null,
>     stealth?: boolean | null,
>     viewport?: {
>       height?: number | null,
>       refresh_rate?: number | null,
>       width?: number | null
>     } | null
>   } | null,
>   evidence?: {
>     accessed?: number | null,
>     blocked?: number | null,
>     inconclusive?: number | null,
>     last_observed_at?: string | null,
>     last_supported_at?: string | null | null,
>     run_count?: number | null,
>     sample_size?: number | null,
>     success_rate?: number | null
>   } | null,
>   match_scope?: string | null,
>   matched_target?: string | null,
>   proxy?: {
>     mode?: string | null
>   } | {
>     create?: {
>       bypass_hosts?: string[] | null,
>       config?: {
>         country?: string | null
>       } | {
>         country?: string | null,
>         ip_address?: string | null
>       } | {
>         asn?: string | null,
>         city?: string | null,
>         country?: string | null,
>         os?: string | null,
>         state?: string | null,
>         zip?: string | null
>       } | {
>         city?: string | null,
>         country?: string | null,
>         state?: string | null
>       } | {
>         ca_bundle?: string | null,
>         host?: string | null,
>         password?: string | null,
>         port?: number | null,
>         username?: string | null
>       } | null,
>       name?: string | null,
>       protocol?: string | null,
>       type?: string | null
>     } | null,
>     mode?: string | null
>   } | null,
>   type?: string | null
> } | {
>   code?: string | null,
>   message?: string | null,
>   type?: string | null
> } | null | null
> ```

> [accordion] target full type
>
> ```ts theme={null}
> {
>   domain?: string | null,
>   host?: string | null,
>   normalized?: string | null
> } | null
> ```

> [accordion] working\_configurations full type
>
> ```ts theme={null}
> {
>   browser?: {
>     gpu?: boolean | null,
>     headless?: boolean | null,
>     stealth?: boolean | null,
>     viewport?: {
>       height?: number | null,
>       refresh_rate?: number | null,
>       width?: number | null
>     } | null
>   } | null,
>   evidence?: {
>     accessed?: number | null,
>     blocked?: number | null,
>     inconclusive?: number | null,
>     last_observed_at?: string | null,
>     last_supported_at?: string | null | null,
>     run_count?: number | null,
>     sample_size?: number | null,
>     success_rate?: number | null
>   } | null,
>   match_scope?: string | null,
>   matched_target?: string | null,
>   proxy?: {
>     mode?: string | null
>   } | {
>     create?: {
>       bypass_hosts?: string[] | null,
>       config?: {
>         country?: string | null
>       } | {
>         country?: string | null,
>         ip_address?: string | null
>       } | {
>         asn?: string | null,
>         city?: string | null,
>         country?: string | null,
>         os?: string | null,
>         state?: string | null,
>         zip?: string | null
>       } | {
>         city?: string | null,
>         country?: string | null,
>         state?: string | null
>       } | {
>         ca_bundle?: string | null,
>         host?: string | null,
>         password?: string | null,
>         port?: number | null,
>         username?: string | null
>       } | null,
>       name?: string | null,
>       protocol?: string | null,
>       type?: string | null
>     } | null,
>     mode?: string | null
>   } | null,
>   type?: string | null
> }[] | null
> ```

***

### analyses.list

`configRegistry.analyses.list`

List config analyses.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.configRegistry.analyses.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `limit` | `number` | No | — |
| `offset` | `number` | No | — |
| `search` | `string` | No | Case-insensitive substring search over requested URLs. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | This page of results. |
| `has_more` | `boolean` | Yes | True when more results follow; pass next\_offset as offset to read them. |
| `next_offset` | `number \| null` | Yes | Value for `offset` that reads the next page, or null on the last page. |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   analysis?: {
>     created_at?: string | null,
>     expires_at?: string | null,
>     failure?: {
>       code?: string | null,
>       details?: {
>         code?: string | null,
>         message?: string | null
>       }[] | null,
>       inner_error?: {
>         code?: string | null,
>         message?: string | null
>       } | null,
>       message?: string | null
>     } | null | null,
>     finished_at?: string | null | null,
>     id?: string | null,
>     intent?: string | null | null,
>     status?: string | null
>   } | null,
>   target?: {
>     domain?: string | null,
>     host?: string | null,
>     normalized?: string | null
>   } | null
> }[]
> ```

***

### list

`configRegistry.list`

List known site configurations.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.configRegistry.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `limit` | `number` | No | — |
| `offset` | `number` | No | — |
| `search` | `string` | No | Case-insensitive substring search over normalized targets, including domain, subdomain, and path. |
| `sort_by` | `target \| analysis_status \| recommended_config \| last_requested_at \| success_rate` | No | — |
| `sort_order` | `asc \| desc` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | This page of results. |
| `has_more` | `boolean` | Yes | True when more results follow; pass next\_offset as offset to read them. |
| `next_offset` | `number \| null` | Yes | Value for `offset` that reads the next page, or null on the last page. |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   analysis_id?: string | null,
>   analysis_status?: string | null,
>   last_requested_at?: string | null,
>   recommendation?: {
>     browser?: {
>       gpu?: boolean | null,
>       headless?: boolean | null,
>       stealth?: boolean | null,
>       viewport?: {
>         height?: number | null,
>         refresh_rate?: number | null,
>         width?: number | null
>       } | null
>     } | null,
>     evidence?: {
>       accessed?: number | null,
>       blocked?: number | null,
>       inconclusive?: number | null,
>       last_observed_at?: string | null,
>       last_supported_at?: string | null | null,
>       run_count?: number | null,
>       sample_size?: number | null,
>       success_rate?: number | null
>     } | null,
>     match_scope?: string | null,
>     matched_target?: string | null,
>     proxy?: {
>       mode?: string | null
>     } | {
>       create?: {
>         bypass_hosts?: string[] | null,
>         config?: {
>           country?: string | null
>         } | {
>           country?: string | null,
>           ip_address?: string | null
>         } | {
>           asn?: string | null,
>           city?: string | null,
>           country?: string | null,
>           os?: string | null,
>           state?: string | null,
>           zip?: string | null
>         } | {
>           city?: string | null,
>           country?: string | null,
>           state?: string | null
>         } | {
>           ca_bundle?: string | null,
>           host?: string | null,
>           password?: string | null,
>           port?: number | null,
>           username?: string | null
>         } | null,
>         name?: string | null,
>         protocol?: string | null,
>         type?: string | null
>       } | null,
>       mode?: string | null
>     } | null,
>     type?: string | null
>   } | null | null,
>   recommended_config_label?: string | null | null,
>   success_rate?: number | null | null,
>   target?: string | null
> }[]
> ```

***

### lookup

`configRegistry.lookup`

Look up Kernel's recommended browser and proxy settings for a bot-protected site (no side effects).

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.configRegistry.lookup({ url: 'https://example.com' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `allowed_proxy_countries` | `string[]` | No | ISO 3166 country codes Kernel may use when returning a proxy configuration. When omitted, Kernel uses its default country selection. |
| `url` | `string` | Yes | Public HTTP(S) URL to look up. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `guidance` | `string \| null \| null` | No | Short advisory markdown to facilitate navigating this target. Returned even when no configuration reached the target, since knowing what prevented success is useful without a configuration. Not verified against this target. Null when nothing applicable was observed or no notes exist. |
| `recommendation` | `object \| null` | No | Recommendation or structured no-recommendation result from current knowledge. Only the proxy\_restricted code is reported here. Null for every other outcome, including a target analyzed without a working configuration. |
| `target` | `object \| null` | No | — |
| `working_configurations` | `object[] \| null` | No | Working configurations for the target, ordered with the recommended configuration first. |

> [accordion] recommendation full type
>
> ```ts theme={null}
> {
>   browser?: {
>     gpu?: boolean | null,
>     headless?: boolean | null,
>     stealth?: boolean | null,
>     viewport?: {
>       height?: number | null,
>       refresh_rate?: number | null,
>       width?: number | null
>     } | null
>   } | null,
>   evidence?: {
>     accessed?: number | null,
>     blocked?: number | null,
>     inconclusive?: number | null,
>     last_observed_at?: string | null,
>     last_supported_at?: string | null | null,
>     run_count?: number | null,
>     sample_size?: number | null,
>     success_rate?: number | null
>   } | null,
>   match_scope?: string | null,
>   matched_target?: string | null,
>   proxy?: {
>     mode?: string | null
>   } | {
>     create?: {
>       bypass_hosts?: string[] | null,
>       config?: {
>         country?: string | null
>       } | {
>         country?: string | null,
>         ip_address?: string | null
>       } | {
>         asn?: string | null,
>         city?: string | null,
>         country?: string | null,
>         os?: string | null,
>         state?: string | null,
>         zip?: string | null
>       } | {
>         city?: string | null,
>         country?: string | null,
>         state?: string | null
>       } | {
>         ca_bundle?: string | null,
>         host?: string | null,
>         password?: string | null,
>         port?: number | null,
>         username?: string | null
>       } | null,
>       name?: string | null,
>       protocol?: string | null,
>       type?: string | null
>     } | null,
>     mode?: string | null
>   } | null,
>   type?: string | null
> } | {
>   code?: string | null,
>   message?: string | null,
>   type?: string | null
> } | null | null
> ```

> [accordion] target full type
>
> ```ts theme={null}
> {
>   domain?: string | null,
>   host?: string | null,
>   normalized?: string | null
> } | null
> ```

> [accordion] working\_configurations full type
>
> ```ts theme={null}
> {
>   browser?: {
>     gpu?: boolean | null,
>     headless?: boolean | null,
>     stealth?: boolean | null,
>     viewport?: {
>       height?: number | null,
>       refresh_rate?: number | null,
>       width?: number | null
>     } | null
>   } | null,
>   evidence?: {
>     accessed?: number | null,
>     blocked?: number | null,
>     inconclusive?: number | null,
>     last_observed_at?: string | null,
>     last_supported_at?: string | null | null,
>     run_count?: number | null,
>     sample_size?: number | null,
>     success_rate?: number | null
>   } | null,
>   match_scope?: string | null,
>   matched_target?: string | null,
>   proxy?: {
>     mode?: string | null
>   } | {
>     create?: {
>       bypass_hosts?: string[] | null,
>       config?: {
>         country?: string | null
>       } | {
>         country?: string | null,
>         ip_address?: string | null
>       } | {
>         asn?: string | null,
>         city?: string | null,
>         country?: string | null,
>         os?: string | null,
>         state?: string | null,
>         zip?: string | null
>       } | {
>         city?: string | null,
>         country?: string | null,
>         state?: string | null
>       } | {
>         ca_bundle?: string | null,
>         host?: string | null,
>         password?: string | null,
>         port?: number | null,
>         username?: string | null
>       } | null,
>       name?: string | null,
>       protocol?: string | null,
>       type?: string | null
>     } | null,
>     mode?: string | null
>   } | null,
>   type?: string | null
> }[] | null
> ```

***

### resolve

`configRegistry.resolve`

Ask Kernel to analyse a site and work out the browser and proxy settings that get through its bot protection; poll configRegistry.analyses.get.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.configRegistry.resolve({ url: 'https://example.com' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `allowed_proxy_countries` | `string[]` | No | ISO 3166 country codes Kernel may use when searching for or returning a proxy configuration. Kernel may test a subset of allowed countries. When omitted, Kernel uses its default country selection. |
| `intent` | `string` | No | Plain-language description of the workload you intend to run against this target, in a sentence or two. Requires an https target, because the pass treats any non-HTTPS destination as off-site and will not drive an http one. Kernel uses it to drive the browser further into the site, where it can observe protections that only appear once a session interacts. When this target already has a recommended configuration, the run confirms that one instead of re-deriving the whole matrix, so supplying an intent narrows what can be recommended. |
| `url` | `string` | Yes | Public HTTP(S) URL to refresh. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `analysis` | `object \| null` | No | Pollable analysis after workflow submission is acknowledged. Null when no refresh was submitted. |
| `guidance` | `string \| null \| null` | No | Short advisory markdown to facilitate navigating this target. Returned even when no configuration reached the target, since knowing what prevented success is useful without a configuration. Not verified against this target. Null when nothing applicable was observed or no notes exist. |
| `recommendation` | `object \| null` | No | Recommendation or structured no-recommendation result for a completed analysis. Null before the analysis produces an outcome. |
| `target` | `object \| null` | No | — |
| `working_configurations` | `object[] \| null` | No | Working configurations for the target, ordered with the recommended configuration first. |
| `workload_outcome` | `string \| null \| null` | No | How far the workload pass got, when an intent was supplied and a pass ran. A run outcome rather than advice, so it is reported whether or not any guidance could be assembled. Null when no intent was supplied or no pass ran. |

> [accordion] analysis full type
>
> ```ts theme={null}
> {
>   created_at?: string | null,
>   expires_at?: string | null,
>   failure?: {
>     code?: string | null,
>     details?: {
>       code?: string | null,
>       message?: string | null
>     }[] | null,
>     inner_error?: {
>       code?: string | null,
>       message?: string | null
>     } | null,
>     message?: string | null
>   } | null | null,
>   finished_at?: string | null | null,
>   id?: string | null,
>   intent?: string | null | null,
>   status?: string | null
> } | null | null
> ```

> [accordion] recommendation full type
>
> ```ts theme={null}
> {
>   browser?: {
>     gpu?: boolean | null,
>     headless?: boolean | null,
>     stealth?: boolean | null,
>     viewport?: {
>       height?: number | null,
>       refresh_rate?: number | null,
>       width?: number | null
>     } | null
>   } | null,
>   evidence?: {
>     accessed?: number | null,
>     blocked?: number | null,
>     inconclusive?: number | null,
>     last_observed_at?: string | null,
>     last_supported_at?: string | null | null,
>     run_count?: number | null,
>     sample_size?: number | null,
>     success_rate?: number | null
>   } | null,
>   match_scope?: string | null,
>   matched_target?: string | null,
>   proxy?: {
>     mode?: string | null
>   } | {
>     create?: {
>       bypass_hosts?: string[] | null,
>       config?: {
>         country?: string | null
>       } | {
>         country?: string | null,
>         ip_address?: string | null
>       } | {
>         asn?: string | null,
>         city?: string | null,
>         country?: string | null,
>         os?: string | null,
>         state?: string | null,
>         zip?: string | null
>       } | {
>         city?: string | null,
>         country?: string | null,
>         state?: string | null
>       } | {
>         ca_bundle?: string | null,
>         host?: string | null,
>         password?: string | null,
>         port?: number | null,
>         username?: string | null
>       } | null,
>       name?: string | null,
>       protocol?: string | null,
>       type?: string | null
>     } | null,
>     mode?: string | null
>   } | null,
>   type?: string | null
> } | {
>   code?: string | null,
>   message?: string | null,
>   type?: string | null
> } | null | null
> ```

> [accordion] target full type
>
> ```ts theme={null}
> {
>   domain?: string | null,
>   host?: string | null,
>   normalized?: string | null
> } | null
> ```

> [accordion] working\_configurations full type
>
> ```ts theme={null}
> {
>   browser?: {
>     gpu?: boolean | null,
>     headless?: boolean | null,
>     stealth?: boolean | null,
>     viewport?: {
>       height?: number | null,
>       refresh_rate?: number | null,
>       width?: number | null
>     } | null
>   } | null,
>   evidence?: {
>     accessed?: number | null,
>     blocked?: number | null,
>     inconclusive?: number | null,
>     last_observed_at?: string | null,
>     last_supported_at?: string | null | null,
>     run_count?: number | null,
>     sample_size?: number | null,
>     success_rate?: number | null
>   } | null,
>   match_scope?: string | null,
>   matched_target?: string | null,
>   proxy?: {
>     mode?: string | null
>   } | {
>     create?: {
>       bypass_hosts?: string[] | null,
>       config?: {
>         country?: string | null
>       } | {
>         country?: string | null,
>         ip_address?: string | null
>       } | {
>         asn?: string | null,
>         city?: string | null,
>         country?: string | null,
>         os?: string | null,
>         state?: string | null,
>         zip?: string | null
>       } | {
>         city?: string | null,
>         country?: string | null,
>         state?: string | null
>       } | {
>         ca_bundle?: string | null,
>         host?: string | null,
>         password?: string | null,
>         port?: number | null,
>         username?: string | null
>       } | null,
>       name?: string | null,
>       protocol?: string | null,
>       type?: string | null
>     } | null,
>     mode?: string | null
>   } | null,
>   type?: string | null
> }[] | null
> ```

***

## Credential Providers

### create

`credentialProviders.create`

Connect an external credential provider (such as 1Password) so managed auth can read logins from it.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.credentialProviders.create({ provider_type: 'onepassword', name: 'my-name', token: 'example' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `cache_ttl_seconds` | `number` | No | How long to cache credential lists (default 300 seconds) |
| `name` | `string` | Yes | Human-readable name for this provider instance (unique per org). Surrounding whitespace is trimmed and the trimmed value must be non-empty. |
| `provider_type` | `onepassword` | Yes | Type of credential provider |
| `token` | `string` | Yes | Service account token for the provider (e.g., 1Password service account token) |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `created_at` | `string \| null` | No | When the credential provider was created |
| `enabled` | `boolean \| null` | No | Whether the provider is enabled for credential lookups |
| `id` | `string \| null` | No | Unique identifier for the credential provider |
| `name` | `string \| null` | No | Human-readable name for this provider instance |
| `priority` | `number \| null` | No | Priority order for credential lookups (lower numbers are checked first) |
| `provider_type` | `string \| null` | No | Type of credential provider |
| `updated_at` | `string \| null` | No | When the credential provider was last updated |

***

### delete

`credentialProviders.delete`

Disconnect and delete a credential provider. Cannot be undone.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.kernel.api.credentialProviders.delete({ id: 'credentialProvider_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Credential provider ID |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### get

`credentialProviders.get`

Get a credential provider.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.credentialProviders.get({ id: 'credentialProvider_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Credential provider ID |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `created_at` | `string \| null` | No | When the credential provider was created |
| `enabled` | `boolean \| null` | No | Whether the provider is enabled for credential lookups |
| `id` | `string \| null` | No | Unique identifier for the credential provider |
| `name` | `string \| null` | No | Human-readable name for this provider instance |
| `priority` | `number \| null` | No | Priority order for credential lookups (lower numbers are checked first) |
| `provider_type` | `string \| null` | No | Type of credential provider |
| `updated_at` | `string \| null` | No | When the credential provider was last updated |

***

### list

`credentialProviders.list`

List connected credential providers (such as 1Password).

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.credentialProviders.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `limit` | `number` | No | Limit the number of credential providers to return. |
| `offset` | `number` | No | Offset the number of credential providers to return. |
| `query` | `string` | No | Case-insensitive substring match against credential provider name. IDs match by exact value. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | This page of results. |
| `has_more` | `boolean` | Yes | True when more results follow; pass next\_offset as offset to read them. |
| `next_offset` | `number \| null` | Yes | Value for `offset` that reads the next page, or null on the last page. |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   created_at?: string | null,
>   enabled?: boolean | null,
>   id?: string | null,
>   name?: string | null,
>   priority?: number | null,
>   provider_type?: string | null,
>   updated_at?: string | null
> }[]
> ```

***

### listItems

`credentialProviders.listItems`

List the logins a credential provider makes available (no secret values).

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.credentialProviders.listItems({ id: 'credentialProvider_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Credential provider ID |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[] \| null` | No | — |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   path?: string | null,
>   title?: string | null,
>   urls?: string[] | null,
>   vault_id?: string | null,
>   vault_name?: string | null
> }[] | null
> ```

***

### test

`credentialProviders.test`

Check that a credential provider's connection works.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.credentialProviders.test({ id: 'credentialProvider_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Credential provider ID |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `error` | `string \| null` | No | Error message if the test failed |
| `success` | `boolean \| null` | No | Whether the connection test was successful |
| `vaults` | `object[] \| null` | No | List of vaults accessible by the service account |

> [accordion] vaults full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   name?: string | null
> }[] | null
> ```

***

### update

`credentialProviders.update`

Change a credential provider's settings or token.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.credentialProviders.update({ id: 'credentialProvider_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Credential provider ID |
| `cache_ttl_seconds` | `number` | No | How long to cache credential lists |
| `enabled` | `boolean` | No | Whether the provider is enabled for credential lookups |
| `name` | `string` | No | Human-readable name for this provider instance. Surrounding whitespace is trimmed and the trimmed value must be non-empty. |
| `priority` | `number` | No | Priority order for credential lookups (lower numbers are checked first) |
| `token` | `string` | No | New service account token (to rotate credentials) |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `created_at` | `string \| null` | No | When the credential provider was created |
| `enabled` | `boolean \| null` | No | Whether the provider is enabled for credential lookups |
| `id` | `string \| null` | No | Unique identifier for the credential provider |
| `name` | `string \| null` | No | Human-readable name for this provider instance |
| `priority` | `number \| null` | No | Priority order for credential lookups (lower numbers are checked first) |
| `provider_type` | `string \| null` | No | Type of credential provider |
| `updated_at` | `string \| null` | No | When the credential provider was last updated |

***

## Credentials

### create

`credentials.create`

Store login values (username, password, TOTP secret) for a domain so managed auth can sign in by itself. Values are write-only.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.credentials.create({
	name: 'acme-login',
	domain: 'app.acme.com',
	values: { username: 'agent@acme.com', password: '••••••••' },
});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `domain` | `string` | Yes | Target domain this credential is for |
| `name` | `string` | Yes | Unique name for the credential within the project |
| `sso_provider` | `string` | No | If set, indicates this credential should be used with the specified SSO provider (e.g., google, github, microsoft). When the target site has a matching SSO button, it will be clicked first before filling credential values on the identity provider's login page. |
| `totp_algorithm` | `SHA1 \| SHA256 \| SHA512` | No | HMAC algorithm used to generate TOTP codes. Defaults to SHA1 and is ignored when an `otpauth://` URI supplies the algorithm. |
| `totp_digits` | `number` | No | Number of digits in generated TOTP codes. Defaults to 6 and is ignored when an `otpauth://` URI supplies the digit count. |
| `totp_period` | `number` | No | TOTP rotation period in seconds. Defaults to 30 and is ignored when an `otpauth://` URI supplies the period. |
| `totp_secret` | `string` | No | Accepts a 16-128 character base32-encoded TOTP secret or an `otpauth://totp/...` URI. The range accepts existing shorter seeds and longer seeds regardless of HMAC algorithm; RFC 6238 recommends unpadded base32 lengths of 32/52/103 for SHA1/SHA256/SHA512. Only URI parameters present override the corresponding explicit TOTP fields. Used for automatic 2FA during login. |
| `values` | `Record<string, string>` | Yes | Field name to value mapping (e.g., username, password) |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `created_at` | `string \| null` | No | When the credential was created |
| `domain` | `string \| null` | No | Target domain this credential is for |
| `has_totp_secret` | `boolean \| null` | No | Whether this credential has a TOTP secret configured for automatic 2FA |
| `has_values` | `boolean \| null` | No | Whether this credential has stored values (email, password, etc.) |
| `id` | `string \| null` | No | Unique identifier for the credential |
| `name` | `string \| null` | No | Unique name for the credential within the project |
| `sso_provider` | `string \| null \| null` | No | If set, indicates this credential should be used with the specified SSO provider (e.g., google, github, microsoft). When the target site has a matching SSO button, it will be clicked first before filling credential values on the identity provider's login page. |
| `totp_algorithm` | `string \| null` | No | HMAC algorithm used to generate TOTP codes. Defaults to SHA1 for credentials created before this metadata was stored. |
| `totp_code` | `string \| null` | No | Current TOTP code. Only included in create/update responses when totp\_secret was just set. |
| `totp_code_expires_at` | `string \| null` | No | When the totp\_code expires. Only included when totp\_code is present. |
| `totp_digits` | `number \| null` | No | Number of digits in generated TOTP codes. Defaults to 6 for credentials created before this metadata was stored. |
| `totp_period` | `number \| null` | No | TOTP rotation period in seconds. Defaults to 30 for credentials created before this metadata was stored. |
| `updated_at` | `string \| null` | No | When the credential was last updated |
| `value_keys` | `string[] \| null` | No | The field names stored in this credential's values (e.g., username, password). Values themselves are never returned. Included on single-credential responses (create, get by id or name, update); omitted from list responses. |

***

### delete

`credentials.delete`

Delete a stored credential. Cannot be undone.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.kernel.api.credentials.delete({ id_or_name: 'acme-login' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Credential ID or name |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### get

`credentials.get`

Get a stored credential's metadata (values are never returned).

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.credentials.get({ id_or_name: 'acme-login' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Credential ID or name |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `created_at` | `string \| null` | No | When the credential was created |
| `domain` | `string \| null` | No | Target domain this credential is for |
| `has_totp_secret` | `boolean \| null` | No | Whether this credential has a TOTP secret configured for automatic 2FA |
| `has_values` | `boolean \| null` | No | Whether this credential has stored values (email, password, etc.) |
| `id` | `string \| null` | No | Unique identifier for the credential |
| `name` | `string \| null` | No | Unique name for the credential within the project |
| `sso_provider` | `string \| null \| null` | No | If set, indicates this credential should be used with the specified SSO provider (e.g., google, github, microsoft). When the target site has a matching SSO button, it will be clicked first before filling credential values on the identity provider's login page. |
| `totp_algorithm` | `string \| null` | No | HMAC algorithm used to generate TOTP codes. Defaults to SHA1 for credentials created before this metadata was stored. |
| `totp_code` | `string \| null` | No | Current TOTP code. Only included in create/update responses when totp\_secret was just set. |
| `totp_code_expires_at` | `string \| null` | No | When the totp\_code expires. Only included when totp\_code is present. |
| `totp_digits` | `number \| null` | No | Number of digits in generated TOTP codes. Defaults to 6 for credentials created before this metadata was stored. |
| `totp_period` | `number \| null` | No | TOTP rotation period in seconds. Defaults to 30 for credentials created before this metadata was stored. |
| `updated_at` | `string \| null` | No | When the credential was last updated |
| `value_keys` | `string[] \| null` | No | The field names stored in this credential's values (e.g., username, password). Values themselves are never returned. Included on single-credential responses (create, get by id or name, update); omitted from list responses. |

***

### list

`credentials.list`

List stored credentials (names and domains; values are never returned).

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.credentials.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `domain` | `string` | No | Filter by domain |
| `limit` | `number` | No | Maximum number of results to return |
| `offset` | `number` | No | Number of results to skip |
| `query` | `string` | No | Case-insensitive substring match against credential name or domain. IDs match by exact value. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | This page of results. |
| `has_more` | `boolean` | Yes | True when more results follow; pass next\_offset as offset to read them. |
| `next_offset` | `number \| null` | Yes | Value for `offset` that reads the next page, or null on the last page. |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   created_at?: string | null,
>   domain?: string | null,
>   has_totp_secret?: boolean | null,
>   has_values?: boolean | null,
>   id?: string | null,
>   name?: string | null,
>   sso_provider?: string | null | null,
>   totp_algorithm?: string | null,
>   totp_code?: string | null,
>   totp_code_expires_at?: string | null,
>   totp_digits?: number | null,
>   totp_period?: number | null,
>   updated_at?: string | null,
>   value_keys?: string[] | null
> }[]
> ```

***

### totpCode

`credentials.totpCode`

Get the current one-time code for a credential that has a TOTP secret, and when it expires.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.credentials.totpCode({ id_or_name: 'acme-login' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Credential ID or name |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `code` | `string \| null` | No | Current 6-digit TOTP code |
| `expires_at` | `string \| null` | No | When this code expires (ISO 8601 timestamp) |

***

### update

`credentials.update`

Change a stored credential's values or settings.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.credentials.update({ id_or_name: 'acme-login' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Credential ID or name |
| `name` | `string` | No | New name for the credential |
| `remove_value_keys` | `string[]` | No | Field names to remove from the credential's stored values. Removals are applied before `values` are merged, so a key present in both is kept with its new value. |
| `sso_provider` | `string \| null` | No | If set, indicates this credential should be used with the specified SSO provider. Set to empty string or null to remove. |
| `totp_algorithm` | `SHA1 \| SHA256 \| SHA512` | No | HMAC algorithm used to generate TOTP codes. Requires totp\_secret and is ignored when an `otpauth://` URI supplies the algorithm. |
| `totp_digits` | `number` | No | Number of digits in generated TOTP codes. Requires totp\_secret and is ignored when an `otpauth://` URI supplies the digit count. |
| `totp_period` | `number` | No | TOTP rotation period in seconds. Requires totp\_secret and is ignored when an `otpauth://` URI supplies the period. |
| `totp_secret` | `string` | No | Accepts a 16-128 character base32-encoded TOTP secret or an `otpauth://totp/...` URI. Only URI parameters present override the corresponding explicit TOTP fields. When rotating a raw secret, omitted fields preserve their existing values; a new URI defaults unspecified fields to SHA1/6/30. Set to empty string to remove the secret and its metadata. |
| `values` | `Record<string, string>` | No | Field name to value mapping. Values are merged with existing values (new keys added, existing keys overwritten). |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `created_at` | `string \| null` | No | When the credential was created |
| `domain` | `string \| null` | No | Target domain this credential is for |
| `has_totp_secret` | `boolean \| null` | No | Whether this credential has a TOTP secret configured for automatic 2FA |
| `has_values` | `boolean \| null` | No | Whether this credential has stored values (email, password, etc.) |
| `id` | `string \| null` | No | Unique identifier for the credential |
| `name` | `string \| null` | No | Unique name for the credential within the project |
| `sso_provider` | `string \| null \| null` | No | If set, indicates this credential should be used with the specified SSO provider (e.g., google, github, microsoft). When the target site has a matching SSO button, it will be clicked first before filling credential values on the identity provider's login page. |
| `totp_algorithm` | `string \| null` | No | HMAC algorithm used to generate TOTP codes. Defaults to SHA1 for credentials created before this metadata was stored. |
| `totp_code` | `string \| null` | No | Current TOTP code. Only included in create/update responses when totp\_secret was just set. |
| `totp_code_expires_at` | `string \| null` | No | When the totp\_code expires. Only included when totp\_code is present. |
| `totp_digits` | `number \| null` | No | Number of digits in generated TOTP codes. Defaults to 6 for credentials created before this metadata was stored. |
| `totp_period` | `number \| null` | No | TOTP rotation period in seconds. Defaults to 30 for credentials created before this metadata was stored. |
| `updated_at` | `string \| null` | No | When the credential was last updated |
| `value_keys` | `string[] \| null` | No | The field names stored in this credential's values (e.g., username, password). Values themselves are never returned. Included on single-credential responses (create, get by id or name, update); omitted from list responses. |

***

## Deployments

### create

`deployments.create`

Deploy a Kernel app from a zip (URL or base64) with its entrypoint, or from a source repository.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.deployments.create({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `entrypoint_rel_path` | `string` | No | Relative path to the entrypoint of the application |
| `env_vars` | `Record<string, string>` | No | Map of environment variables to set for the deployed application. Each key-value pair represents an environment variable. |
| `file` | `string \| object \| custom` | No | ZIP file containing the application source directory |
| `force` | `boolean` | No | Allow overwriting an existing app version |
| `region` | `aws.us-east-1a` | No | Region for deployment. Currently we only support "aws.us-east-1a" |
| `source` | `object` | No | — |
| `version` | `string` | No | Version of the application. Can be any string. |

> [accordion] file full type
>
> ```ts theme={null}
> string | {
>   url: string,
>   filename?: string,
>   contentType?: string
> } | {
>   base64: string,
>   filename?: string,
>   contentType?: string
> } | custom
> ```

> [accordion] source full type
>
> ```ts theme={null}
> {
>   auth?: {
>     method: github_token,
>     token: string
>   },
>   entrypoint: string,
>   path?: string,
>   ref: string,
>   type: github,
>   url: string
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `created_at` | `string \| null` | No | Timestamp when the deployment was created |
| `entrypoint_rel_path` | `string \| null` | No | Relative path to the application entrypoint |
| `env_vars` | `Record<string, string> \| null` | No | Environment variables configured for this deployment. Values are redacted for API key, OAuth, and managed-auth callers, which receive every key with an empty string value. Only dashboard sessions receive the actual values. |
| `id` | `string \| null` | No | Unique identifier for the deployment |
| `region` | `string \| null` | No | Deployment region code |
| `source_checksum` | `string \| null` | No | Hex-encoded SHA-256 checksum of the source archive. For file uploads, this hashes the uploaded archive; for GitHub-sourced deployments, this hashes the GitHub archive downloaded by the API. Omitted for deployments created before this field was recorded. |
| `source_path` | `string \| null` | No | For GitHub-sourced deployments, the subpath within the repository that was used as the deploy root. Omitted when the repo root was used or for file uploads. |
| `source_ref` | `string \| null` | No | For GitHub-sourced deployments, the git ref as requested at deploy time (branch, tag, or commit SHA — not resolved to a commit). Omitted for file uploads. |
| `source_type` | `string \| null` | No | Origin of the deployed source code. This is read-only response provenance; `file` indicates an uploaded archive and `github` indicates a repository fetched by the API. |
| `source_url` | `string \| null` | No | For GitHub-sourced deployments, the repository URL that was fetched. Omitted for file uploads. |
| `status` | `string \| null` | No | Current status of the deployment |
| `status_reason` | `string \| null` | No | Status reason |
| `updated_at` | `string \| null \| null` | No | Timestamp when the deployment was last updated |

***

### delete

`deployments.delete`

Delete an app deployment. Cannot be undone.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.kernel.api.deployments.delete({ id: 'deployment_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Deployment ID |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### get

`deployments.get`

Get a deployment and its status. Poll this instead of the event stream.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.deployments.get({ id: 'deployment_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Deployment ID |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `created_at` | `string \| null` | No | Timestamp when the deployment was created |
| `entrypoint_rel_path` | `string \| null` | No | Relative path to the application entrypoint |
| `env_vars` | `Record<string, string> \| null` | No | Environment variables configured for this deployment. Values are redacted for API key, OAuth, and managed-auth callers, which receive every key with an empty string value. Only dashboard sessions receive the actual values. |
| `id` | `string \| null` | No | Unique identifier for the deployment |
| `region` | `string \| null` | No | Deployment region code |
| `source_checksum` | `string \| null` | No | Hex-encoded SHA-256 checksum of the source archive. For file uploads, this hashes the uploaded archive; for GitHub-sourced deployments, this hashes the GitHub archive downloaded by the API. Omitted for deployments created before this field was recorded. |
| `source_path` | `string \| null` | No | For GitHub-sourced deployments, the subpath within the repository that was used as the deploy root. Omitted when the repo root was used or for file uploads. |
| `source_ref` | `string \| null` | No | For GitHub-sourced deployments, the git ref as requested at deploy time (branch, tag, or commit SHA — not resolved to a commit). Omitted for file uploads. |
| `source_type` | `string \| null` | No | Origin of the deployed source code. This is read-only response provenance; `file` indicates an uploaded archive and `github` indicates a repository fetched by the API. |
| `source_url` | `string \| null` | No | For GitHub-sourced deployments, the repository URL that was fetched. Omitted for file uploads. |
| `status` | `string \| null` | No | Current status of the deployment |
| `status_reason` | `string \| null` | No | Status reason |
| `updated_at` | `string \| null \| null` | No | Timestamp when the deployment was last updated |

***

### list

`deployments.list`

List app deployments.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.deployments.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `app_name` | `string` | No | Filter results by application name. |
| `app_version` | `string` | No | Filter results by application version. Requires app\_name to be set. |
| `limit` | `number` | No | Limit the number of deployments to return. |
| `offset` | `number` | No | Offset the number of deployments to return. |
| `query` | `string` | No | Search deployments by ID or app name. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | This page of results. |
| `has_more` | `boolean` | Yes | True when more results follow; pass next\_offset as offset to read them. |
| `next_offset` | `number \| null` | Yes | Value for `offset` that reads the next page, or null on the last page. |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   created_at?: string | null,
>   entrypoint_rel_path?: string | null,
>   env_vars?: Record<string, string> | null,
>   id?: string | null,
>   region?: string | null,
>   source_checksum?: string | null,
>   source_path?: string | null,
>   source_ref?: string | null,
>   source_type?: string | null,
>   source_url?: string | null,
>   status?: string | null,
>   status_reason?: string | null,
>   updated_at?: string | null | null
> }[]
> ```

***

## Extensions

### delete

`extensions.delete`

Delete an uploaded extension. Cannot be undone.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.kernel.api.extensions.delete({ id_or_name: 'my-extension' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Extension ID or extension name |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### download

`extensions.download`

Download an uploaded extension's zip. Returns a file.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.extensions.download({ id_or_name: 'my-extension' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Extension ID or name |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `contentBase64` | `string` | No | The file, base64-encoded. Missing when the file came back as text or contentOmitted is set. |
| `text` | `string` | No | The file as text, in place of contentBase64, when it is a text file (CSV, JSON, Markdown, XML and the like) in UTF-8. |
| `contentType` | `string` | Yes | Media type of the file, for example application/pdf. |
| `byteLength` | `number` | Yes | Size of the file in bytes. |
| `filename` | `string` | No | The file name, when known. |
| `contentOmitted` | `not_requested \| over_limit` | No | Set when the content was left out: the caller did not ask for it, or the file was over the limit. |
| `fileId` | `string` | No | Where the host saved the file. Over the limit it comes in place of the content; a host that keeps every file sets it beside the content too. On Corsair it is a Files id (fil\_…): pass it to another app wherever that app takes a file URL, or read a text file or PDF with files.read\_text. |

***

### downloadFromChromeStore

`extensions.downloadFromChromeStore`

Download an extension from the Chrome Web Store as an unpacked zip, ready for extensions.upload. Returns a file.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.extensions.downloadFromChromeStore({ url: 'https://chromewebstore.google.com/detail/ublock-origin-lite/ddkjiahejlhfcafbddmgiahcphecmpfh' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `url` | `string` | Yes | Chrome Web Store URL for the extension. |
| `os` | `win \| mac \| linux` | No | Target operating system for the extension package. Defaults to linux. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `contentBase64` | `string` | No | The file, base64-encoded. Missing when the file came back as text or contentOmitted is set. |
| `text` | `string` | No | The file as text, in place of contentBase64, when it is a text file (CSV, JSON, Markdown, XML and the like) in UTF-8. |
| `contentType` | `string` | Yes | Media type of the file, for example application/pdf. |
| `byteLength` | `number` | Yes | Size of the file in bytes. |
| `filename` | `string` | No | The file name, when known. |
| `contentOmitted` | `not_requested \| over_limit` | No | Set when the content was left out: the caller did not ask for it, or the file was over the limit. |
| `fileId` | `string` | No | Where the host saved the file. Over the limit it comes in place of the content; a host that keeps every file sets it beside the content too. On Corsair it is a Files id (fil\_…): pass it to another app wherever that app takes a file URL, or read a text file or PDF with files.read\_text. |

***

### get

`extensions.get`

Get an uploaded extension's metadata.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.extensions.get({ id_or_name: 'my-extension' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Extension ID or name |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `checksum` | `string \| null \| null` | No | SHA-256 checksum, encoded as lowercase hexadecimal, of the exact uploaded extension archive bytes. This is not a normalized checksum of the extension contents; archive metadata, file ordering, and compression can change the checksum for otherwise identical contents. Omitted for legacy rows and server-repackaged Chrome Web Store extensions. |
| `created_at` | `string \| null` | No | Timestamp when the extension was created |
| `id` | `string \| null` | No | Unique identifier for the extension |
| `last_used_at` | `string \| null \| null` | No | Timestamp when the extension was last used |
| `name` | `string \| null \| null` | No | Optional, easier-to-reference name for the extension. Must be unique within the project. |
| `size_bytes` | `number \| null` | No | Size of the extension archive in bytes |

***

### list

`extensions.list`

List uploaded Chrome extensions.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.extensions.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `limit` | `number` | No | Limit the number of extensions to return. |
| `offset` | `number` | No | Offset the number of extensions to return. |
| `query` | `string` | No | Case-insensitive substring match against extension name. IDs match by exact value. |
| `name` | `string` | No | Exact-match filter on extension name using the database collation. In production, matching is case- and accent-insensitive. During the default-project migration, unscoped requests prefer a concrete default-project extension over a legacy unscoped extension with the same name. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | This page of results. |
| `has_more` | `boolean` | Yes | True when more results follow; pass next\_offset as offset to read them. |
| `next_offset` | `number \| null` | Yes | Value for `offset` that reads the next page, or null on the last page. |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   checksum?: string | null | null,
>   created_at?: string | null,
>   id?: string | null,
>   last_used_at?: string | null | null,
>   name?: string | null | null,
>   size_bytes?: number | null
> }[]
> ```

***

### upload

`extensions.upload`

Upload a Chrome extension (a zip of the unpacked extension, as a URL or base64) to use in browsers by name.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.extensions.upload({ file: 'https://example.com/archive.zip' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `file` | `string \| object \| custom` | Yes | ZIP file containing the browser extension. |
| `name` | `string` | No | Optional unique name within the project to reference this extension. |

> [accordion] file full type
>
> ```ts theme={null}
> string | {
>   url: string,
>   filename?: string,
>   contentType?: string
> } | {
>   base64: string,
>   filename?: string,
>   contentType?: string
> } | custom
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `checksum` | `string \| null \| null` | No | SHA-256 checksum, encoded as lowercase hexadecimal, of the exact uploaded extension archive bytes. This is not a normalized checksum of the extension contents; archive metadata, file ordering, and compression can change the checksum for otherwise identical contents. Omitted for legacy rows and server-repackaged Chrome Web Store extensions. |
| `created_at` | `string \| null` | No | Timestamp when the extension was created |
| `id` | `string \| null` | No | Unique identifier for the extension |
| `last_used_at` | `string \| null \| null` | No | Timestamp when the extension was last used |
| `name` | `string \| null \| null` | No | Optional, easier-to-reference name for the extension. Must be unique within the project. |
| `size_bytes` | `number \| null` | No | Size of the extension archive in bytes |

***

## Invocations

### create

`invocations.create`

Run an action of a deployed Kernel app (billed per second). async: true returns at once; poll invocations.get for the result.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.kernel.api.invocations.create({ app_name: 'my-app', version: '1', action_name: 'run' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `action_name` | `string` | Yes | Name of the action to invoke |
| `app_name` | `string` | Yes | Name of the application |
| `async` | `boolean` | No | If true, invoke asynchronously. When set, the API responds 202 Accepted with status "queued". |
| `async_timeout_seconds` | `number` | No | Timeout in seconds for async invocations (min 10, max 3600). Only applies when async is true. |
| `payload` | `string` | No | Input data for the action, sent as a JSON string. |
| `version` | `string` | Yes | Version of the application |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `action_name` | `string \| null` | No | Name of the action invoked |
| `id` | `string \| null` | No | ID of the invocation |
| `output` | `string \| null` | No | The action result or detailed failure output. Often a JSON-encoded value, but failures may contain plain text. May contain sensitive application data. |
| `status` | `string \| null` | No | Status of the invocation |
| `status_reason` | `string \| null` | No | A nonempty, customer-safe summary of the recorded failure output, always present when status is failed and omitted otherwise. Recognized messages receive a specific summary; other failures receive a generic summary. Message matching does not establish whether the failure originated in the platform or action code. Does not include raw action output or internal error details. Human-readable text, not a stable identifier for retry logic. |

***

### deleteBrowsers

`invocations.deleteBrowsers`

Delete every browser an invocation started. Cannot be undone.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.kernel.api.invocations.deleteBrowsers({ id: 'invocation_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Invocation ID |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### get

`invocations.get`

Get an invocation: status, output and timing. Poll this instead of the event stream.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.invocations.get({ id: 'invocation_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | The invocation ID |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `action_name` | `string \| null` | No | Name of the action invoked |
| `app_name` | `string \| null` | No | Name of the application |
| `finished_at` | `string \| null \| null` | No | RFC 3339 Nanoseconds timestamp when the invocation finished (null if still running) |
| `id` | `string \| null` | No | ID of the invocation |
| `output` | `string \| null` | No | The action result or detailed failure output. Often a JSON-encoded value, but failures may contain plain text. May contain sensitive application data. |
| `payload` | `string \| null` | No | Payload provided to the invocation. This is a string that can be parsed as JSON. |
| `started_at` | `string \| null` | No | RFC 3339 Nanoseconds timestamp when the invocation started |
| `status` | `string \| null` | No | Status of the invocation |
| `status_reason` | `string \| null` | No | A nonempty, customer-safe summary of the recorded failure output, always present when status is failed and omitted otherwise, including in the first failed invocation\_state event. Recognized messages receive a specific summary; other failures receive a generic summary. Message matching does not establish whether the failure originated in the platform or action code. Does not include raw action output or internal error details. Available for historical invocations as well. Human-readable text, not a stable identifier for retry logic. |
| `version` | `string \| null` | No | Version label for the application |

***

### list

`invocations.list`

List app action invocations, filtered by app, action, status or time.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.invocations.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `app_name` | `string` | No | Filter results by application name. |
| `version` | `string` | No | Filter results by application version. |
| `action_name` | `string` | No | Filter results by action name. |
| `deployment_id` | `string` | No | Filter results by deployment ID. |
| `status` | `queued \| running \| succeeded \| failed` | No | Filter results by invocation status. |
| `since` | `string` | No | Show invocations that have started since the given time (RFC timestamps or durations like 5m). |
| `limit` | `number` | No | Limit the number of invocations to return. |
| `offset` | `number` | No | Offset the number of invocations to return. |
| `query` | `string` | No | Search invocations by ID, app name, or action name. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | This page of results. |
| `has_more` | `boolean` | Yes | True when more results follow; pass next\_offset as offset to read them. |
| `next_offset` | `number \| null` | Yes | Value for `offset` that reads the next page, or null on the last page. |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   action_name?: string | null,
>   app_name?: string | null,
>   finished_at?: string | null | null,
>   id?: string | null,
>   output?: string | null,
>   payload?: string | null,
>   started_at?: string | null,
>   status?: string | null,
>   status_reason?: string | null,
>   version?: string | null
> }[]
> ```

***

### listBrowsers

`invocations.listBrowsers`

List the browsers an invocation started.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.invocations.listBrowsers({ id: 'invocation_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Invocation ID |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `browsers` | `object[] \| null` | No | — |

> [accordion] browsers full type
>
> ```ts theme={null}
> {
>   base_url?: string | null,
>   browser_live_view_url?: string | null,
>   captcha_solver?: {
>     enabled?: boolean | null
>   } | null,
>   cdp_ws_url?: string | null,
>   chrome_policy?: {
>   } | null,
>   cost?: {
>     as_of?: string | null,
>     estimated_usage_spend_usd?: string | null,
>     status?: string | null
>   } | null,
>   created_at?: string | null,
>   deleted_at?: string | null,
>   fingerprint?: {
>     os?: string | null
>   } | null,
>   gpu?: boolean | null,
>   headless?: boolean | null,
>   kiosk_mode?: boolean | null,
>   leased_at?: string | null,
>   location?: {
>     locale?: string | null,
>     locale_source?: string | null,
>     timezone?: string | null,
>     timezone_source?: string | null
>   } | null,
>   memory?: string | null,
>   name?: string | null,
>   network?: {
>     allowed_hosts?: string[] | null,
>     allowlist_state?: {
>       base_revision?: string | null,
>       mutation_id?: string | null,
>       revision?: string | null
>     } | null,
>     private_hosts?: string[] | null,
>     proxy_routes?: {
>       hosts?: string[] | null,
>       proxy?: {
>         id?: string | null,
>         name?: string | null
>       } | null
>     }[] | null
>   } | null,
>   pool?: {
>     id?: string | null,
>     name?: string | null
>   } | null,
>   profile?: {
>     created_at?: string | null,
>     id?: string | null,
>     last_used_at?: string | null,
>     name?: string | null | null,
>     updated_at?: string | null
>   } | null,
>   profile_save_changes?: boolean | null,
>   proxy?: {
>     id?: string | null,
>     mode?: string | null,
>     name?: string | null
>   } | null,
>   proxy_id?: string | null,
>   region?: string | null,
>   replay?: {
>     finished_at?: string | null | null,
>     replay_id?: string | null,
>     replay_view_url?: string | null,
>     started_at?: string | null | null
>   } | null,
>   session_id?: string | null,
>   start_url?: string | null,
>   stealth?: boolean | null,
>   tags?: Record<string, string> | null,
>   telemetry?: {
>     browser?: {
>       captcha?: {
>         enabled?: boolean | null
>       } | null,
>       connection?: {
>         enabled?: boolean | null
>       } | null,
>       console?: {
>         enabled?: boolean | null
>       } | null,
>       control?: {
>         cdp?: {
>           excluded_methods?: string[] | null
>         } | null,
>         enabled?: boolean | null
>       } | null,
>       interaction?: {
>         enabled?: boolean | null
>       } | null,
>       network?: {
>         enabled?: boolean | null
>       } | null,
>       page?: {
>         enabled?: boolean | null
>       } | null,
>       platform?: {
>         enabled?: boolean | null
>       } | null,
>       screenshot?: {
>         enabled?: boolean | null
>       } | null,
>       system?: {
>         enabled?: boolean | null
>       } | null
>     } | null,
>     export?: {
>       otlp?: {
>         destination?: string | null,
>         enabled?: boolean | null
>       } | null
>     } | null,
>     storage?: {
>       enabled?: boolean | null
>     } | null
>   } | null | null,
>   timeout_seconds?: number | null,
>   usage?: {
>     uptime_ms?: number | null
>   } | null,
>   usage_status?: string | null,
>   vaults?: {
>     id?: string | null,
>     name?: string | null
>   }[] | null,
>   video_memory?: string | null,
>   viewport?: {
>     height?: number | null,
>     refresh_rate?: number | null,
>     width?: number | null
>   } | null,
>   webdriver_ws_url?: string | null
> }[] | null
> ```

***

### update

`invocations.update`

Change an invocation's status, for example mark it succeeded or failed with output.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.invocations.update({ id: 'invocation_123', status: 'succeeded' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Invocation ID |
| `output` | `string` | No | Updated output of the invocation rendered as JSON string. |
| `status` | `succeeded \| failed` | Yes | New status for the invocation. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `action_name` | `string \| null` | No | Name of the action invoked |
| `app_name` | `string \| null` | No | Name of the application |
| `finished_at` | `string \| null \| null` | No | RFC 3339 Nanoseconds timestamp when the invocation finished (null if still running) |
| `id` | `string \| null` | No | ID of the invocation |
| `output` | `string \| null` | No | The action result or detailed failure output. Often a JSON-encoded value, but failures may contain plain text. May contain sensitive application data. |
| `payload` | `string \| null` | No | Payload provided to the invocation. This is a string that can be parsed as JSON. |
| `started_at` | `string \| null` | No | RFC 3339 Nanoseconds timestamp when the invocation started |
| `status` | `string \| null` | No | Status of the invocation |
| `status_reason` | `string \| null` | No | A nonempty, customer-safe summary of the recorded failure output, always present when status is failed and omitted otherwise, including in the first failed invocation\_state event. Recognized messages receive a specific summary; other failures receive a generic summary. Message matching does not establish whether the failure originated in the platform or action code. Does not include raw action output or internal error details. Available for historical invocations as well. Human-readable text, not a stable identifier for retry logic. |
| `version` | `string \| null` | No | Version label for the application |

***

## Organization

### entitlements.get

`organization.entitlements.get`

Get what the org's plan includes (features and quotas).

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.organization.entitlements.get({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `features` | `object \| null` | No | — |
| `limits` | `object \| null` | No | — |
| `plan` | `object \| null` | No | — |

> [accordion] features full type
>
> ```ts theme={null}
> {
>   browser_extensions?: {
>     enabled?: boolean | null,
>     max_stored_per_org?: number | null | null
>   } | null,
>   browser_pools?: {
>     enabled?: boolean | null
>   } | null,
>   browser_replays?: {
>     enabled?: boolean | null,
>     retention_days?: number | null
>   } | null,
>   credential_providers?: {
>     enabled?: boolean | null
>   } | null,
>   credentials?: {
>     enabled?: boolean | null
>   } | null,
>   custom_proxies?: {
>     enabled?: boolean | null
>   } | null,
>   file_io?: {
>     enabled?: boolean | null
>   } | null,
>   gpu?: {
>     enabled?: boolean | null
>   } | null,
>   managed_auth?: {
>     enabled?: boolean | null,
>     health_check_interval_default_seconds?: number | null,
>     health_check_interval_max_seconds?: number | null,
>     health_check_interval_min_seconds?: number | null,
>     max_connections?: number | null | null
>   } | null,
>   managed_proxies?: {
>     enabled?: boolean | null
>   } | null,
>   profiles?: {
>     enabled?: boolean | null
>   } | null,
>   proxy_bypass_hosts?: {
>     enabled?: boolean | null
>   } | null,
>   search?: {
>     enabled?: boolean | null
>   } | null,
>   vaults?: {
>     enabled?: boolean | null
>   } | null
> } | null
> ```

> [accordion] limits full type
>
> ```ts theme={null}
> {
>   default_max_concurrent_invocations_per_app?: number | null,
>   max_concurrent_browsers?: number | null,
>   max_concurrent_invocations?: number | null,
>   max_vaults?: number | null | null
> } | null
> ```

> [accordion] plan full type
>
> ```ts theme={null}
> {
>   effective_id?: string | null,
>   id?: string | null,
>   is_trialing?: boolean | null,
>   status?: string | null | null,
>   trial_ends_at?: string | null | null
> } | null
> ```

***

### limits.get

`organization.limits.get`

Get the org's limits and current use: concurrent browsers, managed auth connections, vaults.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.organization.limits.get({});
```

**Input:** *empty object*

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `auth_connections_used` | `number \| null` | No | The organization's current non-deleted managed auth connections, counted org-wide across every project. Compare against max\_auth\_connections to show remaining capacity before a create is rejected with 403 insufficient\_plan. |
| `concurrent_sessions_available` | `number \| null \| null` | No | Number of concurrent browser slots currently available to the organization. This is the effective concurrency limit minus active on-demand sessions and browser pool reservations, floored at zero. Null when usage cannot be read. |
| `concurrent_sessions_used` | `number \| null \| null` | No | Current organization-wide concurrent browser usage, including active on-demand sessions and browser pool reservations. Null when usage cannot be read. |
| `default_project_max_concurrent_sessions` | `number \| null \| null` | No | Default maximum concurrent browsers applied to every project that has no explicit per-project override. Null means no org-level default, so such projects are uncapped (only the org-wide limit applies). Applies to existing and newly created projects. |
| `max_auth_connections` | `number \| null \| null` | No | Maximum managed auth connections the organization's plan allows. Null means unlimited. Counted org-wide, so it cannot be multiplied across projects. |
| `max_concurrent_sessions` | `number \| null` | No | The organization's effective concurrency limit — the maximum browsers running at once, covering both on-demand sessions and browser pool reservations — from its plan or an override. Read-only and shared across all projects in the org; a per-project default cannot exceed it. |
| `max_vaults` | `number \| null \| null` | No | Maximum non-deleted vaults allowed org-wide across all projects. Null means unlimited. |
| `min_health_check_interval_seconds` | `number \| null` | No | Smallest health\_check\_interval the organization's plan accepts on a managed auth connection. Requests below this are rejected with 400. Existing connections stored below the floor are grandfathered until edited. |
| `vaults_used` | `number \| null` | No | Current non-deleted vault count across all projects in the organization. |

***

### limits.update

`organization.limits.update`

Set the default concurrent-browser cap for projects without their own.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.organization.limits.update({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `default_project_max_concurrent_sessions` | `number \| null` | No | Default maximum concurrent browsers for projects without an explicit override. Set to 0 to remove the default; omit to leave unchanged. Cannot exceed the organization's concurrency limit. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `auth_connections_used` | `number \| null` | No | The organization's current non-deleted managed auth connections, counted org-wide across every project. Compare against max\_auth\_connections to show remaining capacity before a create is rejected with 403 insufficient\_plan. |
| `concurrent_sessions_available` | `number \| null \| null` | No | Number of concurrent browser slots currently available to the organization. This is the effective concurrency limit minus active on-demand sessions and browser pool reservations, floored at zero. Null when usage cannot be read. |
| `concurrent_sessions_used` | `number \| null \| null` | No | Current organization-wide concurrent browser usage, including active on-demand sessions and browser pool reservations. Null when usage cannot be read. |
| `default_project_max_concurrent_sessions` | `number \| null \| null` | No | Default maximum concurrent browsers applied to every project that has no explicit per-project override. Null means no org-level default, so such projects are uncapped (only the org-wide limit applies). Applies to existing and newly created projects. |
| `max_auth_connections` | `number \| null \| null` | No | Maximum managed auth connections the organization's plan allows. Null means unlimited. Counted org-wide, so it cannot be multiplied across projects. |
| `max_concurrent_sessions` | `number \| null` | No | The organization's effective concurrency limit — the maximum browsers running at once, covering both on-demand sessions and browser pool reservations — from its plan or an override. Read-only and shared across all projects in the org; a per-project default cannot exceed it. |
| `max_vaults` | `number \| null \| null` | No | Maximum non-deleted vaults allowed org-wide across all projects. Null means unlimited. |
| `min_health_check_interval_seconds` | `number \| null` | No | Smallest health\_check\_interval the organization's plan accepts on a managed auth connection. Requests below this are rejected with 400. Existing connections stored below the floor are grandfathered until edited. |
| `vaults_used` | `number \| null` | No | Current non-deleted vault count across all projects in the organization. |

***

## Profiles

### create

`profiles.create`

Create an empty browser profile (saved cookies and storage) to start browsers signed in. Fill it by starting a browser with profile \{name, save\_changes: true}, logging in, then deleting the browser.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.profiles.create({ name: 'acme-login' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `name` | `string` | No | Optional name of the profile. Must be unique within the logical project; during the default-project migration, unscoped profiles and profiles in the org default project are treated as the same project. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `created_at` | `string \| null` | No | Timestamp when the profile was created |
| `id` | `string \| null` | No | Unique identifier for the profile |
| `last_used_at` | `string \| null` | No | Timestamp when the profile was last used |
| `name` | `string \| null \| null` | No | Optional, easier-to-reference name for the profile |
| `updated_at` | `string \| null` | No | Timestamp when the profile was last updated |

***

### delete

`profiles.delete`

Delete a browser profile and its saved cookies and storage. Cannot be undone.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.kernel.api.profiles.delete({ id_or_name: 'acme-login' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Profile ID or profile name |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### download

`profiles.download`

Download a profile's saved state as a tar.zst (or tar) archive. Returns a file. Holds session cookies: treat it as a credential.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.profiles.download({ id_or_name: 'acme-login' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Profile ID or name |
| `format` | `tar.zst \| tar` | No | Response format for current profile archives. Legacy profiles are always returned as JSON. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `contentBase64` | `string` | No | The file, base64-encoded. Missing when the file came back as text or contentOmitted is set. |
| `text` | `string` | No | The file as text, in place of contentBase64, when it is a text file (CSV, JSON, Markdown, XML and the like) in UTF-8. |
| `contentType` | `string` | Yes | Media type of the file, for example application/pdf. |
| `byteLength` | `number` | Yes | Size of the file in bytes. |
| `filename` | `string` | No | The file name, when known. |
| `contentOmitted` | `not_requested \| over_limit` | No | Set when the content was left out: the caller did not ask for it, or the file was over the limit. |
| `fileId` | `string` | No | Where the host saved the file. Over the limit it comes in place of the content; a host that keeps every file sets it beside the content too. On Corsair it is a Files id (fil\_…): pass it to another app wherever that app takes a file URL, or read a text file or PDF with files.read\_text. |

***

### get

`profiles.get`

Get a browser profile by id or name.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.profiles.get({ id_or_name: 'acme-login' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Profile ID or name |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `created_at` | `string \| null` | No | Timestamp when the profile was created |
| `id` | `string \| null` | No | Unique identifier for the profile |
| `last_used_at` | `string \| null` | No | Timestamp when the profile was last used |
| `name` | `string \| null \| null` | No | Optional, easier-to-reference name for the profile |
| `updated_at` | `string \| null` | No | Timestamp when the profile was last updated |

***

### list

`profiles.list`

List saved browser profiles (name, id, last used).

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.profiles.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `limit` | `number` | No | Limit the number of profiles to return. |
| `offset` | `number` | No | Offset the number of profiles to return. |
| `query` | `string` | No | Case-insensitive substring match against profile name or ID. |
| `name` | `string` | No | Exact-match filter on profile name using the database collation. In production, matching is case- and accent-insensitive. During the default-project migration, unscoped requests prefer a concrete default-project profile over a legacy unscoped profile with the same name. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | This page of results. |
| `has_more` | `boolean` | Yes | True when more results follow; pass next\_offset as offset to read them. |
| `next_offset` | `number \| null` | Yes | Value for `offset` that reads the next page, or null on the last page. |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   created_at?: string | null,
>   id?: string | null,
>   last_used_at?: string | null,
>   name?: string | null | null,
>   updated_at?: string | null
> }[]
> ```

***

### update

`profiles.update`

Rename a browser profile.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.profiles.update({ id_or_name: 'acme-login', name: 'my-name' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Profile ID or profile name |
| `name` | `string` | Yes | New profile name. Must be unique within the logical project; during the default-project migration, unscoped profiles and profiles in the org default project are treated as the same project. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `created_at` | `string \| null` | No | Timestamp when the profile was created |
| `id` | `string \| null` | No | Unique identifier for the profile |
| `last_used_at` | `string \| null` | No | Timestamp when the profile was last used |
| `name` | `string \| null \| null` | No | Optional, easier-to-reference name for the profile |
| `updated_at` | `string \| null` | No | Timestamp when the profile was last updated |

***

## Projects

### create

`projects.create`

Create a project to keep browsers, profiles and keys separate within the org.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.projects.create({ name: 'my-name' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `name` | `string` | Yes | Project name (1-255 Unicode code points; cannot contain `/` or `%`) |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `created_at` | `string \| null` | No | When the project was created |
| `id` | `string \| null` | No | Unique project identifier |
| `name` | `string \| null` | No | Project name |
| `status` | `string \| null` | No | Project status |
| `updated_at` | `string \| null` | No | When the project was last updated |

***

### delete

`projects.delete`

Delete a project. Cannot be undone.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.kernel.api.projects.delete({ id_or_name: 'my-project' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Project ID or name |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### get

`projects.get`

Get a project.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.projects.get({ id_or_name: 'my-project' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Project ID or name |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `created_at` | `string \| null` | No | When the project was created |
| `id` | `string \| null` | No | Unique project identifier |
| `name` | `string \| null` | No | Project name |
| `status` | `string \| null` | No | Project status |
| `updated_at` | `string \| null` | No | When the project was last updated |

***

### limits.get

`projects.limits.get`

Get a project's concurrency limit and use.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.projects.limits.get({ id_or_name: 'my-project' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Project ID or name |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `max_concurrent_invocations` | `number \| null \| null` | No | Maximum concurrent app invocations for this project. Null means no project-level cap. |
| `max_concurrent_sessions` | `number \| null \| null` | No | Maximum concurrent browsers for this project, covering both on-demand sessions (`browsers.create()`) and browser pool reservations. Null means no project-level cap. |
| `max_pooled_sessions` | `number \| null \| null` | No | Deprecated: pooled browsers now count toward `max_concurrent_sessions`. Always null. |

***

### limits.update

`projects.limits.update`

Set a project's concurrent-browser cap.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.projects.limits.update({ id_or_name: 'my-project' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Project ID or name |
| `max_concurrent_invocations` | `number \| null` | No | Maximum concurrent app invocations for this project. Set to 0 to remove the cap; omit to leave unchanged. |
| `max_concurrent_sessions` | `number \| null` | No | Maximum concurrent browsers for this project, covering both on-demand sessions and browser pool reservations. Set to 0 to remove the cap; omit to leave unchanged. |
| `max_pooled_sessions` | `number \| null` | No | Deprecated: pooled browsers now count toward `max_concurrent_sessions`. Requests that set this field are rejected with a 400. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `max_concurrent_invocations` | `number \| null \| null` | No | Maximum concurrent app invocations for this project. Null means no project-level cap. |
| `max_concurrent_sessions` | `number \| null \| null` | No | Maximum concurrent browsers for this project, covering both on-demand sessions (`browsers.create()`) and browser pool reservations. Null means no project-level cap. |
| `max_pooled_sessions` | `number \| null \| null` | No | Deprecated: pooled browsers now count toward `max_concurrent_sessions`. Always null. |

***

### list

`projects.list`

List the org's projects.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.projects.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `limit` | `number` | No | Maximum number of results to return |
| `offset` | `number` | No | Number of results to skip |
| `query` | `string` | No | Case-insensitive substring match against project name |
| `name` | `string` | No | Exact-match filter on project name using the database collation. In production, matching is case- and accent-insensitive. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | This page of results. |
| `has_more` | `boolean` | Yes | True when more results follow; pass next\_offset as offset to read them. |
| `next_offset` | `number \| null` | Yes | Value for `offset` that reads the next page, or null on the last page. |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   created_at?: string | null,
>   id?: string | null,
>   name?: string | null,
>   status?: string | null,
>   updated_at?: string | null
> }[]
> ```

***

### update

`projects.update`

Rename or change a project.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.projects.update({ id_or_name: 'my-project' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Project ID or name |
| `name` | `string` | No | New project name (1-255 Unicode code points; cannot contain `/` or `%`) |
| `status` | `active \| archived` | No | New project status |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `created_at` | `string \| null` | No | When the project was created |
| `id` | `string \| null` | No | Unique project identifier |
| `name` | `string \| null` | No | Project name |
| `status` | `string \| null` | No | Project status |
| `updated_at` | `string \| null` | No | When the project was last updated |

***

## Proxies

### check

`proxies.check`

Check that a proxy works and see its exit IP.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.proxies.check({ id_or_name: 'my-proxy' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Proxy ID. Name-based addressing is supported only for retrieval. |
| `url` | `string` | No | An optional URL to test reachability against. If provided, the proxy check will test connectivity to this URL instead of the default test URLs. Only HTTP and HTTPS schemes are allowed, and the URL must resolve to a public IP address. For ISP proxies, the exit IP is stable, so a successful check reliably indicates that subsequent browser sessions will reach the target site with the same IP. For residential and mobile proxies, the exit node changes between requests, so a successful check validates proxy configuration but does not guarantee that a subsequent browser session will use the same exit IP or reach the same site — it is useful for verifying credentials and connectivity, not for predicting site-specific behavior. When provided, the check result does not update the proxy's health status, since a failure may indicate a problem with the target site rather than the proxy itself. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `bypass_hosts` | `string[] \| null` | No | Hostnames that should bypass the parent proxy and connect directly. |
| `config` | `object \| null` | No | Configuration specific to the selected proxy `type`. |
| `id` | `string \| null` | No | — |
| `ip_address` | `string \| null` | No | IP address that the proxy uses when making requests. |
| `last_checked` | `string \| null` | No | Timestamp of the last health check performed on this proxy. |
| `name` | `string \| null` | No | Readable name of the proxy. |
| `protocol` | `string \| null` | No | Protocol to use for the proxy connection. |
| `status` | `string \| null` | No | Current health status of the proxy. |
| `type` | `string \| null` | No | Proxy type to use. In terms of quality for avoiding bot-detection, from best to worst: `mobile` > `residential` > `isp`. `datacenter` is deprecated; use `isp` instead. Existing datacenter proxies remain supported. |

> [accordion] config full type
>
> ```ts theme={null}
> {
>   country?: string | null
> } | {
>   country?: string | null,
>   ip_address?: string | null
> } | {
>   asn?: string | null,
>   city?: string | null,
>   country?: string | null,
>   os?: string | null,
>   state?: string | null,
>   zip?: string | null
> } | {
>   city?: string | null,
>   country?: string | null,
>   state?: string | null
> } | {
>   has_ca_bundle?: boolean | null,
>   has_password?: boolean | null,
>   host?: string | null,
>   port?: number | null,
>   username?: string | null
> } | null
> ```

***

### create

`proxies.create`

Create a proxy configuration (datacenter, ISP, residential, mobile or your own) for browsers to route through.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.proxies.create({ type: 'datacenter' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `bypass_hosts` | `string[]` | No | Hostnames that should bypass the parent proxy and connect directly. |
| `config` | `object` | No | Configuration specific to the selected proxy `type`. |
| `name` | `string` | No | Readable name of the proxy. |
| `protocol` | `http \| https` | No | Protocol to use for the proxy connection. |
| `type` | `datacenter \| isp \| residential \| mobile \| custom` | Yes | Proxy type to use. In terms of quality for avoiding bot-detection, from best to worst: `mobile` > `residential` > `isp`. `datacenter` is deprecated; use `isp` instead. Datacenter proxy creation remains supported for backward compatibility. |

> [accordion] config full type
>
> ```ts theme={null}
> {
>   country?: string
> } | {
>   country?: string,
>   ip_address?: string
> } | {
>   asn?: string,
>   city?: string,
>   country?: string,
>   os?: windows | macos | android,
>   state?: string,
>   zip?: string
> } | {
>   city?: string,
>   country?: string,
>   state?: string
> } | {
>   ca_bundle?: string,
>   host: string,
>   password?: string,
>   port: number,
>   username?: string
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `bypass_hosts` | `string[] \| null` | No | Hostnames that should bypass the parent proxy and connect directly. |
| `config` | `object \| null` | No | Configuration specific to the selected proxy `type`. |
| `id` | `string \| null` | No | — |
| `ip_address` | `string \| null` | No | IP address that the proxy uses when making requests. |
| `last_checked` | `string \| null` | No | Timestamp of the last health check performed on this proxy. |
| `name` | `string \| null` | No | Readable name of the proxy. |
| `protocol` | `string \| null` | No | Protocol to use for the proxy connection. |
| `status` | `string \| null` | No | Current health status of the proxy. |
| `type` | `string \| null` | No | Proxy type to use. In terms of quality for avoiding bot-detection, from best to worst: `mobile` > `residential` > `isp`. `datacenter` is deprecated; use `isp` instead. Existing datacenter proxies remain supported. |

> [accordion] config full type
>
> ```ts theme={null}
> {
>   country?: string | null
> } | {
>   country?: string | null,
>   ip_address?: string | null
> } | {
>   asn?: string | null,
>   city?: string | null,
>   country?: string | null,
>   os?: string | null,
>   state?: string | null,
>   zip?: string | null
> } | {
>   city?: string | null,
>   country?: string | null,
>   state?: string | null
> } | {
>   has_ca_bundle?: boolean | null,
>   has_password?: boolean | null,
>   host?: string | null,
>   port?: number | null,
>   username?: string | null
> } | null
> ```

***

### delete

`proxies.delete`

Delete a proxy configuration. Cannot be undone.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.kernel.api.proxies.delete({ id_or_name: 'my-proxy' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Proxy ID. Name-based addressing is supported only for retrieval. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### get

`proxies.get`

Get a proxy configuration.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.proxies.get({ id_or_name: 'my-proxy' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `bypass_hosts` | `string[] \| null` | No | Hostnames that should bypass the parent proxy and connect directly. |
| `config` | `object \| null` | No | Configuration specific to the selected proxy `type`. |
| `id` | `string \| null` | No | — |
| `ip_address` | `string \| null` | No | IP address that the proxy uses when making requests. |
| `last_checked` | `string \| null` | No | Timestamp of the last health check performed on this proxy. |
| `name` | `string \| null` | No | Readable name of the proxy. |
| `protocol` | `string \| null` | No | Protocol to use for the proxy connection. |
| `status` | `string \| null` | No | Current health status of the proxy. |
| `type` | `string \| null` | No | Proxy type to use. In terms of quality for avoiding bot-detection, from best to worst: `mobile` > `residential` > `isp`. `datacenter` is deprecated; use `isp` instead. Existing datacenter proxies remain supported. |

> [accordion] config full type
>
> ```ts theme={null}
> {
>   country?: string | null
> } | {
>   country?: string | null,
>   ip_address?: string | null
> } | {
>   asn?: string | null,
>   city?: string | null,
>   country?: string | null,
>   os?: string | null,
>   state?: string | null,
>   zip?: string | null
> } | {
>   city?: string | null,
>   country?: string | null,
>   state?: string | null
> } | {
>   has_ca_bundle?: boolean | null,
>   has_password?: boolean | null,
>   host?: string | null,
>   port?: number | null,
>   username?: string | null
> } | null
> ```

***

### list

`proxies.list`

List proxy configurations.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.proxies.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `limit` | `number` | No | Limit the number of proxies to return. |
| `offset` | `number` | No | Offset the number of proxies to return. |
| `query` | `string` | No | Case-insensitive substring match against proxy name, host, or IP address. IDs match by exact value. |
| `name` | `string` | No | Exact-match filter on proxy name using the database collation. In production, matching is case- and accent-insensitive. Names are not required to be unique, so multiple proxies may match. |
| `ip_address` | `string` | No | Exact match on the primary exit IP of ISP proxies. Must be an IPv4 address. Only ISP proxies are matched: the ip\_address shown on other proxy types is a one-time observation, not a stable identity. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | This page of results. |
| `has_more` | `boolean` | Yes | True when more results follow; pass next\_offset as offset to read them. |
| `next_offset` | `number \| null` | Yes | Value for `offset` that reads the next page, or null on the last page. |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   bypass_hosts?: string[] | null,
>   config?: {
>     country?: string | null
>   } | {
>     country?: string | null,
>     ip_address?: string | null
>   } | {
>     asn?: string | null,
>     city?: string | null,
>     country?: string | null,
>     os?: string | null,
>     state?: string | null,
>     zip?: string | null
>   } | {
>     city?: string | null,
>     country?: string | null,
>     state?: string | null
>   } | {
>     has_ca_bundle?: boolean | null,
>     has_password?: boolean | null,
>     host?: string | null,
>     port?: number | null,
>     username?: string | null
>   } | null,
>   id?: string | null,
>   ip_address?: string | null,
>   last_checked?: string | null,
>   name?: string | null,
>   protocol?: string | null,
>   status?: string | null,
>   type?: string | null
> }[]
> ```

***

### update

`proxies.update`

Change a proxy configuration.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.proxies.update({ id_or_name: 'my-proxy' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Proxy ID. Name-based addressing is supported only for retrieval. |
| `config` | `object` | No | Type-specific changes. Only ISP proxies accept a config update. |
| `name` | `string` | No | New proxy name. Proxy names are trimmed and length-checked only; duplicates are allowed because proxies are updated by ID, not by name. |

> [accordion] config full type
>
> ```ts theme={null}
> {
>   ip_address: string
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `bypass_hosts` | `string[] \| null` | No | Hostnames that should bypass the parent proxy and connect directly. |
| `config` | `object \| null` | No | Configuration specific to the selected proxy `type`. |
| `id` | `string \| null` | No | — |
| `ip_address` | `string \| null` | No | IP address that the proxy uses when making requests. |
| `last_checked` | `string \| null` | No | Timestamp of the last health check performed on this proxy. |
| `name` | `string \| null` | No | Readable name of the proxy. |
| `protocol` | `string \| null` | No | Protocol to use for the proxy connection. |
| `status` | `string \| null` | No | Current health status of the proxy. |
| `type` | `string \| null` | No | Proxy type to use. In terms of quality for avoiding bot-detection, from best to worst: `mobile` > `residential` > `isp`. `datacenter` is deprecated; use `isp` instead. Existing datacenter proxies remain supported. |

> [accordion] config full type
>
> ```ts theme={null}
> {
>   country?: string | null
> } | {
>   country?: string | null,
>   ip_address?: string | null
> } | {
>   asn?: string | null,
>   city?: string | null,
>   country?: string | null,
>   os?: string | null,
>   state?: string | null,
>   zip?: string | null
> } | {
>   city?: string | null,
>   country?: string | null,
>   state?: string | null
> } | {
>   has_ca_bundle?: boolean | null,
>   has_password?: boolean | null,
>   host?: string | null,
>   port?: number | null,
>   username?: string | null
> } | null
> ```

***

## Proxy IPs

### get

`proxyIPs.get`

Get a reserved ISP proxy IP.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.proxyIPs.get({ ip_address: '203.0.113.10' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `ip_address` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `country` | `string \| null` | No | ISO 3166 country code of the IP. |
| `ip_address` | `string \| null` | No | Reserved exit IP address. |
| `proxies` | `object[] \| null` | No | ISP proxies in the current project whose primary exit IP is this address. |
| `proxy_count` | `number \| null` | No | Number of ISP proxies across the organization whose primary exit IP is this address. |
| `status` | `string \| null` | No | — |

> [accordion] proxies full type
>
> ```ts theme={null}
> {
>   id?: string | null,
>   name?: string | null
> }[] | null
> ```

***

### list

`proxyIPs.list`

List the org's reserved ISP proxy IPs.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.proxyIPs.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `limit` | `number` | No | Limit the number of IPs to return. |
| `offset` | `number` | No | Offset the number of IPs to return. |
| `country` | `string` | No | ISO 3166 country code to filter by. Must be a country ISP proxies support. |
| `status` | `active \| excluded` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | This page of results. |
| `has_more` | `boolean` | Yes | True when more results follow; pass next\_offset as offset to read them. |
| `next_offset` | `number \| null` | Yes | Value for `offset` that reads the next page, or null on the last page. |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   country?: string | null,
>   ip_address?: string | null,
>   status?: string | null
> }[]
> ```

***

## Reports

### create

`reports.create`

Submit a typed report against a task (validated against the report type's schema).

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.reports.create({
	task_id: 'task_123',
	type: 'my-report-type',
	data: { key: 'value' },
});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `idempotency_key` | `string` | No | Makes retrying the create safe. A retry with the same key and the same request returns the record the first call created, with status 200, instead of creating another. Reusing a key with a different request returns 422. Keys are scoped to the project and do not expire. The Kernel SDKs send a key automatically and reuse it when they retry. |
| `data` | `object` | Yes | Report data. It must match the schema of the report type's version and encode to at most 16 KB of JSON. |
| `occurred_at` | `string` | No | When the reported event happened. Defaults to the time the report is submitted. Must be no more than 5 minutes in the future or 30 days in the past. |
| `schema_version` | `number` | No | Version of the report type's schema to validate data against. Defaults to the type's latest version, which the response returns. |
| `session_id` | `string` | No | ID of the browser the report was observed in. It must belong to the task's project; deleted browsers are accepted. The browser is linked to the task if it is not already. |
| `task_id` | `string` | Yes | ID of the task to report against. |
| `type` | `string` | Yes | Report type name. List report types to see the available types and their schemas. |

> [accordion] data full type
>
> ```ts theme={null}
> {
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `created_at` | `string \| null` | No | When the report was submitted |
| `data` | `object \| null` | No | Report data, matching the report type's schema |
| `id` | `string \| null` | No | Unique identifier for the report |
| `occurred_at` | `string \| null` | No | When the reported event happened |
| `schema_version` | `number \| null` | No | Version of the report type's schema that data was validated against |
| `session_id` | `string \| null \| null` | No | ID of the browser the report was observed in, if any |
| `task_id` | `string \| null` | No | ID of the task the report belongs to |
| `type` | `string \| null` | No | Report type name |

> [accordion] data full type
>
> ```ts theme={null}
> {
> } | null
> ```

***

### get

`reports.get`

Get a report.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.reports.get({ id: 'report_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Report ID |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `created_at` | `string \| null` | No | When the report was submitted |
| `data` | `object \| null` | No | Report data, matching the report type's schema |
| `id` | `string \| null` | No | Unique identifier for the report |
| `occurred_at` | `string \| null` | No | When the reported event happened |
| `schema_version` | `number \| null` | No | Version of the report type's schema that data was validated against |
| `session_id` | `string \| null \| null` | No | ID of the browser the report was observed in, if any |
| `task_id` | `string \| null` | No | ID of the task the report belongs to |
| `type` | `string \| null` | No | Report type name |

> [accordion] data full type
>
> ```ts theme={null}
> {
> } | null
> ```

***

### list

`reports.list`

List a task's reports, oldest first.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.reports.list({ task_id: 'task_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `task_id` | `string` | Yes | Task whose reports to list. |
| `type` | `string` | No | Only return reports of this type. |
| `limit` | `number` | No | Limit the number of reports to return. |
| `offset` | `number` | No | Offset the number of reports to return. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | This page of results. |
| `has_more` | `boolean` | Yes | True when more results follow; pass next\_offset as offset to read them. |
| `next_offset` | `number \| null` | Yes | Value for `offset` that reads the next page, or null on the last page. |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   created_at?: string | null,
>   data?: {
>   } | null,
>   id?: string | null,
>   occurred_at?: string | null,
>   schema_version?: number | null,
>   session_id?: string | null | null,
>   task_id?: string | null,
>   type?: string | null
> }[]
> ```

***

## Report Types

### get

`reportTypes.get`

Get a report type and its schema.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.reportTypes.get({ type: 'my-report-type' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `type` | `string` | Yes | Report type name, such as task.result |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `description` | `string \| null` | No | What the report type records and when to submit it |
| `latest_version` | `number \| null` | No | Highest version that is not retired. A report submitted without a schema\_version uses this version. It is 0 when every version is retired. |
| `schema` | `object \| null` | No | JSON Schema (draft 2020-12) of the latest version, which a report's data must match. Its field descriptions and examples describe what to send. Null when every version is retired. |
| `type` | `string \| null` | No | Report type name, such as task.result |
| `versions` | `object[] \| null` | No | Every version of the type, oldest first, including retired versions. |

> [accordion] schema full type
>
> ```ts theme={null}
> {
> } | null | null
> ```

> [accordion] versions full type
>
> ```ts theme={null}
> {
>   retired?: boolean | null,
>   version?: number | null
> }[] | null
> ```

***

### list

`reportTypes.list`

List report types.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.reportTypes.list({ task_id: 'task_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `task_id` | `string` | Yes | Task the agent is finding a report type for. |
| `limit` | `number` | No | Limit the number of report types to return. |
| `offset` | `number` | No | Offset the number of report types to return. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | This page of results. |
| `has_more` | `boolean` | Yes | True when more results follow; pass next\_offset as offset to read them. |
| `next_offset` | `number \| null` | Yes | Value for `offset` that reads the next page, or null on the last page. |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   description?: string | null,
>   latest_version?: number | null,
>   type?: string | null
> }[]
> ```

***

### versions.get

`reportTypes.versions.get`

Get one version of a report type's schema.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.reportTypes.versions.get({ type: 'my-report-type', version: 1 });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `type` | `string` | Yes | Report type name, such as task.result |
| `version` | `number` | Yes | Schema version number, starting at 1. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `retired` | `boolean \| null` | No | Whether the version is retired. Retired versions are no longer accepted for new reports; existing reports keep them. |
| `schema` | `object \| null` | No | JSON Schema (draft 2020-12) that a report's data must match. Its field descriptions and examples describe what to send. |
| `type` | `string \| null` | No | Report type name, such as task.result |
| `version` | `number \| null` | No | Schema version number, starting at 1. |

> [accordion] schema full type
>
> ```ts theme={null}
> {
> } | null
> ```

***

## Search

### contents.fetch

`search.contents.fetch`

Fetch the page contents of chosen results from an earlier search (by result\_ids or the top limit results).

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.search.contents.fetch({ id: 'search_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Search resource ID returned by POST /search. |
| `content` | `object` | No | — |
| `limit` | `number` | No | Maximum number of search results to fetch when result\_ids is omitted, starting from rank 1. Mutually exclusive with result\_ids. |
| `result_ids` | `string[]` | No | Kernel-generated IDs from the referenced retained search, in desired response order. They are not provider-standard IDs. Mutually exclusive with limit. |
| `timeout_ms` | `number` | No | Overall deadline across all selected results. |

> [accordion] content full type
>
> ```ts theme={null}
> {
>   browser?: {
>     browser_id?: string,
>     mode?: curl | render
>   },
>   format?: markdown | text,
>   max_age_hours?: number,
>   max_chars?: number,
>   source?: auto | provider | browser,
>   timeout_ms?: number
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `contents` | `object[] \| null` | No | — |
| `search_id` | `string \| null` | No | — |
| `usage` | `object \| null` | No | — |
| `warnings` | `object[] \| null` | No | — |

> [accordion] contents full type
>
> ```ts theme={null}
> {
>   cache_status?: string | null,
>   completeness?: string | null,
>   error?: {
>     code?: string | null,
>     message?: string | null,
>     retryable?: boolean | null
>   } | null,
>   extractor_version?: string | null,
>   fetched_at?: string | null | null,
>   final_url?: string | null,
>   format?: string | null,
>   http_status?: number | null,
>   method?: string | null,
>   result_id?: string | null,
>   status?: string | null,
>   text?: string | null,
>   truncated?: boolean | null,
>   url?: string | null
> }[] | null
> ```

> [accordion] usage full type
>
> ```ts theme={null}
> {
>   content_fetches?: number | null,
>   cost?: number | null,
>   results_count?: number | null
> } | null
> ```

> [accordion] warnings full type
>
> ```ts theme={null}
> {
>   code?: string | null,
>   message?: string | null,
>   param?: string | null,
>   provider?: string | null,
>   result_id?: string | null
> }[] | null
> ```

***

### create

`search.create`

Search the web through one of Kernel's search providers and get ranked results (titles, URLs, snippets), kept for search.contents.fetch.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.search.create({ query: 'kernel browser automation' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `content` | `true \| object` | No | Optional portable content retrieval. Pass true for defaults or an options object. Omission never starts Kernel browser work; provider-supplied content is still returned when available, including when requested through native options. Both inline and deferred retrieval use the same options schema. |
| `country` | `string` | No | ISO 3166-1 alpha-2 search locale preference. |
| `end_date` | `string` | No | Inclusive publication-date upper bound; must not precede start\_date. If recency is also supplied, recency takes precedence with a warning. Unsupported or approximated filtering is reported, or rejected under strict\_params. |
| `exclude_domains` | `string[]` | No | Hostname exclusions, with the same best-effort/strict behavior as include\_domains. Provider-specific combinations that cannot be represented are reported via warnings or rejected in strict mode. |
| `include_domains` | `string[]` | No | Hostname inclusion preference, matching a hostname and its subdomains. Empty means unrestricted. Translated, emulated, or dropped with a warning according to provider capability unless strict\_params is true. Native boost modes remain advisory and are identified in warnings. |
| `include_raw` | `boolean` | No | Include untouched per-result payloads and the full serving-provider response in raw fields. Off by default; native top-level outputs such as answer remain available without it. |
| `language` | `string` | No | BCP 47 search language preference. |
| `max_results` | `number` | No | Requested result count from 1 through 100. The effective count is clamped to the serving provider's cap with a warning. Effective native counts are the lower of this limit and supplied provider-native count aliases. Strict mode rejects unsupported counts. |
| `query` | `string` | Yes | Primary search query. A provider-native multi-query option applies only to that provider; other providers in a fallback chain receive this query. |
| `recency` | `hour \| day \| week \| month \| year` | No | Relative search window. Takes precedence over start\_date/end\_date with a warning if both are set. Provider-native recency behavior is retained, including documented hour-to-day widening. Unsupported filters are rejected only in strict mode. |
| `safe_search` | `off \| moderate \| strict` | No | Optional safety preference. Omit to use provider defaults. Unsupported values are dropped with a warning unless strict\_params is true. A search filter is not an authorization boundary. |
| `start_date` | `string` | No | Inclusive publication-date lower bound. If recency is also supplied, recency takes precedence with a warning. Provider date semantics, precision, and unsupported filters are reported; unknown source dates are not fabricated or universally post-filtered. |
| `strategy` | `object` | No | — |
| `strict_params` | `boolean` | No | When false, unsupported portable parameters are omitted and approximations are described in warnings. When true, every supplied portable parameter must be honored exactly. Requests that cannot be served with those parameters are rejected. This does not guarantee identical rankings or document timestamps across indexes. Authentication and project isolation are always enforced. |
| `timeout_ms` | `number` | No | Overall deadline across search attempts and inline retrieval. No new attempt starts after the deadline. Completed search results survive inline retrieval timeouts. |

> [accordion] content full type
>
> ```ts theme={null}
> true | {
>   browser?: {
>     browser_id?: string,
>     mode?: curl | render
>   },
>   format?: markdown | text,
>   max_age_hours?: number,
>   max_chars?: number,
>   source?: auto | provider | browser,
>   timeout_ms?: number
> }
> ```

> [accordion] strategy full type
>
> ```ts theme={null}
> {
>   fallback_on?: (error | timeout | empty)[],
>   provider_options?: (
>     {
>       options?: {
>         count?: number,
>         extra_snippets?: boolean,
>         goggles?: string,
>         goggles_id?: string,
>         include_fetch_metadata?: boolean,
>         offset?: number,
>         operators?: string,
>         result_filter?: string,
>         search_lang?: string,
>         spellcheck?: boolean,
>         ui_lang?: string,
>         units?: metric | imperial
>       },
>       provider: brave
>     } | {
>       options?: {
>         category?: string,
>         compliance?: string,
>         contents?: {
>           highlights?: boolean,
>           text?: boolean
>         },
>         maxAgeHours?: number,
>         numResults?: number,
>         type?: auto | fast | instant
>       },
>       provider: exa
>     } | {
>       options?: {
>         last_updated_after_filter?: string,
>         last_updated_before_filter?: string,
>         max_results?: number,
>         max_tokens?: number,
>         max_tokens_per_page?: number,
>         query?: string[],
>         search_context_size?: low | medium | high,
>         search_language_filter?: string[]
>       },
>       provider: perplexity
>     } | {
>       options?: {
>         country?: string,
>         excludeDomains?: string[],
>         freshness?: last_24_hours | last_week | last_month | last_year,
>         includeDomains?: string[],
>         markdownOptions?: {
>           enabled?: boolean,
>           includeFrames?: boolean,
>           includeImages?: boolean,
>           includeLinks?: boolean,
>           maxAgeMs?: number,
>           pdf?: {
>             shouldParse?: boolean
>           },
>           shortenBase64Images?: boolean,
>           timeoutMS?: number,
>           useMainContentOnly?: boolean,
>           waitForMs?: number
>         },
>         numResults?: number,
>         queryFanout?: boolean,
>         tags?: string[],
>         timeoutMS?: number
>       },
>       provider: context
>     } | {
>       options?: {
>         advanced_settings?: {
>           excerpt_settings?: {
>             max_chars_per_result?: number | null
>           },
>           fetch_policy?: {
>             disable_cache_fallback?: boolean,
>             max_age_seconds?: number | null,
>             timeout_seconds?: number | null
>           },
>           location?: string | null,
>           max_results?: number | null,
>           source_policy?: {
>             after_date?: string | null,
>             exclude_domains?: string[],
>             include_domains?: string[]
>           }
>         },
>         client_model?: string,
>         max_chars_total?: number,
>         mode?: turbo | fast | basic | advanced,
>         objective?: string,
>         search_queries?: string[],
>         session_id?: string
>       },
>       provider: parallel
>     } | {
>       options?: {
>         count?: number,
>         end_time?: string,
>         exclude_domains?: string[],
>         exclude_text?: string[],
>         format?: markdown | text,
>         full_content?: {
>           enable?: boolean,
>           max_tokens?: number
>         },
>         highlight?: {
>           enable?: boolean,
>           max_tokens?: number
>         },
>         include_domains?: string[],
>         include_images?: boolean,
>         include_text?: string[],
>         language?: string[],
>         safesearch?: off | strict,
>         start_time?: string,
>         time_basis?: auto | published | crawled,
>         time_range?: day | week | month | year | d | w | m | y,
>         topic?: general | news
>       },
>       provider: octen
>     } | {
>       options?: {
>         boost_domains?: string[],
>         count?: number,
>         crawl_timeout?: number,
>         extraction?: {
>           extraction_mode: highlights | full_page,
>           full_page?: {
>             extraction_formats?: (html | markdown)[]
>           }
>         },
>         knowledge?: core,
>         language?: string,
>         offset?: number
>       },
>       provider: you
>     } | {
>       options?: {
>         auto_parameters?: boolean,
>         chunks_per_source?: number,
>         exact_match?: boolean,
>         filter_by_language?: boolean,
>         include_answer?: boolean | basic | advanced,
>         include_domains_mode?: filter | boost,
>         include_favicon?: boolean,
>         include_image_descriptions?: boolean,
>         include_images?: boolean,
>         include_raw_content?: boolean | markdown | text,
>         language?: string,
>         max_results?: number,
>         search_depth?: advanced | basic | fast | ultra-fast,
>         topic?: general | news | finance
>       },
>       provider: tavily
>     }
>   )[],
>   type: auto
> } | {
>   provider: {
>     options?: {
>       count?: number,
>       extra_snippets?: boolean,
>       goggles?: string,
>       goggles_id?: string,
>       include_fetch_metadata?: boolean,
>       offset?: number,
>       operators?: string,
>       result_filter?: string,
>       search_lang?: string,
>       spellcheck?: boolean,
>       ui_lang?: string,
>       units?: metric | imperial
>     },
>     provider: brave
>   } | {
>     options?: {
>       category?: string,
>       compliance?: string,
>       contents?: {
>         highlights?: boolean,
>         text?: boolean
>       },
>       maxAgeHours?: number,
>       numResults?: number,
>       type?: auto | fast | instant
>     },
>     provider: exa
>   } | {
>     options?: {
>       last_updated_after_filter?: string,
>       last_updated_before_filter?: string,
>       max_results?: number,
>       max_tokens?: number,
>       max_tokens_per_page?: number,
>       query?: string[],
>       search_context_size?: low | medium | high,
>       search_language_filter?: string[]
>     },
>     provider: perplexity
>   } | {
>     options?: {
>       country?: string,
>       excludeDomains?: string[],
>       freshness?: last_24_hours | last_week | last_month | last_year,
>       includeDomains?: string[],
>       markdownOptions?: {
>         enabled?: boolean,
>         includeFrames?: boolean,
>         includeImages?: boolean,
>         includeLinks?: boolean,
>         maxAgeMs?: number,
>         pdf?: {
>           shouldParse?: boolean
>         },
>         shortenBase64Images?: boolean,
>         timeoutMS?: number,
>         useMainContentOnly?: boolean,
>         waitForMs?: number
>       },
>       numResults?: number,
>       queryFanout?: boolean,
>       tags?: string[],
>       timeoutMS?: number
>     },
>     provider: context
>   } | {
>     options?: {
>       advanced_settings?: {
>         excerpt_settings?: {
>           max_chars_per_result?: number | null
>         },
>         fetch_policy?: {
>           disable_cache_fallback?: boolean,
>           max_age_seconds?: number | null,
>           timeout_seconds?: number | null
>         },
>         location?: string | null,
>         max_results?: number | null,
>         source_policy?: {
>           after_date?: string | null,
>           exclude_domains?: string[],
>           include_domains?: string[]
>         }
>       },
>       client_model?: string,
>       max_chars_total?: number,
>       mode?: turbo | fast | basic | advanced,
>       objective?: string,
>       search_queries?: string[],
>       session_id?: string
>     },
>     provider: parallel
>   } | {
>     options?: {
>       count?: number,
>       end_time?: string,
>       exclude_domains?: string[],
>       exclude_text?: string[],
>       format?: markdown | text,
>       full_content?: {
>         enable?: boolean,
>         max_tokens?: number
>       },
>       highlight?: {
>         enable?: boolean,
>         max_tokens?: number
>       },
>       include_domains?: string[],
>       include_images?: boolean,
>       include_text?: string[],
>       language?: string[],
>       safesearch?: off | strict,
>       start_time?: string,
>       time_basis?: auto | published | crawled,
>       time_range?: day | week | month | year | d | w | m | y,
>       topic?: general | news
>     },
>     provider: octen
>   } | {
>     options?: {
>       boost_domains?: string[],
>       count?: number,
>       crawl_timeout?: number,
>       extraction?: {
>         extraction_mode: highlights | full_page,
>         full_page?: {
>           extraction_formats?: (html | markdown)[]
>         }
>       },
>       knowledge?: core,
>       language?: string,
>       offset?: number
>     },
>     provider: you
>   } | {
>     options?: {
>       auto_parameters?: boolean,
>       chunks_per_source?: number,
>       exact_match?: boolean,
>       filter_by_language?: boolean,
>       include_answer?: boolean | basic | advanced,
>       include_domains_mode?: filter | boost,
>       include_favicon?: boolean,
>       include_image_descriptions?: boolean,
>       include_images?: boolean,
>       include_raw_content?: boolean | markdown | text,
>       language?: string,
>       max_results?: number,
>       search_depth?: advanced | basic | fast | ultra-fast,
>       topic?: general | news | finance
>     },
>     provider: tavily
>   },
>   type: pinned
> } | {
>   fallback_on?: (error | timeout | empty)[],
>   providers: (
>     {
>       options?: {
>         count?: number,
>         extra_snippets?: boolean,
>         goggles?: string,
>         goggles_id?: string,
>         include_fetch_metadata?: boolean,
>         offset?: number,
>         operators?: string,
>         result_filter?: string,
>         search_lang?: string,
>         spellcheck?: boolean,
>         ui_lang?: string,
>         units?: metric | imperial
>       },
>       provider: brave
>     } | {
>       options?: {
>         category?: string,
>         compliance?: string,
>         contents?: {
>           highlights?: boolean,
>           text?: boolean
>         },
>         maxAgeHours?: number,
>         numResults?: number,
>         type?: auto | fast | instant
>       },
>       provider: exa
>     } | {
>       options?: {
>         last_updated_after_filter?: string,
>         last_updated_before_filter?: string,
>         max_results?: number,
>         max_tokens?: number,
>         max_tokens_per_page?: number,
>         query?: string[],
>         search_context_size?: low | medium | high,
>         search_language_filter?: string[]
>       },
>       provider: perplexity
>     } | {
>       options?: {
>         country?: string,
>         excludeDomains?: string[],
>         freshness?: last_24_hours | last_week | last_month | last_year,
>         includeDomains?: string[],
>         markdownOptions?: {
>           enabled?: boolean,
>           includeFrames?: boolean,
>           includeImages?: boolean,
>           includeLinks?: boolean,
>           maxAgeMs?: number,
>           pdf?: {
>             shouldParse?: boolean
>           },
>           shortenBase64Images?: boolean,
>           timeoutMS?: number,
>           useMainContentOnly?: boolean,
>           waitForMs?: number
>         },
>         numResults?: number,
>         queryFanout?: boolean,
>         tags?: string[],
>         timeoutMS?: number
>       },
>       provider: context
>     } | {
>       options?: {
>         advanced_settings?: {
>           excerpt_settings?: {
>             max_chars_per_result?: number | null
>           },
>           fetch_policy?: {
>             disable_cache_fallback?: boolean,
>             max_age_seconds?: number | null,
>             timeout_seconds?: number | null
>           },
>           location?: string | null,
>           max_results?: number | null,
>           source_policy?: {
>             after_date?: string | null,
>             exclude_domains?: string[],
>             include_domains?: string[]
>           }
>         },
>         client_model?: string,
>         max_chars_total?: number,
>         mode?: turbo | fast | basic | advanced,
>         objective?: string,
>         search_queries?: string[],
>         session_id?: string
>       },
>       provider: parallel
>     } | {
>       options?: {
>         count?: number,
>         end_time?: string,
>         exclude_domains?: string[],
>         exclude_text?: string[],
>         format?: markdown | text,
>         full_content?: {
>           enable?: boolean,
>           max_tokens?: number
>         },
>         highlight?: {
>           enable?: boolean,
>           max_tokens?: number
>         },
>         include_domains?: string[],
>         include_images?: boolean,
>         include_text?: string[],
>         language?: string[],
>         safesearch?: off | strict,
>         start_time?: string,
>         time_basis?: auto | published | crawled,
>         time_range?: day | week | month | year | d | w | m | y,
>         topic?: general | news
>       },
>       provider: octen
>     } | {
>       options?: {
>         boost_domains?: string[],
>         count?: number,
>         crawl_timeout?: number,
>         extraction?: {
>           extraction_mode: highlights | full_page,
>           full_page?: {
>             extraction_formats?: (html | markdown)[]
>           }
>         },
>         knowledge?: core,
>         language?: string,
>         offset?: number
>       },
>       provider: you
>     } | {
>       options?: {
>         auto_parameters?: boolean,
>         chunks_per_source?: number,
>         exact_match?: boolean,
>         filter_by_language?: boolean,
>         include_answer?: boolean | basic | advanced,
>         include_domains_mode?: filter | boost,
>         include_favicon?: boolean,
>         include_image_descriptions?: boolean,
>         include_images?: boolean,
>         include_raw_content?: boolean | markdown | text,
>         language?: string,
>         max_results?: number,
>         search_depth?: advanced | basic | fast | ultra-fast,
>         topic?: general | news | finance
>       },
>       provider: tavily
>     }
>   )[],
>   type: fallback
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `answer` | `string \| null` | No | Provider-generated answer when requested (e.g. via Tavily include\_answer or Perplexity). Preserved independently of include\_raw. |
| `attempts` | `object[] \| null` | No | — |
| `expires_at` | `string \| null` | No | Expiration of result IDs for deferred retrieval. Results expire 24 hours after search completion. |
| `id` | `string \| null` | No | Search resource ID. Request tracing uses X-Request-Id. |
| `provider` | `string \| null` | No | Concrete serving provider, never auto or fallback. |
| `query` | `string \| null` | No | Echo of the query. Native multi-query inputs are visible in the selected strategy target and the optional raw response. |
| `raw` | `any \| null` | No | Full serving-provider response, including top-level metadata that does not belong to a result. Present only with include\_raw=true; untrusted provider data. |
| `results` | `object[] \| null` | No | — |
| `usage` | `object \| null` | No | — |
| `warnings` | `object[] \| null` | No | — |

> [accordion] attempts full type
>
> ```ts theme={null}
> {
>   duration_ms?: number | null,
>   error_code?: string | null,
>   outcome?: string | null,
>   provider?: string | null,
>   retryable?: boolean | null
> }[] | null
> ```

> [accordion] results full type
>
> ```ts theme={null}
> {
>   additional_snippets?: string[] | null,
>   content?: {
>     cache_status?: string | null,
>     completeness?: string | null,
>     error?: {
>       code?: string | null,
>       message?: string | null,
>       retryable?: boolean | null
>     } | null,
>     extractor_version?: string | null,
>     fetched_at?: string | null | null,
>     final_url?: string | null,
>     format?: string | null,
>     http_status?: number | null,
>     method?: string | null,
>     status?: string | null,
>     text?: string | null,
>     truncated?: boolean | null
>   } | null,
>   id?: string | null,
>   published_date?: string | null | null,
>   rank?: number | null,
>   raw?: any | null,
>   snippet?: string | null | null,
>   source?: string | null | null,
>   title?: string | null | null,
>   url?: string | null
> }[] | null
> ```

> [accordion] usage full type
>
> ```ts theme={null}
> {
>   content_fetches?: number | null,
>   cost?: number | null,
>   results_count?: number | null
> } | null
> ```

> [accordion] warnings full type
>
> ```ts theme={null}
> {
>   code?: string | null,
>   message?: string | null,
>   param?: string | null,
>   provider?: string | null,
>   result_id?: string | null
> }[] | null
> ```

***

### get

`search.get`

Get a search that was run earlier, with its results.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.search.get({ id: 'search_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Search resource ID returned by POST /search. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `answer` | `string \| null` | No | Provider-generated answer when requested (e.g. via Tavily include\_answer or Perplexity). Preserved independently of include\_raw. |
| `attempts` | `object[] \| null` | No | — |
| `expires_at` | `string \| null` | No | Expiration of result IDs for deferred retrieval. Results expire 24 hours after search completion. |
| `id` | `string \| null` | No | Search resource ID. Request tracing uses X-Request-Id. |
| `provider` | `string \| null` | No | Concrete serving provider, never auto or fallback. |
| `query` | `string \| null` | No | Echo of the query. Native multi-query inputs are visible in the selected strategy target and the optional raw response. |
| `raw` | `any \| null` | No | Full serving-provider response, including top-level metadata that does not belong to a result. Present only with include\_raw=true; untrusted provider data. |
| `results` | `object[] \| null` | No | — |
| `usage` | `object \| null` | No | — |
| `warnings` | `object[] \| null` | No | — |

> [accordion] attempts full type
>
> ```ts theme={null}
> {
>   duration_ms?: number | null,
>   error_code?: string | null,
>   outcome?: string | null,
>   provider?: string | null,
>   retryable?: boolean | null
> }[] | null
> ```

> [accordion] results full type
>
> ```ts theme={null}
> {
>   additional_snippets?: string[] | null,
>   content?: {
>     cache_status?: string | null,
>     completeness?: string | null,
>     error?: {
>       code?: string | null,
>       message?: string | null,
>       retryable?: boolean | null
>     } | null,
>     extractor_version?: string | null,
>     fetched_at?: string | null | null,
>     final_url?: string | null,
>     format?: string | null,
>     http_status?: number | null,
>     method?: string | null,
>     status?: string | null,
>     text?: string | null,
>     truncated?: boolean | null
>   } | null,
>   id?: string | null,
>   published_date?: string | null | null,
>   rank?: number | null,
>   raw?: any | null,
>   snippet?: string | null | null,
>   source?: string | null | null,
>   title?: string | null | null,
>   url?: string | null
> }[] | null
> ```

> [accordion] usage full type
>
> ```ts theme={null}
> {
>   content_fetches?: number | null,
>   cost?: number | null,
>   results_count?: number | null
> } | null
> ```

> [accordion] warnings full type
>
> ```ts theme={null}
> {
>   code?: string | null,
>   message?: string | null,
>   param?: string | null,
>   provider?: string | null,
>   result_id?: string | null
> }[] | null
> ```

***

### providers.list

`search.providers.list`

List the search providers and the options each supports.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.search.providers.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `slug` | `brave \| exa \| perplexity \| context \| parallel \| octen \| you \| tavily` | No | — |

**Output:** `object[]`

> [accordion] Output full type
>
> ```ts theme={null}
> {
>   content?: {
>     freshness_control?: boolean | null,
>     inline?: boolean | null,
>     post_hoc?: boolean | null
>   } | null,
>   max_results_cap?: number | null,
>   notes?: string[] | null,
>   params?: {
>     country?: {
>       notes?: string | null,
>       support?: string | null
>     } | null,
>     end_date?: {
>       notes?: string | null,
>       support?: string | null
>     } | null,
>     exclude_domains?: {
>       notes?: string | null,
>       support?: string | null
>     } | null,
>     include_domains?: {
>       notes?: string | null,
>       support?: string | null
>     } | null,
>     language?: {
>       notes?: string | null,
>       support?: string | null
>     } | null,
>     recency?: {
>       notes?: string | null,
>       support?: string | null
>     } | null,
>     safe_search?: {
>       notes?: string | null,
>       support?: string | null
>     } | null,
>     start_date?: {
>       notes?: string | null,
>       support?: string | null
>     } | null
>   } | null,
>   provider_options?: {
>     examples?: {
>     }[] | null,
>     schema?: {
>     } | null,
>     schema_ref?: string | null
>   } | null,
>   slug?: string | null
> }[]
> ```

***

## Tasks

### create

`tasks.create`

Record a task an agent is working on, optionally with the browsers it uses; submit reports against it.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.tasks.create({ description: 'example' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `idempotency_key` | `string` | No | Makes retrying the create safe. A retry with the same key and the same request returns the record the first call created, with status 200, instead of creating another. Reusing a key with a different request returns 422. Keys are scoped to the project and do not expire. The Kernel SDKs send a key automatically and reuse it when they retry. |
| `description` | `string` | Yes | What the task is meant to accomplish, at most 4 KB. |
| `metadata` | `Record<string, string>` | No | — |
| `session_ids` | `string[]` | No | IDs of browsers to link to the task. Each must belong to the request's project; deleted browsers can be linked. |
| `started_at` | `string` | No | When work on the task started. Defaults to the time the task is created. Must be no more than 5 minutes in the future or 30 days in the past. |
| `target_website` | `string` | No | Hostname of the website the task targets, without a scheme or path. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `created_at` | `string \| null` | No | When the task was created |
| `description` | `string \| null` | No | What the task is meant to accomplish |
| `id` | `string \| null` | No | Unique identifier for the task |
| `metadata` | `Record<string, string> \| null` | No | — |
| `session_ids` | `string[] \| null` | No | IDs of browsers linked to the task, oldest link first. Linked browsers may since have been deleted. |
| `started_at` | `string \| null` | No | When work on the task started |
| `target_website` | `string \| null \| null` | No | Hostname of the website the task targets |

***

### get

`tasks.get`

Get a task.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.tasks.get({ id: 'task_123' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Task ID |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `created_at` | `string \| null` | No | When the task was created |
| `description` | `string \| null` | No | What the task is meant to accomplish |
| `id` | `string \| null` | No | Unique identifier for the task |
| `metadata` | `Record<string, string> \| null` | No | — |
| `session_ids` | `string[] \| null` | No | IDs of browsers linked to the task, oldest link first. Linked browsers may since have been deleted. |
| `started_at` | `string \| null` | No | When work on the task started |
| `target_website` | `string \| null \| null` | No | Hostname of the website the task targets |

***

### linkBrowsers

`tasks.linkBrowsers`

Link browser sessions to a task.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.tasks.linkBrowsers({
	id: 'task_123',
	session_ids: ['htzv5orfit78e1m2biiifpbv'],
});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | Task ID |
| `session_ids` | `string[]` | Yes | IDs of browsers to link. Each must belong to the task's project; deleted browsers can be linked. Browsers already linked are ignored. A task can have at most 100 linked browsers. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `created_at` | `string \| null` | No | When the task was created |
| `description` | `string \| null` | No | What the task is meant to accomplish |
| `id` | `string \| null` | No | Unique identifier for the task |
| `metadata` | `Record<string, string> \| null` | No | — |
| `session_ids` | `string[] \| null` | No | IDs of browsers linked to the task, oldest link first. Linked browsers may since have been deleted. |
| `started_at` | `string \| null` | No | When work on the task started |
| `target_website` | `string \| null \| null` | No | Hostname of the website the task targets |

***

### list

`tasks.list`

List tasks, newest first.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.tasks.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `limit` | `number` | No | Limit the number of tasks to return. |
| `offset` | `number` | No | Offset the number of tasks to return. |
| `session_id` | `string` | No | Only return tasks linked to this browser ID. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | This page of results. |
| `has_more` | `boolean` | Yes | True when more results follow; pass next\_offset as offset to read them. |
| `next_offset` | `number \| null` | Yes | Value for `offset` that reads the next page, or null on the last page. |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   created_at?: string | null,
>   description?: string | null,
>   id?: string | null,
>   metadata?: Record<string, string> | null,
>   session_ids?: string[] | null,
>   started_at?: string | null,
>   target_website?: string | null | null
> }[]
> ```

***

## Telemetry

### destinations.create

`telemetry.destinations.create`

Add an OTLP destination that browser sessions export telemetry to.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.telemetry.destinations.create({ name: 'my-name', endpoint: 'example' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `description` | `string` | No | — |
| `endpoint` | `string` | Yes | Base endpoint of the OTLP/HTTP collector, without a signal path. Kernel appends the signal path itself, so pass `https://api.honeycomb.io` rather than `https://api.honeycomb.io/v1/logs`. If your provider's docs give you a signal-specific URL, drop the trailing `/v1/logs`, `/v1/traces`, or `/v1/metrics` — an endpoint that already carries one is rejected. Must be http or https, must resolve to a public address, and must carry no query string or fragment. Examples: `https://api.honeycomb.io`, `https://otlp-gateway-prod-us-east-0.grafana.net/otlp`, `https://otlp.datadoghq.com` (Datadog's OTLP intake for US1, not its logs intake). |
| `headers` | `Record<string, string>` | No | Headers sent with each export request, typically an ingestion key. Encrypted at rest and returned redacted. Names and values must be valid HTTP header tokens, and the names and values together cannot exceed 8192 bytes. Names are matched case-insensitively and stored canonicalized, so supplying two spellings of one header is rejected. |
| `name` | `string` | Yes | Unique within the organization. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `consecutive_failures` | `number \| null` | No | Failed deliveries since the last success, as observed by the relay process that wrote the latest outcome. Zero means the most recently recorded outcome succeeded. |
| `created_at` | `string \| null` | No | — |
| `description` | `string \| null` | No | — |
| `endpoint` | `string \| null` | No | OTLP/HTTP endpoint telemetry is sent to. |
| `headers` | `Record<string, string> \| null` | No | Headers sent with each export request. Names are returned in canonical form (`Authorization`, not `authorization`). Non-dashboard reads return values redacted as empty strings, so the keys are visible but the credentials are not. Dashboard reads return the stored values. |
| `id` | `string \| null` | No | — |
| `last_error` | `string \| null` | No | Sanitized class of the delivery failure recorded at `last_error_at`. It is retained after a later success, so its presence does not mean the destination is currently failing. Response bodies, endpoint URLs, credentials, and raw transport errors are never returned. |
| `last_error_at` | `string \| null` | No | Timestamp of the most recent failed delivery. It is retained after a later success, so it can predate `last_export_at`. Read `consecutive_failures` to tell whether the destination is currently failing. |
| `last_export_at` | `string \| null` | No | Timestamp of the most recent successful delivery. Moves only on success. |
| `name` | `string \| null` | No | Unique within the organization. Usable in place of the ID when selecting a destination, so it cannot be shaped like an ID. |
| `updated_at` | `string \| null` | No | — |

***

### destinations.delete

`telemetry.destinations.delete`

Delete an OTLP telemetry destination. Cannot be undone.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.kernel.api.telemetry.destinations.delete({ id_or_name: 'my-destination' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | OTLP destination ID or name |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### destinations.get

`telemetry.destinations.get`

Get an OTLP telemetry destination.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.telemetry.destinations.get({ id_or_name: 'my-destination' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | OTLP destination ID or name |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `consecutive_failures` | `number \| null` | No | Failed deliveries since the last success, as observed by the relay process that wrote the latest outcome. Zero means the most recently recorded outcome succeeded. |
| `created_at` | `string \| null` | No | — |
| `description` | `string \| null` | No | — |
| `endpoint` | `string \| null` | No | OTLP/HTTP endpoint telemetry is sent to. |
| `headers` | `Record<string, string> \| null` | No | Headers sent with each export request. Names are returned in canonical form (`Authorization`, not `authorization`). Non-dashboard reads return values redacted as empty strings, so the keys are visible but the credentials are not. Dashboard reads return the stored values. |
| `id` | `string \| null` | No | — |
| `last_error` | `string \| null` | No | Sanitized class of the delivery failure recorded at `last_error_at`. It is retained after a later success, so its presence does not mean the destination is currently failing. Response bodies, endpoint URLs, credentials, and raw transport errors are never returned. |
| `last_error_at` | `string \| null` | No | Timestamp of the most recent failed delivery. It is retained after a later success, so it can predate `last_export_at`. Read `consecutive_failures` to tell whether the destination is currently failing. |
| `last_export_at` | `string \| null` | No | Timestamp of the most recent successful delivery. Moves only on success. |
| `name` | `string \| null` | No | Unique within the organization. Usable in place of the ID when selecting a destination, so it cannot be shaped like an ID. |
| `updated_at` | `string \| null` | No | — |

***

### destinations.list

`telemetry.destinations.list`

List OTLP telemetry destinations.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.telemetry.destinations.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `limit` | `number` | No | Limit the number of destinations to return. |
| `offset` | `number` | No | Offset the number of destinations to return. |
| `query` | `string` | No | Case-insensitive substring match against destination name or endpoint. IDs match by exact value. |
| `name` | `string` | No | Exact-match filter on destination name using the database collation. In production, matching is case- and accent-insensitive. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | This page of results. |
| `has_more` | `boolean` | Yes | True when more results follow; pass next\_offset as offset to read them. |
| `next_offset` | `number \| null` | Yes | Value for `offset` that reads the next page, or null on the last page. |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   consecutive_failures?: number | null,
>   created_at?: string | null,
>   description?: string | null,
>   endpoint?: string | null,
>   headers?: Record<string, string> | null,
>   id?: string | null,
>   last_error?: string | null,
>   last_error_at?: string | null,
>   last_export_at?: string | null,
>   name?: string | null,
>   updated_at?: string | null
> }[]
> ```

***

### destinations.update

`telemetry.destinations.update`

Update an OTLP telemetry destination.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.telemetry.destinations.update({ id_or_name: 'my-destination' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | OTLP destination ID or name |
| `description` | `string` | No | — |
| `endpoint` | `string` | No | Base endpoint of the OTLP/HTTP collector, without a signal path. Same rules as on create. |
| `headers` | `Record<string, string \| null>` | No | Edits stored headers key by key rather than replacing the map. A string value adds or replaces that header, `null` deletes it, and any key you omit is left as it is. Names are matched case-insensitively, so `authorization` replaces a stored `Authorization` rather than adding a second entry. This is the credential rotation path; sessions already exporting pick up the new values without restarting. Names and values must be valid HTTP header tokens, and the names and values together cannot exceed 8192 bytes. |
| `name` | `string` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `consecutive_failures` | `number \| null` | No | Failed deliveries since the last success, as observed by the relay process that wrote the latest outcome. Zero means the most recently recorded outcome succeeded. |
| `created_at` | `string \| null` | No | — |
| `description` | `string \| null` | No | — |
| `endpoint` | `string \| null` | No | OTLP/HTTP endpoint telemetry is sent to. |
| `headers` | `Record<string, string> \| null` | No | Headers sent with each export request. Names are returned in canonical form (`Authorization`, not `authorization`). Non-dashboard reads return values redacted as empty strings, so the keys are visible but the credentials are not. Dashboard reads return the stored values. |
| `id` | `string \| null` | No | — |
| `last_error` | `string \| null` | No | Sanitized class of the delivery failure recorded at `last_error_at`. It is retained after a later success, so its presence does not mean the destination is currently failing. Response bodies, endpoint URLs, credentials, and raw transport errors are never returned. |
| `last_error_at` | `string \| null` | No | Timestamp of the most recent failed delivery. It is retained after a later success, so it can predate `last_export_at`. Read `consecutive_failures` to tell whether the destination is currently failing. |
| `last_export_at` | `string \| null` | No | Timestamp of the most recent successful delivery. Moves only on success. |
| `name` | `string \| null` | No | Unique within the organization. Usable in place of the ID when selecting a destination, so it cannot be shaped like an ID. |
| `updated_at` | `string \| null` | No | — |

***

## Vault Provider Configs

### create

`vaultProviderConfigs.create`

Register a vault provider configuration (card or payment provider settings shared by the org's projects).

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.vaultProviderConfigs.create({
	name: 'my-name',
	provider: 'link',
	credentials: { client_id: 'example', client_secret: 'example' },
});
```

**Input:** `object`

> [accordion] Input full type
>
> ```ts theme={null}
> {
> }& (
>   {
>     credentials: {
>       client_id: string,
>       client_secret: string,
>       publishable_key?: string
>     },
>     name: string,
>     provider: link
>   } | {
>     credentials: {
>       client_id: string,
>       client_secret: string
>     },
>     name: string,
>     provider: agentcard
>   } | {
>     credentials: {
>       client_id: string,
>       client_secret: string,
>       environment: sandbox | live,
>       vault_id: string
>     },
>     name: string,
>     provider: vgs
>   }
> )
> ```

**Output:** `object`

> [accordion] Output full type
>
> ```ts theme={null}
> {
>   client_id?: string | null,
>   created_at?: string | null,
>   id?: string | null,
>   name?: string | null,
>   provider?: string | null,
>   publishable_key?: string | null,
>   updated_at?: string | null
> } | {
>   client_id?: string | null,
>   created_at?: string | null,
>   id?: string | null,
>   name?: string | null,
>   provider?: string | null,
>   test_mode?: boolean | null,
>   updated_at?: string | null
> } | {
>   client_id?: string | null,
>   created_at?: string | null,
>   environment?: string | null,
>   id?: string | null,
>   name?: string | null,
>   provider?: string | null,
>   updated_at?: string | null,
>   vault_id?: string | null
> }
> ```

***

### delete

`vaultProviderConfigs.delete`

Delete an unused vault provider configuration. Cannot be undone.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.kernel.api.vaultProviderConfigs.delete({ id_or_name: 'my-provider-config' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Provider configuration ID or name in the organization. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### get

`vaultProviderConfigs.get`

Get a vault provider configuration.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.vaultProviderConfigs.get({ id_or_name: 'my-provider-config' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Provider configuration ID or name in the organization. |

**Output:** `object`

> [accordion] Output full type
>
> ```ts theme={null}
> {
>   client_id?: string | null,
>   created_at?: string | null,
>   id?: string | null,
>   name?: string | null,
>   provider?: string | null,
>   publishable_key?: string | null,
>   updated_at?: string | null
> } | {
>   client_id?: string | null,
>   created_at?: string | null,
>   id?: string | null,
>   name?: string | null,
>   provider?: string | null,
>   test_mode?: boolean | null,
>   updated_at?: string | null
> } | {
>   client_id?: string | null,
>   created_at?: string | null,
>   environment?: string | null,
>   id?: string | null,
>   name?: string | null,
>   provider?: string | null,
>   updated_at?: string | null,
>   vault_id?: string | null
> }
> ```

***

### list

`vaultProviderConfigs.list`

List vault provider configurations.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.vaultProviderConfigs.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `limit` | `number` | No | — |
| `offset` | `number` | No | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | This page of results. |
| `has_more` | `boolean` | Yes | True when more results follow; pass next\_offset as offset to read them. |
| `next_offset` | `number \| null` | Yes | Value for `offset` that reads the next page, or null on the last page. |

> [accordion] items full type
>
> ```ts theme={null}
> (
>   {
>     client_id?: string | null,
>     created_at?: string | null,
>     id?: string | null,
>     name?: string | null,
>     provider?: string | null,
>     publishable_key?: string | null,
>     updated_at?: string | null
>   } | {
>     client_id?: string | null,
>     created_at?: string | null,
>     id?: string | null,
>     name?: string | null,
>     provider?: string | null,
>     test_mode?: boolean | null,
>     updated_at?: string | null
>   } | {
>     client_id?: string | null,
>     created_at?: string | null,
>     environment?: string | null,
>     id?: string | null,
>     name?: string | null,
>     provider?: string | null,
>     updated_at?: string | null,
>     vault_id?: string | null
>   }
> )[]
> ```

***

### update

`vaultProviderConfigs.update`

Update a vault provider configuration.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.vaultProviderConfigs.update({ id_or_name: 'my-provider-config' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | Provider configuration ID or name in the organization. |
| `credentials` | `object` | No | Fields to update. Omitted credentials are left unchanged. A rejected update leaves existing credentials unchanged. |
| `name` | `string` | No | Unique within the organization. |

> [accordion] credentials full type
>
> ```ts theme={null}
> {
>   client_secret?: string,
>   publishable_key?: string
> }
> ```

**Output:** `object`

> [accordion] Output full type
>
> ```ts theme={null}
> {
>   client_id?: string | null,
>   created_at?: string | null,
>   id?: string | null,
>   name?: string | null,
>   provider?: string | null,
>   publishable_key?: string | null,
>   updated_at?: string | null
> } | {
>   client_id?: string | null,
>   created_at?: string | null,
>   id?: string | null,
>   name?: string | null,
>   provider?: string | null,
>   test_mode?: boolean | null,
>   updated_at?: string | null
> } | {
>   client_id?: string | null,
>   created_at?: string | null,
>   environment?: string | null,
>   id?: string | null,
>   name?: string | null,
>   provider?: string | null,
>   updated_at?: string | null,
>   vault_id?: string | null
> }
> ```

***

## Vaults

### delete

`vaults.delete`

Delete a vault and invalidate every item in it. Cannot be undone.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.kernel.api.vaults.delete({ id_or_name: 'my-vault' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### get

`vaults.get`

Get a vault.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.vaults.get({ id_or_name: 'my-vault' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `created_at` | `string \| null` | No | — |
| `id` | `string \| null` | No | — |
| `name` | `string \| null` | No | Immutable name assigned when the vault is created. |
| `updated_at` | `string \| null` | No | — |

***

### getEncryptionKey

`vaults.getEncryptionKey`

Get a vault's public key, for encrypting credential values in a browser before they are sent.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.vaults.getEncryptionKey({ id_or_name: 'my-vault' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `alg` | `string \| null` | No | JWE key management algorithm. |
| `enc` | `string \| null` | No | JWE content encryption algorithm. |
| `jwk` | `object \| null` | No | — |
| `kid` | `string \| null` | No | Key ID. Set it as the kid protected header of every encrypted\_value. |

> [accordion] jwk full type
>
> ```ts theme={null}
> {
>   crv?: string | null,
>   kty?: string | null,
>   y?: string | null,
>   x?: string | null
> } | null
> ```

***

### items.delete

`vaults.items.delete`

Delete a vault item and invalidate its secret. Cannot be undone.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.kernel.api.vaults.items.delete({ id_or_name: 'my-vault', key: 'my-item' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | — |
| `key` | `string` | Yes | — |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `success` | `true` | Yes | Kernel accepted the call; it answers with no body. |

***

### items.events

`vaults.items.events`

List a vault item's audit events.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.vaults.items.events({ id_or_name: 'my-vault', key: 'my-item' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | — |
| `key` | `string` | Yes | — |
| `after` | `string` | No | Return events after this event ID. |
| `include_deleted` | `boolean` | No | When true, also finds deleted items, and deleted vaults by ID only. `key` then also accepts an item ID, which takes precedence over a key with the same value; the lookup order is the item ID, then the live item with that key, then the most recently deleted one. `wait` is ignored for a deleted item or vault. |
| `wait` | `number` | No | Long-poll for new events for up to this many seconds. |

**Output:** `object[]`

> [accordion] Output full type
>
> ```ts theme={null}
> {
>   browser_id?: string | null,
>   created_at?: string | null,
>   data?: {
>   } | null,
>   id?: string | null,
>   name?: string | null
> }[]
> ```

***

### items.get

`vaults.items.get`

Get a vault item and the operations it currently offers (wait up to 60 s for a change).

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.vaults.items.get({ id_or_name: 'my-vault', key: 'my-item' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | — |
| `key` | `string` | Yes | — |
| `wait` | `number` | No | Hold for up to this many seconds while the item is pending authorization, approval, or credential collection. Return the current item when ready or when the wait elapses. This does not wait for edits to an already-ready credential; poll GET without wait and compare version to observe changes after collect. Managed auth credentials are created ready, so wait returns immediately. |
| `expand` | `(payment_methods \| link_user_info \| link_shipping_addresses)[]` | No | Live fields advertised by `available_expansions` to include in `expanded`. |

**Output:** `object`

> [accordion] Output full type
>
> ```ts theme={null}
> {
>   action?: {
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null,
>     url?: string | null
>   } | {
>     connect_url?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     capture_token?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | null,
>   available_expansions?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   available_operations?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   created_at?: string | null,
>   description?: string | null,
>   expanded?: {
>     link_shipping_addresses?: {
>       address?: {
>         administrative_area?: string | null | null,
>         country_code?: string | null | null,
>         dependent_locality?: string | null | null,
>         line_1?: string | null | null,
>         line_2?: string | null | null,
>         locality?: string | null | null,
>         name?: string | null | null,
>         postal_code?: string | null | null,
>         sorting_code?: string | null | null
>       } | null,
>       id?: string | null,
>       is_default?: boolean | null,
>       nickname?: string | null | null
>     }[] | null,
>     link_user_info?: {
>       address?: {
>         city?: string | null | null,
>         country?: string | null | null,
>         line1?: string | null | null,
>         line2?: string | null | null,
>         postal_code?: string | null | null,
>         state?: string | null | null
>       } | null,
>       agent_wallet_spend_limits?: {
>         daily?: {
>           limit?: number | null | null,
>           remaining?: number | null | null,
>           used?: number | null
>         } | null,
>         per_transaction?: {
>           limit?: number | null | null
>         } | null,
>         thirty_day?: {
>           limit?: number | null | null,
>           remaining?: number | null | null,
>           used?: number | null
>         } | null
>       } | null,
>       agent_wallet_step_up?: {
>         action_url?: string | null | null,
>         status?: string | null
>       } | null,
>       default_spend_request_currency?: string | null,
>       eligible_for_balance?: boolean | null,
>       email?: string | null | null,
>       first_name?: string | null | null,
>       id?: string | null | null,
>       last_name?: string | null | null,
>       name?: string | null | null,
>       phone?: string | null | null
>     } | null,
>     payment_methods?: {
>       action?: {
>         capture_token?: string | null,
>         name?: string | null,
>         url?: string | null
>       } | null,
>       capabilities?: {
>         single_use_card?: {
>           eligible?: boolean | null,
>           reasons?: string[] | null
>         } | null
>       } | null,
>       display?: {
>         brand?: string | null,
>         label?: string | null,
>         last4?: string | null
>       } | null,
>       expires_at?: string | null,
>       id?: string | null,
>       is_default?: boolean | null,
>       issuer_reference?: string | null,
>       provider?: string | null,
>       status?: string | null,
>       status_reason?: string | null,
>       type?: string | null,
>       valid_until?: string | null
>     }[] | null
>   } | null,
>   expires_at?: string | null,
>   id?: string | null,
>   key?: string | null,
>   spec?: {
>     authorization?: {
>       client?: {
>         type?: string | null
>       } | {
>         provider_config?: {
>           id?: string | null,
>           name?: string | null
>         } | null,
>         type?: string | null
>       } | null,
>       method?: string | null,
>       token_refresh?: string | null
>     } | null,
>     provider?: string | null
>   } | {
>     provider?: string | null,
>     provider_config?: {
>       id?: string | null,
>       name?: string | null
>     } | null,
>     user_id?: string | null
>   } | {
>     provider?: string | null
>   } | {
>     authorization?: {
>       client?: {
>         type?: string | null
>       } | null,
>       method?: string | null
>     } | null,
>     provider?: string | null
>   } | {
>     provider?: string | null,
>     provider_config?: {
>       id?: string | null,
>       name?: string | null
>     } | null
>   } | null,
>   state?: {
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null,
>     user_id?: string | null
>   } | {
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | null,
>   type?: string | null,
>   updated_at?: string | null
> } | {
>   action?: {
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null,
>     url?: string | null
>   } | {
>     connect_url?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     capture_token?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | null,
>   available_expansions?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   available_operations?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   created_at?: string | null,
>   expires_at?: string | null,
>   id?: string | null,
>   key?: string | null,
>   spec?: {
>     amount?: number | null,
>     context?: string | null,
>     currency?: string | null,
>     line_items?: {
>       description?: string | null,
>       image_url?: string | null,
>       name?: string | null,
>       product_url?: string | null,
>       quantity?: number | null,
>       sku?: string | null,
>       totals?: {
>         amount?: number | null,
>         display_text?: string | null,
>         type?: string | null
>       }[] | null,
>       unit_amount?: number | null,
>       url?: string | null
>     }[] | null,
>     merchant_name?: string | null,
>     merchant_url?: string | null,
>     metadata?: Record<string, string> | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     recurring?: {
>       interval?: string | null,
>       interval_count?: number | null
>     } | null,
>     totals?: {
>       amount?: number | null,
>       display_text?: string | null,
>       type?: string | null
>     }[] | null,
>     wallet?: string | null
>   } | {
>     amount?: number | null,
>     card_id?: string | null,
>     checkout_origin?: string | null,
>     currency?: string | null,
>     discount?: number | null,
>     line_items?: {
>       amount?: number | null,
>       brand?: string | null,
>       image_url?: string | null,
>       options?: string | null,
>       quantity?: number | null,
>       title?: string | null,
>       unit_amount?: number | null
>     }[] | null,
>     merchant?: string | null,
>     provider?: string | null,
>     shipping?: number | null,
>     subtotal?: number | null,
>     tax?: number | null,
>     wallet?: string | null
>   } | {
>     amount?: number | null,
>     currency?: string | null,
>     expires_at?: string | null,
>     merchant_category?: string | null,
>     merchant_category_code?: string | null,
>     merchant_country?: string | null,
>     merchant_name?: string | null,
>     merchant_url?: string | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     single_use_card?: {
>       billing_address?: {
>         city?: string | null,
>         country?: string | null,
>         line1?: string | null,
>         line2?: string | null,
>         postal_code?: string | null,
>         state?: string | null
>       } | null,
>       cvc?: string | null,
>       exp_month?: string | null,
>       exp_year?: string | null,
>       name?: string | null,
>       number?: string | null,
>       reference?: string | null
>     } | null,
>     wallet?: string | null
>   } | {
>     amount?: number | null,
>     context?: string | null,
>     currency?: string | null,
>     line_items?: {
>       name?: string | null,
>       quantity?: number | null,
>       unit_amount?: number | null
>     }[] | null,
>     merchant_country?: string | null,
>     merchant_name?: string | null,
>     merchant_url?: string | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     totals?: {
>       amount?: number | null,
>       type?: string | null
>     }[] | null,
>     wallet?: string | null
>   } | {
>     amount?: number | null,
>     card?: {
>       cvc_alias?: string | null,
>       exp_month?: number | null,
>       exp_year?: number | null,
>       last4?: string | null,
>       pan_alias?: string | null
>     } | null,
>     card_mode?: string | null,
>     currency?: string | null,
>     merchant_name?: string | null,
>     merchant_url?: string | null,
>     provider?: string | null,
>     wallet?: string | null
>   } | null,
>   state?: {
>     credential_type?: string | null,
>     domains?: string[] | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     aliases?: {
>       cvc?: string | null,
>       exp_month?: string | null,
>       exp_year?: string | null,
>       number?: string | null
>     } | null,
>     authorization?: {
>       actual_cents?: number | null,
>       amount?: string | null,
>       amount_authority?: string | null,
>       amount_cents?: number | null,
>       amount_verified?: boolean | null,
>       approval_url?: string | null,
>       browser_id?: string | null,
>       charged_amount_cents?: number | null,
>       charged_currency?: string | null,
>       charged_kind?: string | null,
>       created_at?: string | null,
>       currency?: string | null,
>       expected_cents?: number | null,
>       expires_at?: string | null,
>       id?: string | null,
>       merchant?: string | null,
>       psp?: string | null,
>       psp_error_code?: string | null,
>       reason?: string | null,
>       replay_attempted?: boolean | null,
>       replay_delivered?: boolean | null,
>       replay_status?: number | null,
>       status?: string | null
>     } | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     preparation?: {
>       approval_url?: string | null,
>       browser_id?: string | null,
>       created_at?: string | null,
>       environment?: string | null,
>       expires_at?: string | null,
>       id?: string | null,
>       merchant_origin?: string | null,
>       psp?: string | null,
>       status?: string | null
>     } | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     domains?: string[] | null,
>     funding_status?: string | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     source?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     domains?: string[] | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     domains?: string[] | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | null,
>   type?: string | null,
>   updated_at?: string | null
> } | {
>   action?: {
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null,
>     url?: string | null
>   } | {
>     connect_url?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     capture_token?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | null,
>   available_expansions?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   available_operations?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   created_at?: string | null,
>   expires_at?: string | null,
>   id?: string | null,
>   key?: string | null,
>   spec?: {
>     amount?: number | null,
>     context?: string | null,
>     currency?: string | null,
>     line_items?: {
>       description?: string | null,
>       image_url?: string | null,
>       name?: string | null,
>       product_url?: string | null,
>       quantity?: number | null,
>       sku?: string | null,
>       totals?: {
>         amount?: number | null,
>         display_text?: string | null,
>         type?: string | null
>       }[] | null,
>       unit_amount?: number | null,
>       url?: string | null
>     }[] | null,
>     merchant_name?: string | null,
>     merchant_url?: string | null,
>     metadata?: Record<string, string> | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     recurring?: {
>       interval?: string | null,
>       interval_count?: number | null
>     } | null,
>     totals?: {
>       amount?: number | null,
>       display_text?: string | null,
>       type?: string | null
>     }[] | null,
>     wallet?: string | null
>   } | {
>     amount?: number | null,
>     currency?: string | null,
>     merchant_category?: string | null,
>     merchant_category_code?: string | null,
>     merchant_country?: string | null,
>     merchant_name?: string | null,
>     merchant_url?: string | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     wallet?: string | null
>   } | null,
>   state?: {
>     credential_type?: string | null,
>     domains?: string[] | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     domains?: string[] | null,
>     funding_status?: string | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     source?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | null,
>   type?: string | null,
>   updated_at?: string | null
> } | {
>   action?: {
>     connect_url?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | null,
>   available_expansions?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   available_operations?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   created_at?: string | null,
>   expires_at?: string | null,
>   id?: string | null,
>   key?: string | null,
>   spec?: {
>     authorization?: {
>       client?: {
>         type?: string | null
>       } | null,
>       method?: string | null
>     } | null,
>     provider?: string | null
>   } | null,
>   state?: {
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | null,
>   type?: string | null,
>   updated_at?: string | null
> } | {
>   action?: {
>     expires_at?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | {
>     access_request_reference?: string | null,
>     instructions?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | null,
>   available_expansions?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   available_operations?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   created_at?: string | null,
>   id?: string | null,
>   key?: string | null,
>   spec?: {
>     description?: string | null,
>     fields?: {
>       label?: string | null,
>       name?: string | null,
>       required?: boolean | null,
>       sensitive?: boolean | null,
>       type?: string | null
>     }[] | null,
>     provider?: string | null
>   } | {
>     access_token_expires_at?: string | null,
>     account?: string | null,
>     provider?: string | null,
>     requests?: {
>       entries?: {
>         id?: string | null,
>         keywords?: string[] | null,
>         parameters?: {
>           website?: string | null
>         } | null,
>         reason?: string | null,
>         type?: string | null
>       }[] | null,
>       goal?: string | null,
>       version?: number | null
>     } | null
>   } | {
>     connection_id?: string | null,
>     description?: string | null,
>     provider?: string | null
>   } | null,
>   state?: {
>     fields?: Record<string, {
>       has_value?: boolean | null,
>       value?: string | null
>     }> | null,
>     provider?: string | null,
>     status?: string | null
>   } | {
>     access_request?: {
>       createdAt?: string | null,
>       entries?: {
>         id?: string | null,
>         keywords?: string[] | null,
>         parameters?: {
>           website?: string | null
>         } | null,
>         reason?: string | null,
>         type?: string | null
>       }[] | null,
>       goal?: string | null,
>       granted_count?: number | null,
>       has_autofill_token?: boolean | null,
>       id?: string | null,
>       identity?: string | null,
>       path?: string | null,
>       request?: {
>         entries?: {
>           id?: string | null,
>           keywords?: string[] | null,
>           parameters?: {
>             website?: string | null
>           } | null,
>           reason?: string | null,
>           type?: string | null
>         }[] | null,
>         goal?: string | null,
>         version?: number | null
>       } | null,
>       resolved?: {
>         entryId?: string | null,
>         reference?: string | null
>       }[] | null,
>       state?: string | null
>     } | null,
>     access_request_id?: string | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     fields?: Record<string, {
>       type?: string | null
>     }> | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | null,
>   type?: string | null,
>   updated_at?: string | null,
>   version?: number | null
> }
> ```

***

### items.list

`vaults.items.list`

List a vault's items (no secret values).

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.vaults.items.list({ id_or_name: 'my-vault' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id_or_name` | `string` | Yes | — |

**Output:** `object[]`

> [accordion] Output full type
>
> ```ts theme={null}
> (
>   {
>     action?: {
>       name?: string | null,
>       url?: string | null
>     } | {
>       name?: string | null,
>       url?: string | null
>     } | {
>       connect_url?: string | null,
>       name?: string | null,
>       url?: string | null
>     } | {
>       name?: string | null,
>       url?: string | null
>     } | {
>       name?: string | null
>     } | {
>       name?: string | null
>     } | {
>       name?: string | null
>     } | {
>       name?: string | null
>     } | {
>       capture_token?: string | null,
>       name?: string | null,
>       url?: string | null
>     } | null,
>     available_expansions?: {
>       description?: string | null,
>       type?: string | null
>     }[] | null,
>     available_operations?: {
>       description?: string | null,
>       type?: string | null
>     }[] | null,
>     created_at?: string | null,
>     description?: string | null,
>     expanded?: {
>       link_shipping_addresses?: {
>         address?: {
>           administrative_area?: string | null | null,
>           country_code?: string | null | null,
>           dependent_locality?: string | null | null,
>           line_1?: string | null | null,
>           line_2?: string | null | null,
>           locality?: string | null | null,
>           name?: string | null | null,
>           postal_code?: string | null | null,
>           sorting_code?: string | null | null
>         } | null,
>         id?: string | null,
>         is_default?: boolean | null,
>         nickname?: string | null | null
>       }[] | null,
>       link_user_info?: {
>         address?: {
>           city?: string | null | null,
>           country?: string | null | null,
>           line1?: string | null | null,
>           line2?: string | null | null,
>           postal_code?: string | null | null,
>           state?: string | null | null
>         } | null,
>         agent_wallet_spend_limits?: {
>           daily?: {
>             limit?: number | null | null,
>             remaining?: number | null | null,
>             used?: number | null
>           } | null,
>           per_transaction?: {
>             limit?: number | null | null
>           } | null,
>           thirty_day?: {
>             limit?: number | null | null,
>             remaining?: number | null | null,
>             used?: number | null
>           } | null
>         } | null,
>         agent_wallet_step_up?: {
>           action_url?: string | null | null,
>           status?: string | null
>         } | null,
>         default_spend_request_currency?: string | null,
>         eligible_for_balance?: boolean | null,
>         email?: string | null | null,
>         first_name?: string | null | null,
>         id?: string | null | null,
>         last_name?: string | null | null,
>         name?: string | null | null,
>         phone?: string | null | null
>       } | null,
>       payment_methods?: {
>         action?: {
>           capture_token?: string | null,
>           name?: string | null,
>           url?: string | null
>         } | null,
>         capabilities?: {
>           single_use_card?: {
>             eligible?: boolean | null,
>             reasons?: string[] | null
>           } | null
>         } | null,
>         display?: {
>           brand?: string | null,
>           label?: string | null,
>           last4?: string | null
>         } | null,
>         expires_at?: string | null,
>         id?: string | null,
>         is_default?: boolean | null,
>         issuer_reference?: string | null,
>         provider?: string | null,
>         status?: string | null,
>         status_reason?: string | null,
>         type?: string | null,
>         valid_until?: string | null
>       }[] | null
>     } | null,
>     expires_at?: string | null,
>     id?: string | null,
>     key?: string | null,
>     spec?: {
>       authorization?: {
>         client?: {
>           type?: string | null
>         } | {
>           provider_config?: {
>             id?: string | null,
>             name?: string | null
>           } | null,
>           type?: string | null
>         } | null,
>         method?: string | null,
>         token_refresh?: string | null
>       } | null,
>       provider?: string | null
>     } | {
>       provider?: string | null,
>       provider_config?: {
>         id?: string | null,
>         name?: string | null
>       } | null,
>       user_id?: string | null
>     } | {
>       provider?: string | null
>     } | {
>       authorization?: {
>         client?: {
>           type?: string | null
>         } | null,
>         method?: string | null
>       } | null,
>       provider?: string | null
>     } | {
>       provider?: string | null,
>       provider_config?: {
>         id?: string | null,
>         name?: string | null
>       } | null
>     } | null,
>     state?: {
>       provider?: string | null,
>       status?: string | null,
>       status_reason?: string | null
>     } | {
>       provider?: string | null,
>       status?: string | null,
>       status_reason?: string | null,
>       user_id?: string | null
>     } | {
>       provider?: string | null,
>       status?: string | null,
>       status_reason?: string | null
>     } | {
>       provider?: string | null,
>       status?: string | null,
>       status_reason?: string | null
>     } | {
>       provider?: string | null,
>       status?: string | null,
>       status_reason?: string | null
>     } | null,
>     type?: string | null,
>     updated_at?: string | null
>   } | {
>     action?: {
>       name?: string | null,
>       url?: string | null
>     } | {
>       name?: string | null,
>       url?: string | null
>     } | {
>       connect_url?: string | null,
>       name?: string | null,
>       url?: string | null
>     } | {
>       name?: string | null,
>       url?: string | null
>     } | {
>       name?: string | null
>     } | {
>       name?: string | null
>     } | {
>       name?: string | null
>     } | {
>       name?: string | null
>     } | {
>       capture_token?: string | null,
>       name?: string | null,
>       url?: string | null
>     } | null,
>     available_expansions?: {
>       description?: string | null,
>       type?: string | null
>     }[] | null,
>     available_operations?: {
>       description?: string | null,
>       type?: string | null
>     }[] | null,
>     created_at?: string | null,
>     expires_at?: string | null,
>     id?: string | null,
>     key?: string | null,
>     spec?: {
>       amount?: number | null,
>       context?: string | null,
>       currency?: string | null,
>       line_items?: {
>         description?: string | null,
>         image_url?: string | null,
>         name?: string | null,
>         product_url?: string | null,
>         quantity?: number | null,
>         sku?: string | null,
>         totals?: {
>           amount?: number | null,
>           display_text?: string | null,
>           type?: string | null
>         }[] | null,
>         unit_amount?: number | null,
>         url?: string | null
>       }[] | null,
>       merchant_name?: string | null,
>       merchant_url?: string | null,
>       metadata?: Record<string, string> | null,
>       payment_method_id?: string | null,
>       provider?: string | null,
>       recurring?: {
>         interval?: string | null,
>         interval_count?: number | null
>       } | null,
>       totals?: {
>         amount?: number | null,
>         display_text?: string | null,
>         type?: string | null
>       }[] | null,
>       wallet?: string | null
>     } | {
>       amount?: number | null,
>       card_id?: string | null,
>       checkout_origin?: string | null,
>       currency?: string | null,
>       discount?: number | null,
>       line_items?: {
>         amount?: number | null,
>         brand?: string | null,
>         image_url?: string | null,
>         options?: string | null,
>         quantity?: number | null,
>         title?: string | null,
>         unit_amount?: number | null
>       }[] | null,
>       merchant?: string | null,
>       provider?: string | null,
>       shipping?: number | null,
>       subtotal?: number | null,
>       tax?: number | null,
>       wallet?: string | null
>     } | {
>       amount?: number | null,
>       currency?: string | null,
>       expires_at?: string | null,
>       merchant_category?: string | null,
>       merchant_category_code?: string | null,
>       merchant_country?: string | null,
>       merchant_name?: string | null,
>       merchant_url?: string | null,
>       payment_method_id?: string | null,
>       provider?: string | null,
>       single_use_card?: {
>         billing_address?: {
>           city?: string | null,
>           country?: string | null,
>           line1?: string | null,
>           line2?: string | null,
>           postal_code?: string | null,
>           state?: string | null
>         } | null,
>         cvc?: string | null,
>         exp_month?: string | null,
>         exp_year?: string | null,
>         name?: string | null,
>         number?: string | null,
>         reference?: string | null
>       } | null,
>       wallet?: string | null
>     } | {
>       amount?: number | null,
>       context?: string | null,
>       currency?: string | null,
>       line_items?: {
>         name?: string | null,
>         quantity?: number | null,
>         unit_amount?: number | null
>       }[] | null,
>       merchant_country?: string | null,
>       merchant_name?: string | null,
>       merchant_url?: string | null,
>       payment_method_id?: string | null,
>       provider?: string | null,
>       totals?: {
>         amount?: number | null,
>         type?: string | null
>       }[] | null,
>       wallet?: string | null
>     } | {
>       amount?: number | null,
>       card?: {
>         cvc_alias?: string | null,
>         exp_month?: number | null,
>         exp_year?: number | null,
>         last4?: string | null,
>         pan_alias?: string | null
>       } | null,
>       card_mode?: string | null,
>       currency?: string | null,
>       merchant_name?: string | null,
>       merchant_url?: string | null,
>       provider?: string | null,
>       wallet?: string | null
>     } | null,
>     state?: {
>       credential_type?: string | null,
>       domains?: string[] | null,
>       masks?: {
>         brand?: string | null,
>         last4?: string | null,
>         token_last4?: string | null
>       } | null,
>       provider?: string | null,
>       status?: string | null,
>       status_reason?: string | null
>     } | {
>       aliases?: {
>         cvc?: string | null,
>         exp_month?: string | null,
>         exp_year?: string | null,
>         number?: string | null
>       } | null,
>       authorization?: {
>         actual_cents?: number | null,
>         amount?: string | null,
>         amount_authority?: string | null,
>         amount_cents?: number | null,
>         amount_verified?: boolean | null,
>         approval_url?: string | null,
>         browser_id?: string | null,
>         charged_amount_cents?: number | null,
>         charged_currency?: string | null,
>         charged_kind?: string | null,
>         created_at?: string | null,
>         currency?: string | null,
>         expected_cents?: number | null,
>         expires_at?: string | null,
>         id?: string | null,
>         merchant?: string | null,
>         psp?: string | null,
>         psp_error_code?: string | null,
>         reason?: string | null,
>         replay_attempted?: boolean | null,
>         replay_delivered?: boolean | null,
>         replay_status?: number | null,
>         status?: string | null
>       } | null,
>       masks?: {
>         brand?: string | null,
>         last4?: string | null,
>         token_last4?: string | null
>       } | null,
>       preparation?: {
>         approval_url?: string | null,
>         browser_id?: string | null,
>         created_at?: string | null,
>         environment?: string | null,
>         expires_at?: string | null,
>         id?: string | null,
>         merchant_origin?: string | null,
>         psp?: string | null,
>         status?: string | null
>       } | null,
>       provider?: string | null,
>       status?: string | null,
>       status_reason?: string | null
>     } | {
>       domains?: string[] | null,
>       funding_status?: string | null,
>       masks?: {
>         brand?: string | null,
>         last4?: string | null,
>         token_last4?: string | null
>       } | null,
>       payment_method_id?: string | null,
>       provider?: string | null,
>       source?: string | null,
>       status?: string | null,
>       status_reason?: string | null
>     } | {
>       domains?: string[] | null,
>       masks?: {
>         brand?: string | null,
>         last4?: string | null,
>         token_last4?: string | null
>       } | null,
>       provider?: string | null,
>       status?: string | null,
>       status_reason?: string | null
>     } | {
>       domains?: string[] | null,
>       masks?: {
>         brand?: string | null,
>         last4?: string | null,
>         token_last4?: string | null
>       } | null,
>       provider?: string | null,
>       status?: string | null,
>       status_reason?: string | null
>     } | null,
>     type?: string | null,
>     updated_at?: string | null
>   } | {
>     action?: {
>       name?: string | null,
>       url?: string | null
>     } | {
>       name?: string | null,
>       url?: string | null
>     } | {
>       connect_url?: string | null,
>       name?: string | null,
>       url?: string | null
>     } | {
>       name?: string | null,
>       url?: string | null
>     } | {
>       name?: string | null
>     } | {
>       name?: string | null
>     } | {
>       name?: string | null
>     } | {
>       name?: string | null
>     } | {
>       capture_token?: string | null,
>       name?: string | null,
>       url?: string | null
>     } | null,
>     available_expansions?: {
>       description?: string | null,
>       type?: string | null
>     }[] | null,
>     available_operations?: {
>       description?: string | null,
>       type?: string | null
>     }[] | null,
>     created_at?: string | null,
>     expires_at?: string | null,
>     id?: string | null,
>     key?: string | null,
>     spec?: {
>       amount?: number | null,
>       context?: string | null,
>       currency?: string | null,
>       line_items?: {
>         description?: string | null,
>         image_url?: string | null,
>         name?: string | null,
>         product_url?: string | null,
>         quantity?: number | null,
>         sku?: string | null,
>         totals?: {
>           amount?: number | null,
>           display_text?: string | null,
>           type?: string | null
>         }[] | null,
>         unit_amount?: number | null,
>         url?: string | null
>       }[] | null,
>       merchant_name?: string | null,
>       merchant_url?: string | null,
>       metadata?: Record<string, string> | null,
>       payment_method_id?: string | null,
>       provider?: string | null,
>       recurring?: {
>         interval?: string | null,
>         interval_count?: number | null
>       } | null,
>       totals?: {
>         amount?: number | null,
>         display_text?: string | null,
>         type?: string | null
>       }[] | null,
>       wallet?: string | null
>     } | {
>       amount?: number | null,
>       currency?: string | null,
>       merchant_category?: string | null,
>       merchant_category_code?: string | null,
>       merchant_country?: string | null,
>       merchant_name?: string | null,
>       merchant_url?: string | null,
>       payment_method_id?: string | null,
>       provider?: string | null,
>       wallet?: string | null
>     } | null,
>     state?: {
>       credential_type?: string | null,
>       domains?: string[] | null,
>       masks?: {
>         brand?: string | null,
>         last4?: string | null,
>         token_last4?: string | null
>       } | null,
>       provider?: string | null,
>       status?: string | null,
>       status_reason?: string | null
>     } | {
>       domains?: string[] | null,
>       funding_status?: string | null,
>       masks?: {
>         brand?: string | null,
>         last4?: string | null,
>         token_last4?: string | null
>       } | null,
>       payment_method_id?: string | null,
>       provider?: string | null,
>       source?: string | null,
>       status?: string | null,
>       status_reason?: string | null
>     } | null,
>     type?: string | null,
>     updated_at?: string | null
>   } | {
>     action?: {
>       connect_url?: string | null,
>       name?: string | null,
>       url?: string | null
>     } | null,
>     available_expansions?: {
>       description?: string | null,
>       type?: string | null
>     }[] | null,
>     available_operations?: {
>       description?: string | null,
>       type?: string | null
>     }[] | null,
>     created_at?: string | null,
>     expires_at?: string | null,
>     id?: string | null,
>     key?: string | null,
>     spec?: {
>       authorization?: {
>         client?: {
>           type?: string | null
>         } | null,
>         method?: string | null
>       } | null,
>       provider?: string | null
>     } | null,
>     state?: {
>       provider?: string | null,
>       status?: string | null,
>       status_reason?: string | null
>     } | null,
>     type?: string | null,
>     updated_at?: string | null
>   } | {
>     action?: {
>       expires_at?: string | null,
>       name?: string | null,
>       url?: string | null
>     } | {
>       access_request_reference?: string | null,
>       instructions?: string | null,
>       name?: string | null,
>       url?: string | null
>     } | null,
>     available_expansions?: {
>       description?: string | null,
>       type?: string | null
>     }[] | null,
>     available_operations?: {
>       description?: string | null,
>       type?: string | null
>     }[] | null,
>     created_at?: string | null,
>     id?: string | null,
>     key?: string | null,
>     spec?: {
>       description?: string | null,
>       fields?: {
>         label?: string | null,
>         name?: string | null,
>         required?: boolean | null,
>         sensitive?: boolean | null,
>         type?: string | null
>       }[] | null,
>       provider?: string | null
>     } | {
>       access_token_expires_at?: string | null,
>       account?: string | null,
>       provider?: string | null,
>       requests?: {
>         entries?: {
>           id?: string | null,
>           keywords?: string[] | null,
>           parameters?: {
>             website?: string | null
>           } | null,
>           reason?: string | null,
>           type?: string | null
>         }[] | null,
>         goal?: string | null,
>         version?: number | null
>       } | null
>     } | {
>       connection_id?: string | null,
>       description?: string | null,
>       provider?: string | null
>     } | null,
>     state?: {
>       fields?: Record<string, {
>         has_value?: boolean | null,
>         value?: string | null
>       }> | null,
>       provider?: string | null,
>       status?: string | null
>     } | {
>       access_request?: {
>         createdAt?: string | null,
>         entries?: {
>           id?: string | null,
>           keywords?: string[] | null,
>           parameters?: {
>             website?: string | null
>           } | null,
>           reason?: string | null,
>           type?: string | null
>         }[] | null,
>         goal?: string | null,
>         granted_count?: number | null,
>         has_autofill_token?: boolean | null,
>         id?: string | null,
>         identity?: string | null,
>         path?: string | null,
>         request?: {
>           entries?: {
>             id?: string | null,
>             keywords?: string[] | null,
>             parameters?: {
>               website?: string | null
>             } | null,
>             reason?: string | null,
>             type?: string | null
>           }[] | null,
>           goal?: string | null,
>           version?: number | null
>         } | null,
>         resolved?: {
>           entryId?: string | null,
>           reference?: string | null
>         }[] | null,
>         state?: string | null
>       } | null,
>       access_request_id?: string | null,
>       provider?: string | null,
>       status?: string | null,
>       status_reason?: string | null
>     } | {
>       fields?: Record<string, {
>         type?: string | null
>       }> | null,
>       provider?: string | null,
>       status?: string | null,
>       status_reason?: string | null
>     } | null,
>     type?: string | null,
>     updated_at?: string | null,
>     version?: number | null
>   }
> )[]
> ```

***

### items.performOperation

`vaults.items.performOperation`

Run an operation a vault item offers, such as fill, authorize, confirm\_transaction or add\_payment\_method. Some move money or use a card: confirm with the person first.

**Risk:** `destructive` · **Irreversible**

```ts theme={null}
await corsair.kernel.api.vaults.items.performOperation({ id_or_name: 'my-vault', key: 'my-item', type: 'authorize' });
```

**Input:** `object`

> [accordion] Input full type
>
> ```ts theme={null}
> {
>   id_or_name: string,
>   key: string
> }& (
>   {
>     browser_id?: string,
>     page_url?: string,
>     type: authorize
>   } | {
>     type: restart_verification
>   } | {
>     amount: number,
>     currency: string,
>     failure_code?: string,
>     occurred_at: string,
>     order_id?: string,
>     order_url?: string,
>     status: APPROVED | DECLINED | PENDING | ERROR | CANCELLED,
>     transaction_type: PURCHASE | AUTHORIZATION | CAPTURE | REFUND | REVERSAL | VERIFICATION | CHARGEBACK | FRAUD,
>     type: confirm_transaction
>   } | {
>     type: collect
>   } | {
>     checkout: {
>       browser_id: string,
>       environment: production | sandbox | shared,
>       merchant_origin: string,
>       psp?: square | braintree | worldpay | bambora | mercado_pago | adyen
>     },
>     type: prepare_checkout
>   } | {
>     browser_id: string,
>     fields?: {
>       field: string,
>       format?: MM/YY | MM/YYYY,
>       selector: string
>     }[],
>     page_url?: string,
>     timeout_ms?: number,
>     type: fill
>   } | {
>     browser_id: string,
>     field?: string,
>     type: arm_passkey
>   } | {
>     browser_id: string,
>     field?: string,
>     type: register_passkey
>   } | {
>     browser_id: string,
>     field?: string,
>     type: disarm_passkey
>   } | {
>     goal?: string,
>     keywords?: string[],
>     reason?: string,
>     type: 1pw_create_access_request
>   } | {
>     timeout_seconds?: number,
>     type: 1pw_access_request_status
>   } | {
>     browser_id: string,
>     entry_id?: string,
>     page_url: string,
>     target_id?: string,
>     timeout_ms?: number,
>     type: 1pw_fill
>   } | {
>     type: 1pw_recover
>   } | {
>     type: 1pw_disconnect
>   } | {
>     access_token: string,
>     access_token_expires_at?: string,
>     type: 1pw_update_access_token
>   } | {
>     access_token: string,
>     type: update_access_token
>   } | {
>     bindings: {
>       field: string,
>       format?: string,
>       input_path: string
>     }[],
>     browser_id: string,
>     input: {
>     },
>     page_url: string,
>     timeout_sec?: number,
>     tool_ref: string,
>     type: webmcp_invoke
>   } | {
>     enrollment?: hosted | server,
>     type: add_payment_method
>   } | {
>     payment_method_id: string,
>     type: remove_payment_method
>   }
> )
> ```

**Output:** `object`

> [accordion] Output full type
>
> ```ts theme={null}
> {
>   action?: {
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null,
>     url?: string | null
>   } | {
>     connect_url?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     capture_token?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | null,
>   available_expansions?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   available_operations?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   created_at?: string | null,
>   description?: string | null,
>   expanded?: {
>     link_shipping_addresses?: {
>       address?: {
>         administrative_area?: string | null | null,
>         country_code?: string | null | null,
>         dependent_locality?: string | null | null,
>         line_1?: string | null | null,
>         line_2?: string | null | null,
>         locality?: string | null | null,
>         name?: string | null | null,
>         postal_code?: string | null | null,
>         sorting_code?: string | null | null
>       } | null,
>       id?: string | null,
>       is_default?: boolean | null,
>       nickname?: string | null | null
>     }[] | null,
>     link_user_info?: {
>       address?: {
>         city?: string | null | null,
>         country?: string | null | null,
>         line1?: string | null | null,
>         line2?: string | null | null,
>         postal_code?: string | null | null,
>         state?: string | null | null
>       } | null,
>       agent_wallet_spend_limits?: {
>         daily?: {
>           limit?: number | null | null,
>           remaining?: number | null | null,
>           used?: number | null
>         } | null,
>         per_transaction?: {
>           limit?: number | null | null
>         } | null,
>         thirty_day?: {
>           limit?: number | null | null,
>           remaining?: number | null | null,
>           used?: number | null
>         } | null
>       } | null,
>       agent_wallet_step_up?: {
>         action_url?: string | null | null,
>         status?: string | null
>       } | null,
>       default_spend_request_currency?: string | null,
>       eligible_for_balance?: boolean | null,
>       email?: string | null | null,
>       first_name?: string | null | null,
>       id?: string | null | null,
>       last_name?: string | null | null,
>       name?: string | null | null,
>       phone?: string | null | null
>     } | null,
>     payment_methods?: {
>       action?: {
>         capture_token?: string | null,
>         name?: string | null,
>         url?: string | null
>       } | null,
>       capabilities?: {
>         single_use_card?: {
>           eligible?: boolean | null,
>           reasons?: string[] | null
>         } | null
>       } | null,
>       display?: {
>         brand?: string | null,
>         label?: string | null,
>         last4?: string | null
>       } | null,
>       expires_at?: string | null,
>       id?: string | null,
>       is_default?: boolean | null,
>       issuer_reference?: string | null,
>       provider?: string | null,
>       status?: string | null,
>       status_reason?: string | null,
>       type?: string | null,
>       valid_until?: string | null
>     }[] | null
>   } | null,
>   expires_at?: string | null,
>   id?: string | null,
>   key?: string | null,
>   spec?: {
>     authorization?: {
>       client?: {
>         type?: string | null
>       } | {
>         provider_config?: {
>           id?: string | null,
>           name?: string | null
>         } | null,
>         type?: string | null
>       } | null,
>       method?: string | null,
>       token_refresh?: string | null
>     } | null,
>     provider?: string | null
>   } | {
>     provider?: string | null,
>     provider_config?: {
>       id?: string | null,
>       name?: string | null
>     } | null,
>     user_id?: string | null
>   } | {
>     provider?: string | null
>   } | {
>     authorization?: {
>       client?: {
>         type?: string | null
>       } | null,
>       method?: string | null
>     } | null,
>     provider?: string | null
>   } | {
>     provider?: string | null,
>     provider_config?: {
>       id?: string | null,
>       name?: string | null
>     } | null
>   } | null,
>   state?: {
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null,
>     user_id?: string | null
>   } | {
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | null,
>   type?: string | null,
>   updated_at?: string | null
> } | {
>   action?: {
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null,
>     url?: string | null
>   } | {
>     connect_url?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     capture_token?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | null,
>   available_expansions?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   available_operations?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   created_at?: string | null,
>   expires_at?: string | null,
>   id?: string | null,
>   key?: string | null,
>   spec?: {
>     amount?: number | null,
>     context?: string | null,
>     currency?: string | null,
>     line_items?: {
>       description?: string | null,
>       image_url?: string | null,
>       name?: string | null,
>       product_url?: string | null,
>       quantity?: number | null,
>       sku?: string | null,
>       totals?: {
>         amount?: number | null,
>         display_text?: string | null,
>         type?: string | null
>       }[] | null,
>       unit_amount?: number | null,
>       url?: string | null
>     }[] | null,
>     merchant_name?: string | null,
>     merchant_url?: string | null,
>     metadata?: Record<string, string> | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     recurring?: {
>       interval?: string | null,
>       interval_count?: number | null
>     } | null,
>     totals?: {
>       amount?: number | null,
>       display_text?: string | null,
>       type?: string | null
>     }[] | null,
>     wallet?: string | null
>   } | {
>     amount?: number | null,
>     card_id?: string | null,
>     checkout_origin?: string | null,
>     currency?: string | null,
>     discount?: number | null,
>     line_items?: {
>       amount?: number | null,
>       brand?: string | null,
>       image_url?: string | null,
>       options?: string | null,
>       quantity?: number | null,
>       title?: string | null,
>       unit_amount?: number | null
>     }[] | null,
>     merchant?: string | null,
>     provider?: string | null,
>     shipping?: number | null,
>     subtotal?: number | null,
>     tax?: number | null,
>     wallet?: string | null
>   } | {
>     amount?: number | null,
>     currency?: string | null,
>     expires_at?: string | null,
>     merchant_category?: string | null,
>     merchant_category_code?: string | null,
>     merchant_country?: string | null,
>     merchant_name?: string | null,
>     merchant_url?: string | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     single_use_card?: {
>       billing_address?: {
>         city?: string | null,
>         country?: string | null,
>         line1?: string | null,
>         line2?: string | null,
>         postal_code?: string | null,
>         state?: string | null
>       } | null,
>       cvc?: string | null,
>       exp_month?: string | null,
>       exp_year?: string | null,
>       name?: string | null,
>       number?: string | null,
>       reference?: string | null
>     } | null,
>     wallet?: string | null
>   } | {
>     amount?: number | null,
>     context?: string | null,
>     currency?: string | null,
>     line_items?: {
>       name?: string | null,
>       quantity?: number | null,
>       unit_amount?: number | null
>     }[] | null,
>     merchant_country?: string | null,
>     merchant_name?: string | null,
>     merchant_url?: string | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     totals?: {
>       amount?: number | null,
>       type?: string | null
>     }[] | null,
>     wallet?: string | null
>   } | {
>     amount?: number | null,
>     card?: {
>       cvc_alias?: string | null,
>       exp_month?: number | null,
>       exp_year?: number | null,
>       last4?: string | null,
>       pan_alias?: string | null
>     } | null,
>     card_mode?: string | null,
>     currency?: string | null,
>     merchant_name?: string | null,
>     merchant_url?: string | null,
>     provider?: string | null,
>     wallet?: string | null
>   } | null,
>   state?: {
>     credential_type?: string | null,
>     domains?: string[] | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     aliases?: {
>       cvc?: string | null,
>       exp_month?: string | null,
>       exp_year?: string | null,
>       number?: string | null
>     } | null,
>     authorization?: {
>       actual_cents?: number | null,
>       amount?: string | null,
>       amount_authority?: string | null,
>       amount_cents?: number | null,
>       amount_verified?: boolean | null,
>       approval_url?: string | null,
>       browser_id?: string | null,
>       charged_amount_cents?: number | null,
>       charged_currency?: string | null,
>       charged_kind?: string | null,
>       created_at?: string | null,
>       currency?: string | null,
>       expected_cents?: number | null,
>       expires_at?: string | null,
>       id?: string | null,
>       merchant?: string | null,
>       psp?: string | null,
>       psp_error_code?: string | null,
>       reason?: string | null,
>       replay_attempted?: boolean | null,
>       replay_delivered?: boolean | null,
>       replay_status?: number | null,
>       status?: string | null
>     } | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     preparation?: {
>       approval_url?: string | null,
>       browser_id?: string | null,
>       created_at?: string | null,
>       environment?: string | null,
>       expires_at?: string | null,
>       id?: string | null,
>       merchant_origin?: string | null,
>       psp?: string | null,
>       status?: string | null
>     } | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     domains?: string[] | null,
>     funding_status?: string | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     source?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     domains?: string[] | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     domains?: string[] | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | null,
>   type?: string | null,
>   updated_at?: string | null
> } | {
>   action?: {
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null,
>     url?: string | null
>   } | {
>     connect_url?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     capture_token?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | null,
>   available_expansions?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   available_operations?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   created_at?: string | null,
>   expires_at?: string | null,
>   id?: string | null,
>   key?: string | null,
>   spec?: {
>     amount?: number | null,
>     context?: string | null,
>     currency?: string | null,
>     line_items?: {
>       description?: string | null,
>       image_url?: string | null,
>       name?: string | null,
>       product_url?: string | null,
>       quantity?: number | null,
>       sku?: string | null,
>       totals?: {
>         amount?: number | null,
>         display_text?: string | null,
>         type?: string | null
>       }[] | null,
>       unit_amount?: number | null,
>       url?: string | null
>     }[] | null,
>     merchant_name?: string | null,
>     merchant_url?: string | null,
>     metadata?: Record<string, string> | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     recurring?: {
>       interval?: string | null,
>       interval_count?: number | null
>     } | null,
>     totals?: {
>       amount?: number | null,
>       display_text?: string | null,
>       type?: string | null
>     }[] | null,
>     wallet?: string | null
>   } | {
>     amount?: number | null,
>     currency?: string | null,
>     merchant_category?: string | null,
>     merchant_category_code?: string | null,
>     merchant_country?: string | null,
>     merchant_name?: string | null,
>     merchant_url?: string | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     wallet?: string | null
>   } | null,
>   state?: {
>     credential_type?: string | null,
>     domains?: string[] | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     domains?: string[] | null,
>     funding_status?: string | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     source?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | null,
>   type?: string | null,
>   updated_at?: string | null
> } | {
>   action?: {
>     connect_url?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | null,
>   available_expansions?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   available_operations?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   created_at?: string | null,
>   expires_at?: string | null,
>   id?: string | null,
>   key?: string | null,
>   spec?: {
>     authorization?: {
>       client?: {
>         type?: string | null
>       } | null,
>       method?: string | null
>     } | null,
>     provider?: string | null
>   } | null,
>   state?: {
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | null,
>   type?: string | null,
>   updated_at?: string | null
> } | {
>   action?: {
>     expires_at?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | {
>     access_request_reference?: string | null,
>     instructions?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | null,
>   available_expansions?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   available_operations?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   created_at?: string | null,
>   id?: string | null,
>   key?: string | null,
>   spec?: {
>     description?: string | null,
>     fields?: {
>       label?: string | null,
>       name?: string | null,
>       required?: boolean | null,
>       sensitive?: boolean | null,
>       type?: string | null
>     }[] | null,
>     provider?: string | null
>   } | {
>     access_token_expires_at?: string | null,
>     account?: string | null,
>     provider?: string | null,
>     requests?: {
>       entries?: {
>         id?: string | null,
>         keywords?: string[] | null,
>         parameters?: {
>           website?: string | null
>         } | null,
>         reason?: string | null,
>         type?: string | null
>       }[] | null,
>       goal?: string | null,
>       version?: number | null
>     } | null
>   } | {
>     connection_id?: string | null,
>     description?: string | null,
>     provider?: string | null
>   } | null,
>   state?: {
>     fields?: Record<string, {
>       has_value?: boolean | null,
>       value?: string | null
>     }> | null,
>     provider?: string | null,
>     status?: string | null
>   } | {
>     access_request?: {
>       createdAt?: string | null,
>       entries?: {
>         id?: string | null,
>         keywords?: string[] | null,
>         parameters?: {
>           website?: string | null
>         } | null,
>         reason?: string | null,
>         type?: string | null
>       }[] | null,
>       goal?: string | null,
>       granted_count?: number | null,
>       has_autofill_token?: boolean | null,
>       id?: string | null,
>       identity?: string | null,
>       path?: string | null,
>       request?: {
>         entries?: {
>           id?: string | null,
>           keywords?: string[] | null,
>           parameters?: {
>             website?: string | null
>           } | null,
>           reason?: string | null,
>           type?: string | null
>         }[] | null,
>         goal?: string | null,
>         version?: number | null
>       } | null,
>       resolved?: {
>         entryId?: string | null,
>         reference?: string | null
>       }[] | null,
>       state?: string | null
>     } | null,
>     access_request_id?: string | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     fields?: Record<string, {
>       type?: string | null
>     }> | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | null,
>   type?: string | null,
>   updated_at?: string | null,
>   version?: number | null
> } | {
>   fields?: {
>     error_code?: string | null,
>     index?: number | null,
>     status?: string | null
>   }[] | null,
>   status?: string | null,
>   type?: string | null
> } | {
>   rp_id?: string | null,
>   status?: string | null,
>   type?: string | null
> } | {
>   error_code?: string | null,
>   status?: string | null,
>   type?: string | null
> } | {
>   error_text?: string | null,
>   invocation_id?: string | null,
>   output?: any | null,
>   status?: string | null,
>   type?: string | null
> } | {
>   payment_method?: {
>     action?: {
>       capture_token?: string | null,
>       name?: string | null,
>       url?: string | null
>     } | null,
>     capabilities?: {
>       single_use_card?: {
>         eligible?: boolean | null,
>         reasons?: string[] | null
>       } | null
>     } | null,
>     display?: {
>       brand?: string | null,
>       label?: string | null,
>       last4?: string | null
>     } | null,
>     expires_at?: string | null,
>     id?: string | null,
>     is_default?: boolean | null,
>     issuer_reference?: string | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null,
>     type?: string | null,
>     valid_until?: string | null
>   } | null,
>   type?: string | null
> } | {
>   payment_method_id?: string | null,
>   status?: string | null,
>   type?: string | null
> }
> ```

***

### items.update

`vaults.items.update`

Update a vault item's card specification or credential values.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.vaults.items.update({
	id_or_name: 'my-vault',
	key: 'my-item',
	spec: {
		provider: 'link',
		wallet: 'example',
		payment_method_id: 'example',
		amount: 1,
		currency: 'exa',
		merchant_name: 'example',
		merchant_url: 'example',
		context: 'examplexxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx',
	},
});
```

**Input:** `object`

> [accordion] Input full type
>
> ```ts theme={null}
> {
>   id_or_name: string,
>   key: string
> }& (
>   {
>     spec: {
>       amount: number,
>       context: string,
>       currency: string,
>       line_items?: {
>         description?: string,
>         image_url?: string,
>         name: string,
>         product_url?: string,
>         quantity?: number,
>         sku?: string,
>         totals?: {
>           amount: number,
>           display_text: string,
>           type: string
>         }[],
>         unit_amount?: number,
>         url?: string
>       }[],
>       merchant_name: string,
>       merchant_url: string,
>       metadata?: Record<string, string>,
>       payment_method_id: string,
>       provider: link,
>       recurring?: {
>         interval: day | week | month | year,
>         interval_count?: number
>       },
>       totals?: {
>         amount: number,
>         display_text: string,
>         type: string
>       }[],
>       wallet: string
>     } | {
>       amount: number,
>       card_id?: string,
>       checkout_origin?: string,
>       currency: string,
>       discount?: number,
>       line_items?: {
>         amount?: number,
>         brand?: string,
>         image_url?: string,
>         options?: string,
>         quantity: number,
>         title: string,
>         unit_amount?: number
>       }[],
>       merchant: string,
>       provider: agentcard,
>       shipping?: number,
>       subtotal?: number,
>       tax?: number,
>       wallet: string
>     } | {
>       amount: number,
>       currency: string,
>       expires_at?: string,
>       merchant_category?: string,
>       merchant_category_code?: string,
>       merchant_country?: string,
>       merchant_name: string,
>       merchant_url: string,
>       payment_method_id?: string,
>       provider: kernel,
>       single_use_card?: {
>         billing_address?: {
>           city?: string,
>           country?: string,
>           line1?: string,
>           line2?: string,
>           postal_code?: string,
>           state?: string
>         },
>         cvc: string,
>         exp_month: string,
>         exp_year: string,
>         name?: string,
>         number: string,
>         reference?: string
>       },
>       wallet: string
>     } | {
>       amount: number,
>       context: string,
>       currency: string,
>       line_items?: {
>         name: string,
>         quantity: number,
>         unit_amount: number
>       }[],
>       merchant_country?: string,
>       merchant_name: string,
>       merchant_url: string,
>       payment_method_id?: string,
>       provider: shop_pay,
>       totals: {
>         amount: number,
>         type: string
>       }[],
>       wallet: string
>     } | {
>       amount: number,
>       card?: {
>         cvc_alias: string,
>         exp_month?: number,
>         exp_year?: number,
>         last4?: string,
>         pan_alias?: string
>       },
>       card_mode?: full | cvc_only,
>       currency: string,
>       merchant_name: string,
>       merchant_url: string,
>       provider: vgs,
>       wallet: string
>     },
>     type?: card
>   } | {
>     spec: {
>       amount: number,
>       context: string,
>       currency: string,
>       line_items?: {
>         description?: string,
>         image_url?: string,
>         name: string,
>         product_url?: string,
>         quantity?: number,
>         sku?: string,
>         totals?: {
>           amount: number,
>           display_text: string,
>           type: string
>         }[],
>         unit_amount?: number,
>         url?: string
>       }[],
>       merchant_name: string,
>       merchant_url: string,
>       metadata?: Record<string, string>,
>       payment_method_id: string,
>       provider: link,
>       recurring?: {
>         interval: day | week | month | year,
>         interval_count?: number
>       },
>       totals?: {
>         amount: number,
>         display_text: string,
>         type: string
>       }[],
>       wallet: string
>     } | {
>       amount: number,
>       currency: string,
>       merchant_category?: string,
>       merchant_category_code?: string,
>       merchant_country?: string,
>       merchant_name: string,
>       merchant_url: string,
>       payment_method_id: string,
>       provider: kernel,
>       wallet: string
>     },
>     type: payment_request
>   } | {
>     expected_item_id?: string,
>     spec: {
>       add_fields?: {
>         label?: string,
>         name: string,
>         required?: boolean,
>         sensitive?: boolean,
>         type: text | email | password | totp | passkey
>       }[],
>       description?: string,
>       fields?: Record<string, {
>         encrypted_value?: string,
>         value?: string | null
>       }>,
>       remove_fields?: string[]
>     },
>     type: credential,
>     version: number
>   }
> )
> ```

**Output:** `object`

> [accordion] Output full type
>
> ```ts theme={null}
> {
>   action?: {
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null,
>     url?: string | null
>   } | {
>     connect_url?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     capture_token?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | null,
>   available_expansions?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   available_operations?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   created_at?: string | null,
>   description?: string | null,
>   expanded?: {
>     link_shipping_addresses?: {
>       address?: {
>         administrative_area?: string | null | null,
>         country_code?: string | null | null,
>         dependent_locality?: string | null | null,
>         line_1?: string | null | null,
>         line_2?: string | null | null,
>         locality?: string | null | null,
>         name?: string | null | null,
>         postal_code?: string | null | null,
>         sorting_code?: string | null | null
>       } | null,
>       id?: string | null,
>       is_default?: boolean | null,
>       nickname?: string | null | null
>     }[] | null,
>     link_user_info?: {
>       address?: {
>         city?: string | null | null,
>         country?: string | null | null,
>         line1?: string | null | null,
>         line2?: string | null | null,
>         postal_code?: string | null | null,
>         state?: string | null | null
>       } | null,
>       agent_wallet_spend_limits?: {
>         daily?: {
>           limit?: number | null | null,
>           remaining?: number | null | null,
>           used?: number | null
>         } | null,
>         per_transaction?: {
>           limit?: number | null | null
>         } | null,
>         thirty_day?: {
>           limit?: number | null | null,
>           remaining?: number | null | null,
>           used?: number | null
>         } | null
>       } | null,
>       agent_wallet_step_up?: {
>         action_url?: string | null | null,
>         status?: string | null
>       } | null,
>       default_spend_request_currency?: string | null,
>       eligible_for_balance?: boolean | null,
>       email?: string | null | null,
>       first_name?: string | null | null,
>       id?: string | null | null,
>       last_name?: string | null | null,
>       name?: string | null | null,
>       phone?: string | null | null
>     } | null,
>     payment_methods?: {
>       action?: {
>         capture_token?: string | null,
>         name?: string | null,
>         url?: string | null
>       } | null,
>       capabilities?: {
>         single_use_card?: {
>           eligible?: boolean | null,
>           reasons?: string[] | null
>         } | null
>       } | null,
>       display?: {
>         brand?: string | null,
>         label?: string | null,
>         last4?: string | null
>       } | null,
>       expires_at?: string | null,
>       id?: string | null,
>       is_default?: boolean | null,
>       issuer_reference?: string | null,
>       provider?: string | null,
>       status?: string | null,
>       status_reason?: string | null,
>       type?: string | null,
>       valid_until?: string | null
>     }[] | null
>   } | null,
>   expires_at?: string | null,
>   id?: string | null,
>   key?: string | null,
>   spec?: {
>     authorization?: {
>       client?: {
>         type?: string | null
>       } | {
>         provider_config?: {
>           id?: string | null,
>           name?: string | null
>         } | null,
>         type?: string | null
>       } | null,
>       method?: string | null,
>       token_refresh?: string | null
>     } | null,
>     provider?: string | null
>   } | {
>     provider?: string | null,
>     provider_config?: {
>       id?: string | null,
>       name?: string | null
>     } | null,
>     user_id?: string | null
>   } | {
>     provider?: string | null
>   } | {
>     authorization?: {
>       client?: {
>         type?: string | null
>       } | null,
>       method?: string | null
>     } | null,
>     provider?: string | null
>   } | {
>     provider?: string | null,
>     provider_config?: {
>       id?: string | null,
>       name?: string | null
>     } | null
>   } | null,
>   state?: {
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null,
>     user_id?: string | null
>   } | {
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | null,
>   type?: string | null,
>   updated_at?: string | null
> } | {
>   action?: {
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null,
>     url?: string | null
>   } | {
>     connect_url?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     capture_token?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | null,
>   available_expansions?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   available_operations?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   created_at?: string | null,
>   expires_at?: string | null,
>   id?: string | null,
>   key?: string | null,
>   spec?: {
>     amount?: number | null,
>     context?: string | null,
>     currency?: string | null,
>     line_items?: {
>       description?: string | null,
>       image_url?: string | null,
>       name?: string | null,
>       product_url?: string | null,
>       quantity?: number | null,
>       sku?: string | null,
>       totals?: {
>         amount?: number | null,
>         display_text?: string | null,
>         type?: string | null
>       }[] | null,
>       unit_amount?: number | null,
>       url?: string | null
>     }[] | null,
>     merchant_name?: string | null,
>     merchant_url?: string | null,
>     metadata?: Record<string, string> | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     recurring?: {
>       interval?: string | null,
>       interval_count?: number | null
>     } | null,
>     totals?: {
>       amount?: number | null,
>       display_text?: string | null,
>       type?: string | null
>     }[] | null,
>     wallet?: string | null
>   } | {
>     amount?: number | null,
>     card_id?: string | null,
>     checkout_origin?: string | null,
>     currency?: string | null,
>     discount?: number | null,
>     line_items?: {
>       amount?: number | null,
>       brand?: string | null,
>       image_url?: string | null,
>       options?: string | null,
>       quantity?: number | null,
>       title?: string | null,
>       unit_amount?: number | null
>     }[] | null,
>     merchant?: string | null,
>     provider?: string | null,
>     shipping?: number | null,
>     subtotal?: number | null,
>     tax?: number | null,
>     wallet?: string | null
>   } | {
>     amount?: number | null,
>     currency?: string | null,
>     expires_at?: string | null,
>     merchant_category?: string | null,
>     merchant_category_code?: string | null,
>     merchant_country?: string | null,
>     merchant_name?: string | null,
>     merchant_url?: string | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     single_use_card?: {
>       billing_address?: {
>         city?: string | null,
>         country?: string | null,
>         line1?: string | null,
>         line2?: string | null,
>         postal_code?: string | null,
>         state?: string | null
>       } | null,
>       cvc?: string | null,
>       exp_month?: string | null,
>       exp_year?: string | null,
>       name?: string | null,
>       number?: string | null,
>       reference?: string | null
>     } | null,
>     wallet?: string | null
>   } | {
>     amount?: number | null,
>     context?: string | null,
>     currency?: string | null,
>     line_items?: {
>       name?: string | null,
>       quantity?: number | null,
>       unit_amount?: number | null
>     }[] | null,
>     merchant_country?: string | null,
>     merchant_name?: string | null,
>     merchant_url?: string | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     totals?: {
>       amount?: number | null,
>       type?: string | null
>     }[] | null,
>     wallet?: string | null
>   } | {
>     amount?: number | null,
>     card?: {
>       cvc_alias?: string | null,
>       exp_month?: number | null,
>       exp_year?: number | null,
>       last4?: string | null,
>       pan_alias?: string | null
>     } | null,
>     card_mode?: string | null,
>     currency?: string | null,
>     merchant_name?: string | null,
>     merchant_url?: string | null,
>     provider?: string | null,
>     wallet?: string | null
>   } | null,
>   state?: {
>     credential_type?: string | null,
>     domains?: string[] | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     aliases?: {
>       cvc?: string | null,
>       exp_month?: string | null,
>       exp_year?: string | null,
>       number?: string | null
>     } | null,
>     authorization?: {
>       actual_cents?: number | null,
>       amount?: string | null,
>       amount_authority?: string | null,
>       amount_cents?: number | null,
>       amount_verified?: boolean | null,
>       approval_url?: string | null,
>       browser_id?: string | null,
>       charged_amount_cents?: number | null,
>       charged_currency?: string | null,
>       charged_kind?: string | null,
>       created_at?: string | null,
>       currency?: string | null,
>       expected_cents?: number | null,
>       expires_at?: string | null,
>       id?: string | null,
>       merchant?: string | null,
>       psp?: string | null,
>       psp_error_code?: string | null,
>       reason?: string | null,
>       replay_attempted?: boolean | null,
>       replay_delivered?: boolean | null,
>       replay_status?: number | null,
>       status?: string | null
>     } | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     preparation?: {
>       approval_url?: string | null,
>       browser_id?: string | null,
>       created_at?: string | null,
>       environment?: string | null,
>       expires_at?: string | null,
>       id?: string | null,
>       merchant_origin?: string | null,
>       psp?: string | null,
>       status?: string | null
>     } | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     domains?: string[] | null,
>     funding_status?: string | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     source?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     domains?: string[] | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     domains?: string[] | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | null,
>   type?: string | null,
>   updated_at?: string | null
> } | {
>   action?: {
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null,
>     url?: string | null
>   } | {
>     connect_url?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     capture_token?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | null,
>   available_expansions?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   available_operations?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   created_at?: string | null,
>   expires_at?: string | null,
>   id?: string | null,
>   key?: string | null,
>   spec?: {
>     amount?: number | null,
>     context?: string | null,
>     currency?: string | null,
>     line_items?: {
>       description?: string | null,
>       image_url?: string | null,
>       name?: string | null,
>       product_url?: string | null,
>       quantity?: number | null,
>       sku?: string | null,
>       totals?: {
>         amount?: number | null,
>         display_text?: string | null,
>         type?: string | null
>       }[] | null,
>       unit_amount?: number | null,
>       url?: string | null
>     }[] | null,
>     merchant_name?: string | null,
>     merchant_url?: string | null,
>     metadata?: Record<string, string> | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     recurring?: {
>       interval?: string | null,
>       interval_count?: number | null
>     } | null,
>     totals?: {
>       amount?: number | null,
>       display_text?: string | null,
>       type?: string | null
>     }[] | null,
>     wallet?: string | null
>   } | {
>     amount?: number | null,
>     currency?: string | null,
>     merchant_category?: string | null,
>     merchant_category_code?: string | null,
>     merchant_country?: string | null,
>     merchant_name?: string | null,
>     merchant_url?: string | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     wallet?: string | null
>   } | null,
>   state?: {
>     credential_type?: string | null,
>     domains?: string[] | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     domains?: string[] | null,
>     funding_status?: string | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     source?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | null,
>   type?: string | null,
>   updated_at?: string | null
> } | {
>   action?: {
>     connect_url?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | null,
>   available_expansions?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   available_operations?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   created_at?: string | null,
>   expires_at?: string | null,
>   id?: string | null,
>   key?: string | null,
>   spec?: {
>     authorization?: {
>       client?: {
>         type?: string | null
>       } | null,
>       method?: string | null
>     } | null,
>     provider?: string | null
>   } | null,
>   state?: {
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | null,
>   type?: string | null,
>   updated_at?: string | null
> } | {
>   action?: {
>     expires_at?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | {
>     access_request_reference?: string | null,
>     instructions?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | null,
>   available_expansions?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   available_operations?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   created_at?: string | null,
>   id?: string | null,
>   key?: string | null,
>   spec?: {
>     description?: string | null,
>     fields?: {
>       label?: string | null,
>       name?: string | null,
>       required?: boolean | null,
>       sensitive?: boolean | null,
>       type?: string | null
>     }[] | null,
>     provider?: string | null
>   } | {
>     access_token_expires_at?: string | null,
>     account?: string | null,
>     provider?: string | null,
>     requests?: {
>       entries?: {
>         id?: string | null,
>         keywords?: string[] | null,
>         parameters?: {
>           website?: string | null
>         } | null,
>         reason?: string | null,
>         type?: string | null
>       }[] | null,
>       goal?: string | null,
>       version?: number | null
>     } | null
>   } | {
>     connection_id?: string | null,
>     description?: string | null,
>     provider?: string | null
>   } | null,
>   state?: {
>     fields?: Record<string, {
>       has_value?: boolean | null,
>       value?: string | null
>     }> | null,
>     provider?: string | null,
>     status?: string | null
>   } | {
>     access_request?: {
>       createdAt?: string | null,
>       entries?: {
>         id?: string | null,
>         keywords?: string[] | null,
>         parameters?: {
>           website?: string | null
>         } | null,
>         reason?: string | null,
>         type?: string | null
>       }[] | null,
>       goal?: string | null,
>       granted_count?: number | null,
>       has_autofill_token?: boolean | null,
>       id?: string | null,
>       identity?: string | null,
>       path?: string | null,
>       request?: {
>         entries?: {
>           id?: string | null,
>           keywords?: string[] | null,
>           parameters?: {
>             website?: string | null
>           } | null,
>           reason?: string | null,
>           type?: string | null
>         }[] | null,
>         goal?: string | null,
>         version?: number | null
>       } | null,
>       resolved?: {
>         entryId?: string | null,
>         reference?: string | null
>       }[] | null,
>       state?: string | null
>     } | null,
>     access_request_id?: string | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     fields?: Record<string, {
>       type?: string | null
>     }> | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | null,
>   type?: string | null,
>   updated_at?: string | null,
>   version?: number | null
> }
> ```

***

### items.upsert

`vaults.items.upsert`

Create a vault item (card, credential, wallet or payment request) under a key, or get the identical existing one.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.vaults.items.upsert({
	id_or_name: 'my-vault',
	key: 'team-wallet',
	type: 'wallet',
	spec: { provider: 'kernel' },
});
```

**Input:** `object`

> [accordion] Input full type
>
> ```ts theme={null}
> {
>   id_or_name: string,
>   key: string
> }& (
>   {
>     spec: {
>       authorization: {
>         client: {
>           type: kernel_managed
>         },
>         method: oauth
>       } | {
>         client: {
>           provider_config: {
>             id?: string,
>             name?: string
>           },
>           type: customer_managed
>         },
>         method: oauth,
>         token_refresh?: kernel | customer,
>         tokens: {
>           access_token: string,
>           refresh_token?: string
>         }
>       },
>       provider: link
>     } | {
>       provider: agentcard,
>       provider_config?: {
>         id?: string,
>         name?: string
>       },
>       user_id?: string
>     } | {
>       provider: kernel
>     } | {
>       authorization: {
>         client: {
>           type: kernel_managed
>         },
>         method: oauth
>       },
>       provider: shop_pay
>     } | {
>       provider: vgs,
>       provider_config: {
>         id?: string,
>         name?: string
>       }
>     },
>     type: wallet
>   } | {
>     spec: {
>       amount: number,
>       context: string,
>       currency: string,
>       line_items?: {
>         description?: string,
>         image_url?: string,
>         name: string,
>         product_url?: string,
>         quantity?: number,
>         sku?: string,
>         totals?: {
>           amount: number,
>           display_text: string,
>           type: string
>         }[],
>         unit_amount?: number,
>         url?: string
>       }[],
>       merchant_name: string,
>       merchant_url: string,
>       metadata?: Record<string, string>,
>       payment_method_id: string,
>       provider: link,
>       recurring?: {
>         interval: day | week | month | year,
>         interval_count?: number
>       },
>       totals?: {
>         amount: number,
>         display_text: string,
>         type: string
>       }[],
>       wallet: string
>     } | {
>       amount: number,
>       card_id?: string,
>       checkout_origin?: string,
>       currency: string,
>       discount?: number,
>       line_items?: {
>         amount?: number,
>         brand?: string,
>         image_url?: string,
>         options?: string,
>         quantity: number,
>         title: string,
>         unit_amount?: number
>       }[],
>       merchant: string,
>       provider: agentcard,
>       shipping?: number,
>       subtotal?: number,
>       tax?: number,
>       wallet: string
>     } | {
>       amount: number,
>       currency: string,
>       expires_at?: string,
>       merchant_category?: string,
>       merchant_category_code?: string,
>       merchant_country?: string,
>       merchant_name: string,
>       merchant_url: string,
>       payment_method_id?: string,
>       provider: kernel,
>       single_use_card?: {
>         billing_address?: {
>           city?: string,
>           country?: string,
>           line1?: string,
>           line2?: string,
>           postal_code?: string,
>           state?: string
>         },
>         cvc: string,
>         exp_month: string,
>         exp_year: string,
>         name?: string,
>         number: string,
>         reference?: string
>       },
>       wallet: string
>     } | {
>       amount: number,
>       context: string,
>       currency: string,
>       line_items?: {
>         name: string,
>         quantity: number,
>         unit_amount: number
>       }[],
>       merchant_country?: string,
>       merchant_name: string,
>       merchant_url: string,
>       payment_method_id?: string,
>       provider: shop_pay,
>       totals: {
>         amount: number,
>         type: string
>       }[],
>       wallet: string
>     } | {
>       amount: number,
>       card?: {
>         cvc_alias: string,
>         exp_month?: number,
>         exp_year?: number,
>         last4?: string,
>         pan_alias?: string
>       },
>       card_mode?: full | cvc_only,
>       currency: string,
>       merchant_name: string,
>       merchant_url: string,
>       provider: vgs,
>       wallet: string
>     },
>     type: card
>   } | {
>     spec: {
>       amount: number,
>       context: string,
>       currency: string,
>       line_items?: {
>         description?: string,
>         image_url?: string,
>         name: string,
>         product_url?: string,
>         quantity?: number,
>         sku?: string,
>         totals?: {
>           amount: number,
>           display_text: string,
>           type: string
>         }[],
>         unit_amount?: number,
>         url?: string
>       }[],
>       merchant_name: string,
>       merchant_url: string,
>       metadata?: Record<string, string>,
>       payment_method_id: string,
>       provider: link,
>       recurring?: {
>         interval: day | week | month | year,
>         interval_count?: number
>       },
>       totals?: {
>         amount: number,
>         display_text: string,
>         type: string
>       }[],
>       wallet: string
>     } | {
>       amount: number,
>       currency: string,
>       merchant_category?: string,
>       merchant_category_code?: string,
>       merchant_country?: string,
>       merchant_name: string,
>       merchant_url: string,
>       payment_method_id: string,
>       provider: kernel,
>       wallet: string
>     },
>     type: payment_request
>   } | {
>     spec: {
>       authorization: {
>         client: {
>           type: kernel_managed
>         },
>         method: oauth
>       },
>       provider: 1password
>     },
>     type: credential_account
>   } | {
>     spec: {
>       description?: string,
>       fields: {
>         encrypted_value?: string,
>         label?: string,
>         name: string,
>         required?: boolean,
>         sensitive?: boolean,
>         type: text | email | password | totp | passkey,
>         value?: string
>       }[],
>       provider: kernel
>     } | {
>       access_request_id?: string,
>       access_token?: string,
>       access_token_expires_at?: string,
>       account?: string,
>       integration_key?: string,
>       provider: 1password,
>       requests?: {
>         entries: {
>           id?: string,
>           keywords?: string[],
>           parameters: {
>             website: string
>           },
>           reason?: string,
>           type: string
>         }[],
>         goal?: string,
>         version: number
>       },
>       resolved?: {
>         entryId?: string,
>         reference: string
>       }[],
>       website?: string
>     } | {
>       connection_id: string,
>       description?: string,
>       provider: managed_auth
>     },
>     type: credential
>   }
> )
> ```

**Output:** `object`

> [accordion] Output full type
>
> ```ts theme={null}
> {
>   action?: {
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null,
>     url?: string | null
>   } | {
>     connect_url?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     capture_token?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | null,
>   available_expansions?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   available_operations?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   created_at?: string | null,
>   description?: string | null,
>   expanded?: {
>     link_shipping_addresses?: {
>       address?: {
>         administrative_area?: string | null | null,
>         country_code?: string | null | null,
>         dependent_locality?: string | null | null,
>         line_1?: string | null | null,
>         line_2?: string | null | null,
>         locality?: string | null | null,
>         name?: string | null | null,
>         postal_code?: string | null | null,
>         sorting_code?: string | null | null
>       } | null,
>       id?: string | null,
>       is_default?: boolean | null,
>       nickname?: string | null | null
>     }[] | null,
>     link_user_info?: {
>       address?: {
>         city?: string | null | null,
>         country?: string | null | null,
>         line1?: string | null | null,
>         line2?: string | null | null,
>         postal_code?: string | null | null,
>         state?: string | null | null
>       } | null,
>       agent_wallet_spend_limits?: {
>         daily?: {
>           limit?: number | null | null,
>           remaining?: number | null | null,
>           used?: number | null
>         } | null,
>         per_transaction?: {
>           limit?: number | null | null
>         } | null,
>         thirty_day?: {
>           limit?: number | null | null,
>           remaining?: number | null | null,
>           used?: number | null
>         } | null
>       } | null,
>       agent_wallet_step_up?: {
>         action_url?: string | null | null,
>         status?: string | null
>       } | null,
>       default_spend_request_currency?: string | null,
>       eligible_for_balance?: boolean | null,
>       email?: string | null | null,
>       first_name?: string | null | null,
>       id?: string | null | null,
>       last_name?: string | null | null,
>       name?: string | null | null,
>       phone?: string | null | null
>     } | null,
>     payment_methods?: {
>       action?: {
>         capture_token?: string | null,
>         name?: string | null,
>         url?: string | null
>       } | null,
>       capabilities?: {
>         single_use_card?: {
>           eligible?: boolean | null,
>           reasons?: string[] | null
>         } | null
>       } | null,
>       display?: {
>         brand?: string | null,
>         label?: string | null,
>         last4?: string | null
>       } | null,
>       expires_at?: string | null,
>       id?: string | null,
>       is_default?: boolean | null,
>       issuer_reference?: string | null,
>       provider?: string | null,
>       status?: string | null,
>       status_reason?: string | null,
>       type?: string | null,
>       valid_until?: string | null
>     }[] | null
>   } | null,
>   expires_at?: string | null,
>   id?: string | null,
>   key?: string | null,
>   spec?: {
>     authorization?: {
>       client?: {
>         type?: string | null
>       } | {
>         provider_config?: {
>           id?: string | null,
>           name?: string | null
>         } | null,
>         type?: string | null
>       } | null,
>       method?: string | null,
>       token_refresh?: string | null
>     } | null,
>     provider?: string | null
>   } | {
>     provider?: string | null,
>     provider_config?: {
>       id?: string | null,
>       name?: string | null
>     } | null,
>     user_id?: string | null
>   } | {
>     provider?: string | null
>   } | {
>     authorization?: {
>       client?: {
>         type?: string | null
>       } | null,
>       method?: string | null
>     } | null,
>     provider?: string | null
>   } | {
>     provider?: string | null,
>     provider_config?: {
>       id?: string | null,
>       name?: string | null
>     } | null
>   } | null,
>   state?: {
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null,
>     user_id?: string | null
>   } | {
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | null,
>   type?: string | null,
>   updated_at?: string | null
> } | {
>   action?: {
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null,
>     url?: string | null
>   } | {
>     connect_url?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     capture_token?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | null,
>   available_expansions?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   available_operations?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   created_at?: string | null,
>   expires_at?: string | null,
>   id?: string | null,
>   key?: string | null,
>   spec?: {
>     amount?: number | null,
>     context?: string | null,
>     currency?: string | null,
>     line_items?: {
>       description?: string | null,
>       image_url?: string | null,
>       name?: string | null,
>       product_url?: string | null,
>       quantity?: number | null,
>       sku?: string | null,
>       totals?: {
>         amount?: number | null,
>         display_text?: string | null,
>         type?: string | null
>       }[] | null,
>       unit_amount?: number | null,
>       url?: string | null
>     }[] | null,
>     merchant_name?: string | null,
>     merchant_url?: string | null,
>     metadata?: Record<string, string> | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     recurring?: {
>       interval?: string | null,
>       interval_count?: number | null
>     } | null,
>     totals?: {
>       amount?: number | null,
>       display_text?: string | null,
>       type?: string | null
>     }[] | null,
>     wallet?: string | null
>   } | {
>     amount?: number | null,
>     card_id?: string | null,
>     checkout_origin?: string | null,
>     currency?: string | null,
>     discount?: number | null,
>     line_items?: {
>       amount?: number | null,
>       brand?: string | null,
>       image_url?: string | null,
>       options?: string | null,
>       quantity?: number | null,
>       title?: string | null,
>       unit_amount?: number | null
>     }[] | null,
>     merchant?: string | null,
>     provider?: string | null,
>     shipping?: number | null,
>     subtotal?: number | null,
>     tax?: number | null,
>     wallet?: string | null
>   } | {
>     amount?: number | null,
>     currency?: string | null,
>     expires_at?: string | null,
>     merchant_category?: string | null,
>     merchant_category_code?: string | null,
>     merchant_country?: string | null,
>     merchant_name?: string | null,
>     merchant_url?: string | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     single_use_card?: {
>       billing_address?: {
>         city?: string | null,
>         country?: string | null,
>         line1?: string | null,
>         line2?: string | null,
>         postal_code?: string | null,
>         state?: string | null
>       } | null,
>       cvc?: string | null,
>       exp_month?: string | null,
>       exp_year?: string | null,
>       name?: string | null,
>       number?: string | null,
>       reference?: string | null
>     } | null,
>     wallet?: string | null
>   } | {
>     amount?: number | null,
>     context?: string | null,
>     currency?: string | null,
>     line_items?: {
>       name?: string | null,
>       quantity?: number | null,
>       unit_amount?: number | null
>     }[] | null,
>     merchant_country?: string | null,
>     merchant_name?: string | null,
>     merchant_url?: string | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     totals?: {
>       amount?: number | null,
>       type?: string | null
>     }[] | null,
>     wallet?: string | null
>   } | {
>     amount?: number | null,
>     card?: {
>       cvc_alias?: string | null,
>       exp_month?: number | null,
>       exp_year?: number | null,
>       last4?: string | null,
>       pan_alias?: string | null
>     } | null,
>     card_mode?: string | null,
>     currency?: string | null,
>     merchant_name?: string | null,
>     merchant_url?: string | null,
>     provider?: string | null,
>     wallet?: string | null
>   } | null,
>   state?: {
>     credential_type?: string | null,
>     domains?: string[] | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     aliases?: {
>       cvc?: string | null,
>       exp_month?: string | null,
>       exp_year?: string | null,
>       number?: string | null
>     } | null,
>     authorization?: {
>       actual_cents?: number | null,
>       amount?: string | null,
>       amount_authority?: string | null,
>       amount_cents?: number | null,
>       amount_verified?: boolean | null,
>       approval_url?: string | null,
>       browser_id?: string | null,
>       charged_amount_cents?: number | null,
>       charged_currency?: string | null,
>       charged_kind?: string | null,
>       created_at?: string | null,
>       currency?: string | null,
>       expected_cents?: number | null,
>       expires_at?: string | null,
>       id?: string | null,
>       merchant?: string | null,
>       psp?: string | null,
>       psp_error_code?: string | null,
>       reason?: string | null,
>       replay_attempted?: boolean | null,
>       replay_delivered?: boolean | null,
>       replay_status?: number | null,
>       status?: string | null
>     } | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     preparation?: {
>       approval_url?: string | null,
>       browser_id?: string | null,
>       created_at?: string | null,
>       environment?: string | null,
>       expires_at?: string | null,
>       id?: string | null,
>       merchant_origin?: string | null,
>       psp?: string | null,
>       status?: string | null
>     } | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     domains?: string[] | null,
>     funding_status?: string | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     source?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     domains?: string[] | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     domains?: string[] | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | null,
>   type?: string | null,
>   updated_at?: string | null
> } | {
>   action?: {
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null,
>     url?: string | null
>   } | {
>     connect_url?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null,
>     url?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     name?: string | null
>   } | {
>     capture_token?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | null,
>   available_expansions?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   available_operations?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   created_at?: string | null,
>   expires_at?: string | null,
>   id?: string | null,
>   key?: string | null,
>   spec?: {
>     amount?: number | null,
>     context?: string | null,
>     currency?: string | null,
>     line_items?: {
>       description?: string | null,
>       image_url?: string | null,
>       name?: string | null,
>       product_url?: string | null,
>       quantity?: number | null,
>       sku?: string | null,
>       totals?: {
>         amount?: number | null,
>         display_text?: string | null,
>         type?: string | null
>       }[] | null,
>       unit_amount?: number | null,
>       url?: string | null
>     }[] | null,
>     merchant_name?: string | null,
>     merchant_url?: string | null,
>     metadata?: Record<string, string> | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     recurring?: {
>       interval?: string | null,
>       interval_count?: number | null
>     } | null,
>     totals?: {
>       amount?: number | null,
>       display_text?: string | null,
>       type?: string | null
>     }[] | null,
>     wallet?: string | null
>   } | {
>     amount?: number | null,
>     currency?: string | null,
>     merchant_category?: string | null,
>     merchant_category_code?: string | null,
>     merchant_country?: string | null,
>     merchant_name?: string | null,
>     merchant_url?: string | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     wallet?: string | null
>   } | null,
>   state?: {
>     credential_type?: string | null,
>     domains?: string[] | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     domains?: string[] | null,
>     funding_status?: string | null,
>     masks?: {
>       brand?: string | null,
>       last4?: string | null,
>       token_last4?: string | null
>     } | null,
>     payment_method_id?: string | null,
>     provider?: string | null,
>     source?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | null,
>   type?: string | null,
>   updated_at?: string | null
> } | {
>   action?: {
>     connect_url?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | null,
>   available_expansions?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   available_operations?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   created_at?: string | null,
>   expires_at?: string | null,
>   id?: string | null,
>   key?: string | null,
>   spec?: {
>     authorization?: {
>       client?: {
>         type?: string | null
>       } | null,
>       method?: string | null
>     } | null,
>     provider?: string | null
>   } | null,
>   state?: {
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | null,
>   type?: string | null,
>   updated_at?: string | null
> } | {
>   action?: {
>     expires_at?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | {
>     access_request_reference?: string | null,
>     instructions?: string | null,
>     name?: string | null,
>     url?: string | null
>   } | null,
>   available_expansions?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   available_operations?: {
>     description?: string | null,
>     type?: string | null
>   }[] | null,
>   created_at?: string | null,
>   id?: string | null,
>   key?: string | null,
>   spec?: {
>     description?: string | null,
>     fields?: {
>       label?: string | null,
>       name?: string | null,
>       required?: boolean | null,
>       sensitive?: boolean | null,
>       type?: string | null
>     }[] | null,
>     provider?: string | null
>   } | {
>     access_token_expires_at?: string | null,
>     account?: string | null,
>     provider?: string | null,
>     requests?: {
>       entries?: {
>         id?: string | null,
>         keywords?: string[] | null,
>         parameters?: {
>           website?: string | null
>         } | null,
>         reason?: string | null,
>         type?: string | null
>       }[] | null,
>       goal?: string | null,
>       version?: number | null
>     } | null
>   } | {
>     connection_id?: string | null,
>     description?: string | null,
>     provider?: string | null
>   } | null,
>   state?: {
>     fields?: Record<string, {
>       has_value?: boolean | null,
>       value?: string | null
>     }> | null,
>     provider?: string | null,
>     status?: string | null
>   } | {
>     access_request?: {
>       createdAt?: string | null,
>       entries?: {
>         id?: string | null,
>         keywords?: string[] | null,
>         parameters?: {
>           website?: string | null
>         } | null,
>         reason?: string | null,
>         type?: string | null
>       }[] | null,
>       goal?: string | null,
>       granted_count?: number | null,
>       has_autofill_token?: boolean | null,
>       id?: string | null,
>       identity?: string | null,
>       path?: string | null,
>       request?: {
>         entries?: {
>           id?: string | null,
>           keywords?: string[] | null,
>           parameters?: {
>             website?: string | null
>           } | null,
>           reason?: string | null,
>           type?: string | null
>         }[] | null,
>         goal?: string | null,
>         version?: number | null
>       } | null,
>       resolved?: {
>         entryId?: string | null,
>         reference?: string | null
>       }[] | null,
>       state?: string | null
>     } | null,
>     access_request_id?: string | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | {
>     fields?: Record<string, {
>       type?: string | null
>     }> | null,
>     provider?: string | null,
>     status?: string | null,
>     status_reason?: string | null
>   } | null,
>   type?: string | null,
>   updated_at?: string | null,
>   version?: number | null
> }
> ```

***

### list

`vaults.list`

List vaults in the project.

**Risk:** `read`

```ts theme={null}
await corsair.kernel.api.vaults.list({});
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `limit` | `number` | No | — |
| `offset` | `number` | No | — |
| `query` | `string` | No | Case-insensitive substring match against vault name. IDs match by exact value. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `items` | `object[]` | Yes | This page of results. |
| `has_more` | `boolean` | Yes | True when more results follow; pass next\_offset as offset to read them. |
| `next_offset` | `number \| null` | Yes | Value for `offset` that reads the next page, or null on the last page. |

> [accordion] items full type
>
> ```ts theme={null}
> {
>   created_at?: string | null,
>   id?: string | null,
>   name?: string | null,
>   updated_at?: string | null
> }[]
> ```

***

### upsert

`vaults.upsert`

Create a vault (a project-scoped store of secrets, cards and credentials for browsers to use), or get the existing one with that name.

**Risk:** `write`

```ts theme={null}
await corsair.kernel.api.vaults.upsert({ name: 'my-name' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `name` | `string` | Yes | Immutable name used to create or retrieve the vault. |

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `created_at` | `string \| null` | No | — |
| `id` | `string \| null` | No | — |
| `name` | `string \| null` | No | Immutable name assigned when the vault is created. |
| `updated_at` | `string \| null` | No | — |

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.