Triggers a new preview build. The deployment record is created as queued, then immediately dispatched to the build worker — the response reflects the worker's initial status (typically building).

In-flight cancellation

If a deployment for the same project and branch is already queued, building, or deploying, it is automatically cancelled (status set to stopped) before the new build starts. This matches the push webhook behavior: the last deploy always wins, orphaned containers are not left running.

Specifying the repository

You must provide either projectId or repoUrl:

• projectId — uses the GitHub repo and env vars configured on the project. Request-level envVars are merged on top. Private repos are accessed automatically via the GitHub App.
• repoUrl — ad-hoc build from any public GitHub HTTPS URL (credentials embedded in the URL are not supported; use projectId for private repos).

Environment variables

Keys are automatically normalised to UPPERCASE. Each key must match [A-Z_][A-Z0-9_]* (up to 100 chars) and each value may be up to 8 KiB.

TTL

If omitted, the preview lives for your plan's default TTL (1 h / 4 h / 8 h / 7 d depending on plan). Pass ttlMs to override, e.g. 3600000 for 1 hour.

Polling for completion

After creating a deployment, poll GET /api/v1/deployments/{id} every 5–15 seconds until status is ready or failed. A typical build takes 60–180 seconds.

Idempotency

Supply an Idempotency-Key request header (e.g. a UUID) to safely retry failed requests without triggering duplicate deploys. If the key matches a request processed within the last 5 minutes, the cached successful response is returned with an Idempotency-Replayed: true header instead of firing a new build. Keys must be 8–128 alphanumeric/hyphen/underscore characters.

{
  "projectId": "11223344-5566-7788-99aa-bbccddeeff00",
  "repoUrl": "https://github.com/acme/my-app.git",
  "branch": "feat/new-checkout",
  "envVars": {
    "DATABASE_URL": "postgres://user:pass@host/db",
    "NEXT_PUBLIC_API_URL": "https://api.example.com"
  },
  "ttlMs": 28800000,
  "githubToken": "ghp_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}

{
  "deployment": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "tenant_id": "f0e1d2c3-b4a5-6789-0abc-def123456789",
    "project_id": "11223344-5566-7788-99aa-bbccddeeff00",
    "pd_projects": {
      "github_repo": "acme/my-app"
    },
    "worker_deploy_id": "abc123def456",
    "url": "https://prv-abc123.previews.previewdrop.dev",
    "status": "ready",
    "framework": "nextjs",
    "branch": "feat/new-checkout",
    "detected_env_vars": [
      "DATABASE_URL",
      "NEXT_PUBLIC_API_URL"
    ],
    "build_log": "[1/4] Installing dependencies...\n[2/4] Building application...",
    "expires_at": "2026-04-09T14:00:00.000Z",
    "created_at": "2026-04-09T10:00:00.000Z",
    "updated_at": "2026-04-09T10:03:42.000Z"
  }
}