API Reference

Base URL#

https://www.deplo.in/api/v1

The version is part of the path (/api/v1). Breaking changes ship as a new version segment; v1 is the current and only version. Requests to www.deplo.in are proxied same-origin to the backend, which is how the browser dashboard talks to this API without CORS — your integration hits the same URL.

Authentication#

Every authenticated endpoint accepts a bearer token in the Authorization header. Two token types work interchangeably on every route:

If you are scripting against the API, use a CLI token — JWTs are session tokens for the dashboard. Your first request:

curl https://www.deplo.in/api/v1/auth/me \
  -H "Authorization: Bearer $DEPLO_TOKEN"

{
  "userId": "cm5xa1b2c0001njk8w9d2f3g4",
  "email": "ada@example.com",
  "name": "Ada Lovelace",
  "githubLogin": "adalovelace",
  "avatarUrl": "https://avatars.githubusercontent.com/u/9919?v=4"
}

See Authentication for the OAuth endpoints and CLI Tokens for token management.

Errors#

Errors return a JSON envelope with a machine-readable code and a human-readable message:

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Deployment not found"
  }
}

Request-body validation failures (400) additionally include a details object with per-field issues, and a few inline guard errors return only message. Always branch on the HTTP status first, then on error.code when present.

Rate limits#

The API allows 200 requests per 15 minutes per IP across all endpoints. Standard RateLimit-* response headers report your limit, remaining budget, and reset time. Exceeding the limit returns 429. Polling a deployment every 2–3 seconds fits comfortably within the budget.

Health#

curl https://www.deplo.in/api/v1/health

{
  "status": "healthy",
  "version": "v1",
  "environment": "production",
  "checks": {
    "database": "ok",
    "redis": "ok"
  },
  "timestamp": "2026-08-07T09:15:04.512Z"
}

System endpoints#

A few routes exist for machines, not API consumers: POST /webhooks/github and POST /webhooks/vercel receive signed provider webhooks, and GET /integrations/vercel/callback completes the browser-driven Vercel OAuth flow. They validate their own signatures or state tokens and are not meant to be called directly.

Resources#