# API, CLI and CI deploys

> API tokens with scopes, the REST API v1, the zefily command-line tool, and deploying from GitHub Actions or GitLab CI.

## API tokens

Create a token under **Settings → API tokens**: a **Name**, an expiry (**Expires after** a number of days, or **Never expires**) and the **Scopes** it may use. The token is shown **once** — copy it into your CI secrets. It acts as you, with your role in the organization, limited to its scopes. The list shows when each token was created and last used; **Revoke token** disables it at once.

| Scope | Allows |
| --- | --- |
| `servers:read` | List servers and their state |
| `sites:read` | List sites and their deploy settings |
| `sites:write` | Create sites (with the panel's validation) |
| `sites:deploy` | Start deploys and rollbacks |
| `jobs:read` | Follow jobs: a deploy's, or a server's recent ones |

The number of requests per minute depends on your plan.

## REST API v1

Base URL `https://app.zefily.com/api/v1`, with the token as a Bearer token:

```bash
curl -H "Authorization: Bearer $ZEFILY_TOKEN" https://app.zefily.com/api/v1/servers
```

| Method and path | Scope |
| --- | --- |
| `GET /servers` | `servers:read` |
| `GET /servers/{server}` | `servers:read` |
| `GET /servers/{server}/sites` | `sites:read` |
| `POST /servers/{server}/sites` | `sites:write` |
| `GET /servers/{server}/sites/{site}` | `sites:read` |
| `POST /servers/{server}/sites/{site}/deploy` | `sites:deploy` |
| `POST /servers/{server}/sites/{site}/rollback` | `sites:deploy` |
| `GET /servers/{server}/jobs` | `jobs:read` |
| `GET /jobs/{job}` | `jobs:read` |

Every write goes through the same checks as the panel (validation, plan limits, the audit log).

## The zefily CLI

Download the CLI for your system from `https://dl.zefily.com/cli/` (`zefily-linux-amd64`, `zefily-linux-arm64`, `zefily-darwin-arm64`, `zefily-windows-amd64.exe`…). Set `ZEFILY_TOKEN` to your token:

```bash
zefily servers
zefily sites [server]
zefily deploy <domain|site-id> [--wait]
zefily rollback <domain|site-id> [--release YYYYMMDDhhmmss] [--wait]
zefily job <id> [--wait]
zefily jobs <server> [--type site.deploy]
```

`--wait` follows the job and exits with status 1 when it does not succeed, so a pipeline fails with the deploy.

## Deploy from CI

Use a token with `sites:read`, `sites:deploy` and `jobs:read`, stored as a CI secret.

GitHub Actions:

```yaml
deploy:
  needs: test
  if: github.ref == 'refs/heads/main'
  runs-on: ubuntu-latest
  steps:
    - name: Deploy
      env:
        ZEFILY_TOKEN: ${{ secrets.ZEFILY_TOKEN }}
      run: |
        curl -fsSLo zefily https://dl.zefily.com/cli/zefily-linux-amd64
        chmod +x zefily
        ./zefily deploy app.example.com --wait
```

GitLab CI:

```yaml
deploy:
  stage: deploy
  rules:
    - if: $CI_COMMIT_BRANCH == "main"
  script:
    - curl -fsSLo zefily https://dl.zefily.com/cli/zefily-linux-amd64 && chmod +x zefily
    - ./zefily deploy app.example.com --wait
```

To be notified when deploys finish, add a [webhook](/docs/notifications) for the `deploy finished` event.

---
Source: https://zefily.com/docs/api-and-cli