# Instance Management API

**Page:** api/code/instance-management

[Download Raw Markdown](./api/code/instance-management.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## Instance Management API

Manage VS Code extensions programmatically. Use these endpoints to list installed extensions and install new ones from remote VSIX URLs, enabling automated deployment workflows and LLM-driven extension management.


Only install extensions from trusted sources. The install endpoint downloads and executes VSIX packages with full extension privileges.


---

### `GET /api/v1/code/extensions/list`

Returns a list of all installed VS Code extensions in the extensions directory.

This endpoint is useful for:
- Verifying extension installation
- Inventory management
- Debugging extension issues
- Automated testing

This endpoint takes no parameters.



```bash
curl -X GET "https://api.hoody.com/api/v1/code/extensions/list" \
  -H "Authorization: Bearer <token>"
```


```javascript
const result = await client.code.extensions.listIterator();

for await (const page of result) {
  console.log(page);
}
```


```json
{
  "success": true,
  "extensionsDir": "/home/user/.local/share/hoody-code/extensions",
  "count": 3,
  "extensions": [
    "ms-python.python-2023.1.0",
    "ms-toolsai.jupyter-2023.2.0",
    "github.copilot-1.67.0"
  ]
}
```

Response when no extensions are installed:

```json
{
  "success": true,
  "extensionsDir": "/home/user/.local/share/hoody-code/extensions",
  "count": 0,
  "extensions": []
}
```


```json
{
  "success": false,
  "error": "Failed to read extensions directory: EACCES"
}
```



---

### `POST /api/v1/code/extensions/install`

Install a VS Code extension by downloading and installing a VSIX file from a URL.

This endpoint allows remote installation of extensions, perfect for:
- Automated deployment workflows
- Custom extension distribution
- Programmatic extension management
- LLM-driven extension installation

The VSIX file is downloaded to a cache directory and then installed using VS Code's extension manager. If the extension is already cached, the cached version is used.

This endpoint takes no parameters.

**Request Body**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `url` | string (uri) | Yes | URL to the VSIX file to install. Supports HTTPS URLs (recommended) and HTTP URLs. |
| `asBuiltin` | boolean | No | If `true`, install as a system/built-in extension. Built-in extensions cannot be uninstalled by users. Default: `false` |



```bash
curl -X POST "https://api.hoody.com/api/v1/code/extensions/install" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://github.com/microsoft/vscode-python/releases/download/2023.1.0/ms-python-python-2023.1.0.vsix",
    "asBuiltin": false
  }'
```


```javascript
const result = await client.code.extensions.install({
  url: "https://github.com/microsoft/vscode-python/releases/download/2023.1.0/ms-python-python-2023.1.0.vsix",
  asBuiltin: false
});

console.log(result);
```


```json
{
  "success": true,
  "message": "Extension installed successfully",
  "url": "https://example.com/my-extension.vsix",
  "vsixPath": "/home/user/.local/share/hoody-code/vsix-cache/a1b2c3d4e5f6-my-extension.vsix",
  "asBuiltin": false,
  "installed": true
}
```


```json
{
  "success": false,
  "error": "Missing or invalid 'url' parameter"
}
```

Response when the URL is malformed:

```json
{
  "success": false,
  "error": "Invalid URL: not-a-url",
  "url": "not-a-url"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `MISSING_URL` | Missing URL parameter | The required `url` parameter was not provided | Include a valid VSIX URL in the request body |
| `INVALID_URL_FORMAT` | Invalid URL format | The provided URL is not a valid HTTPS or HTTP URL | Check the URL format and try again |


```json
{
  "success": false,
  "error": "HTTP 404 while downloading https://example.com/missing.vsix",
  "url": "https://example.com/missing.vsix"
}
```

Response when the VSIX fails to install:

```json
{
  "success": false,
  "error": "Installation failed: Extension is incompatible",
  "url": "https://example.com/extension.vsix"
}
```

| Error Code | Title | Description | Resolution |
|------------|-------|-------------|------------|
| `DOWNLOAD_FAILED` | Failed to download VSIX | Unable to download the extension file from the provided URL | Check if the URL is accessible and try again |
| `INSTALLATION_FAILED` | Extension installation failed | VS Code failed to install the extension (may be incompatible or corrupted) | Verify the VSIX file is valid and compatible with this VS Code version |