API reference

Trigger deploys and pull logs from your own automation. Token-authenticated REST. Same endpoints the dashboard and CLI use.

Interactive spec

Full OpenAPI spec with request/response schemas is served at /api/v1/openapi.json. Load it into Postman, Insomnia, or any OpenAPI viewer.

Base URL

Base
https://previewdrop.dev/api/v1

Authentication

All requests authenticate with a personal API token. Create one from Dashboard → Settings → API tokens. Tokens are scoped to your workspace.

bash
curl https://previewdrop.dev/api/v1/me \
  -H "Authorization: Bearer $PREVIEWDROP_TOKEN"

Endpoints

Projects

GET /projects — list projects in your workspace.
GET /projects/{id}/deployments — list deployments for one project.

Deployments

POST /deployments — trigger a deployment for a project + branch.
GET /deployments — list deployments across the workspace (paginated, 50 max).
GET /deployments/{id} — fetch status, URL, and metadata for one deployment.
POST /deployments/{id}/redeploy — rebuild from the same commit.
GET /deployments/{id}/logs — build log output (streaming + diagnostics).
GET /deployments/{id}/container-logs — runtime stdout/stderr.

Account

GET /me — the current token's user and workspace.

Trigger a deployment

bash
curl -X POST https://previewdrop.dev/api/v1/deployments \
  -H "Authorization: Bearer $PREVIEWDROP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "projectId": "prj_abc123",
    "branch": "feature/checkout-redesign",
    "commitSha": "a1b2c3d4"
  }'

Poll for ready

bash
curl https://previewdrop.dev/api/v1/deployments/dep_xyz \
  -H "Authorization: Bearer $PREVIEWDROP_TOKEN"

# => { "status": "ready", "url": "https://feature-checkout-abc.previews.previewdrop.dev", ... }

Rate limits

Plan-scoped. Most endpoints allow 60 requests per minute per token. Deployment triggers count against your plan's concurrent-preview limit — a 429 with Retry-After means you've hit the ceiling. See pricing for tier limits.

Webhooks

Incoming webhooks (GitHub, GitLab, Bitbucket) are managed automatically when you connect a repo. Outbound webhooks — so your systems can react to preview state changes — are on the roadmap; email support@previewdrop.dev if you need them now.