Skip to content
shadow-canary

Admin API

The admin API is a set of Next.js Route Handlers under app/admin/api/. All endpoints require a valid session cookie obtained by logging in at /admin/login.

Authentication

The session is a HMAC-signed cookie (admin-session) set at login. It expires after 8 hours.

Login:

Terminal window
curl -c cookies.txt -X POST https://your-app.vercel.app/admin/login \
  -H 'Content-Type: application/json' \
  -d '{"username": "admin", "password": "your-password"}'

Response: 302 Redirect to /admin on success, 401 on failure.

GET /admin/api/status

Returns the current canary state from Edge Config.

Auth: Session cookie required.

Response:

{
  "deploymentDomainProd": "https://my-app-abc.vercel.app",
  "deploymentDomainProdPrevious": "https://my-app-def.vercel.app",
  "deploymentDomainShadow": "https://my-app-xyz.vercel.app",
  "trafficShadowPercent": 1,
  "trafficProdCanaryPercent": 42,
  "shadowForceIPs": [],
  "canaryPaused": false,
  "canaryStartedAt": "2024-11-15T08:00:00Z"
}

Example:

Terminal window
curl -b cookies.txt https://your-app.vercel.app/admin/api/status

POST /admin/api/pause

Pauses the canary ramp. Sets canaryPaused: true in Edge Config. The cron will skip SLO checks and bumps until resumed.

Auth: Session cookie required.

Request body: None.

Response:

{ "ok": true, "canaryPaused": true }

Example:

Terminal window
curl -b cookies.txt -X POST https://your-app.vercel.app/admin/api/pause

POST /admin/api/resume

Resumes a paused canary. Sets canaryPaused: false. The next cron tick will run normally.

Auth: Session cookie required.

Request body: None.

Response:

{ "ok": true, "canaryPaused": false }

Example:

Terminal window
curl -b cookies.txt -X POST https://your-app.vercel.app/admin/api/resume

POST /admin/api/cancel

Cancels the canary. Sets trafficProdCanaryPercent: 0 and canaryPaused: true. All prod traffic returns to deploymentDomainProdPrevious. Use this for a manual rollback.

Auth: Session cookie required.

Request body: None.

Response:

{ "ok": true, "trafficProdCanaryPercent": 0, "canaryPaused": true }

Example:

Terminal window
curl -b cookies.txt -X POST https://your-app.vercel.app/admin/api/cancel

POST /admin/api/rollback

Rolls back to a specific previous production deploy. Calls vercel promote to re-alias the custom domain, resets deploymentDomainProd to the target URL, clears deploymentDomainProdPrevious, and sets trafficProdCanaryPercent: 100.

Auth: Session cookie required.

Request body:

{ "deploymentUrl": "https://my-app-old.vercel.app" }

Response:

{ "ok": true, "deploymentDomainProd": "https://my-app-old.vercel.app" }

Example:

Terminal window
curl -b cookies.txt -X POST https://your-app.vercel.app/admin/api/rollback \
  -H 'Content-Type: application/json' \
  -d '{"deploymentUrl": "https://my-app-old.vercel.app"}'

GET /admin/api/deployments

Lists the 20 most recent deployments for the production branch from the Vercel API. Used by the Rollback panel.

Auth: Session cookie required.

Response:

{
  "deployments": [
    {
      "uid": "dpl_xxxxx",
      "url": "my-app-abc.vercel.app",
      "created": 1700000000000,
      "state": "READY",
      "meta": { "githubCommitMessage": "feat: add checkout improvements" }
    }
  ]
}

Example:

Terminal window
curl -b cookies.txt https://your-app.vercel.app/admin/api/deployments

Related:

  • Dashboard — the UI that calls these endpoints
  • Edge Config — the data model written by these endpoints