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

# Deployments

> Deploy, monitor, and roll back MCP server versions

**Required scope:** `deployments:read` (read), `deployments:write` (mutations)

***

## Trigger a deployment

```
POST /v1/servers/:serverId/deploy
```

Start a new deployment by providing an OCI image URI.

**Request body:**

```json theme={null}
{
  "imageUri": "registry.fly.io/my-project/my-server:latest"
}
```

| Field      | Type   | Required | Description             |
| ---------- | ------ | -------- | ----------------------- |
| `imageUri` | string | ✓        | OCI image URI to deploy |

**Response `201`:** Deployment created and pipeline complete.

```json theme={null}
{
  "data": {
    "id": "dep_qrs456",
    "serverId": "srv_xyz789",
    "status": "running",
    "imageUri": "registry.fly.io/my-project/my-server:latest",
    "version": 1,
    "trivyScanResult": null,
    "createdAt": "2026-01-15T12:00:00Z",
    "deployedAt": "2026-01-15T12:03:15Z"
  }
}
```

**Deployment statuses:**

| Status        | Description                               |
| ------------- | ----------------------------------------- |
| `pending`     | Queued, not yet started                   |
| `building`    | Image is being built or scanned           |
| `running`     | Successfully deployed and serving traffic |
| `failed`      | Deploy failed (see `errorMessage`)        |
| `rolled_back` | Superseded by a rollback                  |

***

## List deployments

```
GET /v1/servers/:serverId/deployments
```

Returns deployment history, newest first.

**Query parameters:** Standard pagination (`limit`, `cursor`)

**Response `200`:**

```json theme={null}
{
  "data": [
    {
      "id": "dep_qrs456",
      "status": "running",
      "imageUri": "registry.fly.io/my-project/my-server:latest",
      "version": 1,
      "trivyScanResult": {
        "critical": 0,
        "high": 0,
        "medium": 2
      },
      "createdAt": "2026-01-15T12:00:00Z",
      "deployedAt": "2026-01-15T12:03:15Z"
    }
  ],
  "meta": { "cursor": null, "hasMore": false, "total": 1 }
}
```

***

## Roll back

```
POST /v1/servers/:serverId/rollback
```

Redeploy a previous version by version number. Up to 10 historical deployments are kept (3 on the Free tier).

**Request body:**

```json theme={null}
{
  "version": 3
}
```

| Field     | Type    | Required | Description                                      |
| --------- | ------- | -------- | ------------------------------------------------ |
| `version` | integer | ✓        | Version number of the deployment to roll back to |

**Response `201`:** New deployment object (type: rollback).

***

## List server logs

```
GET /v1/servers/:serverId/logs
```

Returns paginated server log entries, newest first.

**Required scope:** `logs:read` or `servers:read`

**Query parameters:**

| Parameter | Type    | Description                                                        |
| --------- | ------- | ------------------------------------------------------------------ |
| `level`   | string  | Filter by level: `debug`, `info`, `warn`, `error`                  |
| `search`  | string  | Case-insensitive substring match on message                        |
| `limit`   | integer | Max entries to return (1–200, default 50)                          |
| `before`  | string  | Pagination cursor from a previous response (returns older entries) |

**Response `200`:**

```json theme={null}
{
  "data": {
    "items": [
      {
        "id": "1234567890",
        "serverId": "srv_xyz789",
        "level": "info",
        "message": "MCP server listening on port 8080",
        "timestamp": "2026-01-15T12:00:00.000Z"
      }
    ],
    "hasMore": true,
    "cursor": "1746100800000_1234567890"
  }
}
```

To fetch the next page, pass the `cursor` value from the response as the `before` query parameter in your next request. When `hasMore` is `false`, no more entries are available.