# Droid Computers API

Provision and manage Factory computers: create, inspect, refresh, restart, and delete.

## List computers

`GET /api/v0/computers`

Returns the computers owned by the authenticated client, ordered newest first. Provisioning steps are included only when `includeProvisioningSteps=true`.

```bash
curl 'https://api.factory.ai/api/v0/computers' \
  -H 'Authorization: Bearer $FACTORY_API_KEY'
```

**Parameters**

- `hostId` (`string <uuid>`) - Query parameter
- `serviceAccountId` (`string`) - Query parameter. Look up a service account’s Computers (requires human Manager+).
- `includeProvisioningSteps` (`string`) - Query parameter. Whether to include provisioning step details. Allowed values: true, false.
- `includeUnlisted` (`string`) - Query parameter. Whether to include Computers hidden from normal listings. Allowed values: true, false.

**Response:** `200` - Response for status 200

## Create a computer

`POST /api/v0/computers`

Creates a computer. Managed computers are returned in a provisioning state and set up asynchronously; BYOM computers register an existing machine and are active immediately. Replaying a saved Software Factory Draft receipt returns its existing computer without provisioning another.

```bash
curl -X POST 'https://api.factory.ai/api/v0/computers' \
  -H 'Authorization: Bearer $FACTORY_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

**Response:** `200` - Response for status 200

**Response:** `201` - Response for status 201

## Create computers in bulk

`POST /api/v0/computers/bulk`

Creates up to 20 identical managed computers with server-assigned names (`<namePrefix>-<n>`, lowest free suffixes). Creation is fail-fast without rollback: on a mid-batch failure the response is still 201 with the computers created so far plus an `error` describing the failure.

```bash
curl -X POST 'https://api.factory.ai/api/v0/computers/bulk' \
  -H 'Authorization: Bearer $FACTORY_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

**Response:** `201` - Response for status 201

## Get a computer by name

`GET /api/v0/computers/name/{name}`

Returns the caller's computer by name, or a service account's computer when requested by a human Manager or higher.

```bash
curl 'https://api.factory.ai/api/v0/computers/name/{name}' \
  -H 'Authorization: Bearer $FACTORY_API_KEY'
```

**Parameters**

- `name` (`string`, required) - Path parameter. Computer name
- `serviceAccountId` (`string`) - Query parameter. Look up a service account’s Computers (requires human Manager+).
- `includeProvisioningSteps` (`string`) - Query parameter. Whether to include provisioning step details. Allowed values: true, false.

**Response:** `200` - Response for status 200

## List available computer providers

`GET /api/v0/computers/providers`

Returns the managed compute providers currently available for new computers in the authenticated organization.

```bash
curl 'https://api.factory.ai/api/v0/computers/providers' \
  -H 'Authorization: Bearer $FACTORY_API_KEY'
```

**Response:** `200` - Response for status 200

## Get a computer

`GET /api/v0/computers/{computerId}`

Returns a computer by ID. Callers can access their own computers; organization members with the manager role or higher can also access service-account-owned computers.

```bash
curl 'https://api.factory.ai/api/v0/computers/{computerId}' \
  -H 'Authorization: Bearer $FACTORY_API_KEY'
```

**Parameters**

- `computerId` (`string`, required) - Path parameter. Computer ID

**Response:** `200` - Response for status 200

## Delete a computer

`DELETE /api/v0/computers/{computerId}`

Permanently deletes a computer. Deleting a managed computer also shuts down its hosted environment and archives its sessions; deleting a BYOM computer removes the registration but leaves the machine and its sessions intact. Automations running on the computer are paused.

```bash
curl -X DELETE 'https://api.factory.ai/api/v0/computers/{computerId}' \
  -H 'Authorization: Bearer $FACTORY_API_KEY'
```

**Parameters**

- `computerId` (`string`, required) - Path parameter. Computer ID

**Response:** `204` - Response for status 204

## Update a computer

`PATCH /api/v0/computers/{computerId}`

Updates a computer's name or remote user. A host ID can be assigned to a computer that does not have one; host IDs are immutable once set and must be unique among the owner's computers.

```bash
curl -X PATCH 'https://api.factory.ai/api/v0/computers/{computerId}' \
  -H 'Authorization: Bearer $FACTORY_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

**Parameters**

- `computerId` (`string`, required) - Path parameter. Computer ID

**Response:** `200` - Response for status 200

## Record managed computer activity

`POST /api/v0/computers/{computerId}/activity`

Advances the inactivity clock for an active managed computer without performing connection or restart work. Not supported for BYOM computers.

```bash
curl -X POST 'https://api.factory.ai/api/v0/computers/{computerId}/activity' \
  -H 'Authorization: Bearer $FACTORY_API_KEY'
