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

# Deployments API

> Trigger, list, and rollback deployments via the Nometria API.

The deployments API lets you trigger production deployments, check their status, and roll back to previous versions.

## List deployments

```http theme={null}
GET /v1/deployments
```

Returns deployments across all your projects, or for a specific project.

**Query parameters:**

| Parameter    | Type    | Description                                                                |
| ------------ | ------- | -------------------------------------------------------------------------- |
| `project_id` | string  | Filter by project                                                          |
| `limit`      | integer | Number of results (default: 20, max: 100)                                  |
| `cursor`     | string  | Pagination cursor                                                          |
| `status`     | string  | Filter: `queued`, `building`, `deploying`, `live`, `failed`, `rolled_back` |

**Example request:**

```bash theme={null}
curl "https://api.nometria.com/v1/deployments?project_id=proj_abc123" \
  -H "Authorization: Bearer <your-api-key>"
```

**Example response:**

```json theme={null}
{
  "data": [
    {
      "id": "dep_latest",
      "project_id": "proj_abc123",
      "commit_sha": "a1b2c3d",
      "commit_message": "feat: add payment flow",
      "branch": "main",
      "status": "live",
      "url": "https://app.yourcompany.com",
      "created_at": "2025-01-15T14:00:00Z",
      "live_at": "2025-01-15T14:04:30Z"
    },
    {
      "id": "dep_prev",
      "project_id": "proj_abc123",
      "commit_sha": "e4f5g6h",
      "commit_message": "fix: auth redirect",
      "branch": "main",
      "status": "rolled_back",
      "url": "https://app.yourcompany.com",
      "created_at": "2025-01-14T09:00:00Z",
      "live_at": "2025-01-14T09:04:00Z"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  }
}
```

***

## Get deployment

```http theme={null}
GET /v1/deployments/{deployment_id}
```

Returns a single deployment with full details.

**Example response:**

```json theme={null}
{
  "data": {
    "id": "dep_latest",
    "project_id": "proj_abc123",
    "commit_sha": "a1b2c3d",
    "commit_message": "feat: add payment flow",
    "branch": "main",
    "status": "live",
    "url": "https://app.yourcompany.com",
    "preview_url": null,
    "region": "us-east-1",
    "instance_type": "t3.small",
    "build_duration_seconds": 87,
    "created_at": "2025-01-15T14:00:00Z",
    "live_at": "2025-01-15T14:04:30Z",
    "logs_url": "https://api.nometria.com/v1/deployments/dep_latest/logs"
  }
}
```

***

## Trigger deployment

```http theme={null}
POST /v1/deployments
```

Manually trigger a deployment for a project. Deploys the current `HEAD` of the project's connected branch.

**Request body:**

| Field        | Type   | Required | Description                                           |
| ------------ | ------ | -------- | ----------------------------------------------------- |
| `project_id` | string | Yes      | Project to deploy                                     |
| `commit_sha` | string | No       | Specific commit to deploy (default: latest on branch) |
| `env_vars`   | object | No       | Override environment variables for this deploy        |

**Example request:**

```bash theme={null}
curl -X POST https://api.nometria.com/v1/deployments \
  -H "Authorization: Bearer <your-api-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "proj_abc123"
  }'
```

**Example response:**

```json theme={null}
{
  "data": {
    "id": "dep_triggered123",
    "project_id": "proj_abc123",
    "status": "queued",
    "created_at": "2025-01-15T15:00:00Z"
  }
}
```

The deployment runs asynchronously. Poll `GET /v1/deployments/{id}` for status.

***

## Rollback deployment

```http theme={null}
POST /v1/deployments/{deployment_id}/rollback
```

Roll back production to a previous deployment. The target deployment must have `status: live` or `status: rolled_back`.

**Example request:**

```bash theme={null}
curl -X POST https://api.nometria.com/v1/deployments/dep_prev/rollback \
  -H "Authorization: Bearer <your-api-key>"
```

**Example response:**

```json theme={null}
{
  "data": {
    "id": "dep_rollback789",
    "project_id": "proj_abc123",
    "rolled_back_from": "dep_latest",
    "rolled_back_to": "dep_prev",
    "status": "queued",
    "created_at": "2025-01-15T15:10:00Z"
  }
}
```

Nometria redeploys the exact code and environment variables from the target deployment — zero code changes needed.

***

## Deployment logs

```http theme={null}
GET /v1/deployments/{deployment_id}/logs
```

Returns build and deploy logs for a deployment.

**Example request:**

```bash theme={null}
curl https://api.nometria.com/v1/deployments/dep_latest/logs \
  -H "Authorization: Bearer <your-api-key>"
```

**Example response:**

```json theme={null}
{
  "data": {
    "logs": [
      { "timestamp": "2025-01-15T14:00:01Z", "level": "info", "message": "Pulling latest commit a1b2c3d..." },
      { "timestamp": "2025-01-15T14:00:10Z", "level": "info", "message": "Building Docker image..." },
      { "timestamp": "2025-01-15T14:01:30Z", "level": "info", "message": "npm install complete (147 packages)" },
      { "timestamp": "2025-01-15T14:02:45Z", "level": "info", "message": "npm run build complete" },
      { "timestamp": "2025-01-15T14:03:00Z", "level": "info", "message": "Starting container..." },
      { "timestamp": "2025-01-15T14:04:15Z", "level": "info", "message": "Health check passed" },
      { "timestamp": "2025-01-15T14:04:30Z", "level": "success", "message": "Deployment live at https://app.yourcompany.com" }
    ]
  }
}
```

***

## Deployment statuses

| Status        | Description                                 |
| ------------- | ------------------------------------------- |
| `queued`      | Deployment is in the queue                  |
| `building`    | Docker image is being built                 |
| `deploying`   | Container is starting, health check running |
| `live`        | Deployment is serving production traffic    |
| `failed`      | Deployment failed — check logs              |
| `rolled_back` | Deployment was superseded by a rollback     |

***

## CI/CD integration

Use the API in your GitHub Actions workflow to trigger deployments after tests pass:

```yaml theme={null}
name: Deploy to Production

on:
  push:
    branches: [main]

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Trigger Nometria deployment
        run: |
          curl -X POST https://api.nometria.com/v1/deployments \
            -H "Authorization: Bearer ${{ secrets.Nometria_API_KEY }}" \
            -H "Content-Type: application/json" \
            -d '{"project_id": "${{ secrets.Nometria_PROJECT_ID }}"}'
```

Store `Nometria_API_KEY` and `Nometria_PROJECT_ID` as GitHub repository secrets.