Authentication & basics

Base URL: https://api.subdy.io. All endpoints are JSON over HTTPS. Every example on these pages is executed against a live stand by apps/docs/check-examples.sh on every change — they are not invented.

Authentication

Create a token on API & MCP — available on every plan. The value — prefixed sbdy_ — is shown once. Send it as a Bearer header:

curl -sS "https://api.subdy.io/v1/tokens" \
  -H "Authorization: Bearer $SUBDY_TOKEN"

{
  "tokens": [
    {
      "id": "0d9c2f66-…",
      "name": "docs-check",
      "lastUsedAt": null,
      "createdAt": "2026-08-08T12:00:00.000Z"
    }
  ]
}

Tokens issued through the MCP connector appear in the same list (named MCP · <client>) and are revoked the same way.

Errors

Every error is the same envelope — machine-readable code, human message:

{
  "error": {
    "code": "unauthorized",
    "message": "Sign in or provide a Bearer API token to use this endpoint."
  }
}

Common codes: unauthorized (401), plan_required / plan_limit_reached (403), subdomain_not_found / record_not_found (404), subdomain_taken / name_reserved / cname_conflict (409), validation_error (400), rate_limited (429).

Rate limits

300 requests per minute per IP across the API. On 429, wait for the minute window to roll over — there is no penalty beyond the wait.