```

**Parameters**

- `computerId` (`string`, required) - Path parameter. Computer ID

**Response:** `200` - Response for status 200

## Complete a computer file upload

`POST /api/v0/computers/{computerId}/files/{fileName}/complete-upload`

Completes a file upload by writing the previously uploaded file into the computer's workspace. Returns `409 Conflict` if a file with that name already exists.

```bash
curl -X POST 'https://api.factory.ai/api/v0/computers/{computerId}/files/{fileName}/complete-upload' \
  -H 'Authorization: Bearer $FACTORY_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

**Parameters**

- `computerId` (`string`, required) - Path parameter. Computer ID
- `fileName` (`string`, required) - Path parameter. Workspace file name

**Response:** `200` - Response for status 200

## Create a computer file download

`POST /api/v0/computers/{computerId}/files/{fileName}/create-download`

Creates a download for a file in the computer's workspace and returns a time-limited download URL.

```bash
curl -X POST 'https://api.factory.ai/api/v0/computers/{computerId}/files/{fileName}/create-download' \
  -H 'Authorization: Bearer $FACTORY_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

**Parameters**

- `computerId` (`string`, required) - Path parameter. Computer ID
- `fileName` (`string`, required) - Path parameter. Workspace file name

**Response:** `200` - Response for status 200

## Create a computer file upload

`POST /api/v0/computers/{computerId}/files/{fileName}/create-upload`

Starts a file upload to a computer. Returns a time-limited upload URL and form fields; upload the file there, then call complete-upload to place it in the computer's workspace.

```bash
curl -X POST 'https://api.factory.ai/api/v0/computers/{computerId}/files/{fileName}/create-upload' \
  -H 'Authorization: Bearer $FACTORY_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

**Parameters**

- `computerId` (`string`, required) - Path parameter. Computer ID
- `fileName` (`string`, required) - Path parameter. Workspace file name

**Response:** `200` - Response for status 200

## Retry the install-dependencies step

`POST /api/v0/computers/{computerId}/install-deps`

Starts a new dependency-installation attempt on a managed computer that was configured to install dependencies. Installation runs in the background; returns `202 Accepted` with the updated computer, or `409 Conflict` when an install is already in progress.

```bash
curl -X POST 'https://api.factory.ai/api/v0/computers/{computerId}/install-deps' \
  -H 'Authorization: Bearer $FACTORY_API_KEY'
```

**Parameters**

- `computerId` (`string`, required) - Path parameter. Computer ID

**Response:** `202` - Response for status 202

## Get computer metrics

`GET /api/v0/computers/{computerId}/metrics`

Returns CPU, memory, and disk usage metrics for an active managed computer. Not supported for BYOM computers.

```bash
curl 'https://api.factory.ai/api/v0/computers/{computerId}/metrics' \
  -H 'Authorization: Bearer $FACTORY_API_KEY'
```

**Parameters**

- `computerId` (`string`, required) - Path parameter. Computer ID
- `start` (`string <date-time>`) - Query parameter. Start of time range (ISO 8601)

**Response:** `200` - Response for status 200

## Refresh a computer

`POST /api/v0/computers/{computerId}/refresh`

Refreshes the Git credentials and user-owned computer secrets on a managed computer. BYOM computers are not modified and return zero counts.

```bash
curl -X POST 'https://api.factory.ai/api/v0/computers/{computerId}/refresh' \
  -H 'Authorization: Bearer $FACTORY_API_KEY'
```

**Parameters**

- `computerId` (`string`, required) - Path parameter. Computer ID

**Response:** `200` - Response for status 200

## Restart a managed computer

`POST /api/v0/computers/{computerId}/restart`

Ensures an active managed computer is running, resuming it if necessary. Computers that are already running are left untouched and reported with `wasRestarted: false`. Not supported for BYOM computers.

```bash
curl -X POST 'https://api.factory.ai/api/v0/computers/{computerId}/restart' \
  -H 'Authorization: Bearer $FACTORY_API_KEY'
```

**Parameters**

- `computerId` (`string`, required) - Path parameter. Computer ID

**Response:** `200` - Response for status 200