# Deploy hooks API

> Reference for Falak deploy hook URLs — GET or POST /api/deploy/{token}, reserved falak_deploy_* parameters, FALAK_VAR_ variables, responses and limits.

Source: https://falak.sh/docs/api/deploy-hooks/

## `GET|POST /api/deploy/{token}`

Starts a deployment of the site the token belongs to. No `Authorization` header: the unguessable token in the URL is the credential. Create or regenerate the URL under the site's **Settings → Deploy** (permission `deployments.manage`).

### Reserved query parameters

| Parameter | Meaning |
|---|---|
| `falak_deploy_branch` | Branch to deploy (default: the site's branch) |
| `falak_deploy_commit` | Exact commit SHA, 7–64 hex characters |
| `falak_deploy_author` | Author shown in the UI and exported as `FALAK_COMMIT_AUTHOR` |
| `falak_deploy_message` | Message shown in the UI and exported as `FALAK_COMMIT_MESSAGE` |

### Custom variables

Every other query parameter becomes `FALAK_VAR_` in the deploy script environment: the name is upper-cased and non-alphanumeric characters become `_`. At most 50 variables, each up to 4 KiB. They are stored encrypted with the deployment.

```bash
curl -X POST "https://falak.example.com/api/deploy/$TOKEN?falak_deploy_branch=main&notify=ops-channel"
# deploy script: FALAK_VAR_NOTIFY=ops-channel
```

### Responses

```json title="202 Accepted"
{"data": {"id": "01k…", "status": "building", "number": 43, "url": "https://falak.example.com/sites/01k…/deployments/01k…"}}
```

| Status | Meaning |
|---|---|
| `202` | Deployment created, or merged into the site's waiting deployment |
| `404` | Unknown or rotated token |
| `422` | Invalid commit |
| `429` | More than 30 requests per minute |

The trigger is `hook` in the API and `api` in `FALAK_TRIGGER`.

See [Push-to-deploy and deploy hooks](/docs/guides/push-to-deploy/) for usage.