REST API

Everything in your portfolio over plain HTTP and JSON: for scripts, spreadsheets, CI jobs, internal dashboards and your own apps. It offers the same operations as the MCP server, with the same token.

1. Create a token

Open the API page in your Lemon Domains account and click New token. Choose Read-only for reports and dashboards, or Read and write to make changes. You see the value once. The same token also connects AI tools over MCP.

2. Check it works

curl https://lemon.domains/api/v1/me \
  -H "Authorization: Bearer YOUR_TOKEN"

You get back your account and the token's access level.

3. Ask for your domains

curl "https://lemon.domains/api/v1/domains/expiring?withinDays=60" \
  -H "Authorization: Bearer YOUR_TOKEN"

{
  "count": 1,
  "withinDays": 60,
  "includeExpired": false,
  "domains": [
    {
      "id": "6f1c…",
      "domainName": "example.com",
      "status": "Active",
      "autoRenew": false,
      "expiryDate": "2026-12-01",
      "displayStatus": "Active",
      "projectName": "Acme",
      "registrarAccountDisplayName": "Main",
      "registrarName": "Porkbun"
    }
  ]
}

4. Make a change

curl -X POST https://lemon.domains/api/v1/domains \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "domainName": "coolapp.io",
    "projectId": "PROJECT_ID",
    "registrarAccountId": "REGISTRAR_ACCOUNT_ID",
    "expiryDate": "2027-03-01"
  }'

Get the ids from GET /projects and GET /registrar-accounts. Changes made through the API show up in each domain's history as API.

Conventions

• Paging. GET /domains takes limit (up to 500) and offset, and returns total and hasMore.
• Status. displayStatus is the status the app shows: Active, Expiring soon, Expired, Unknown, Not at registrar or Archived. It follows the expiry date and registrar sync.
• Archived domains. Archive a domain you no longer track with PATCH /domains/{id} and {"archived": true, "archivedNote": "Moved to the client"}. Lists and counts leave archived domains out; pass archived=include or archived=only to GET /domains to see them.
• Look up by name. GET /domains/example.com works as well as GET /domains/<id>.
• Partial updates. PATCH changes only the fields you send. Unknown fields are rejected, so a typo never silently does nothing.
• Safe deletes. Deleting a project, registrar or registrar account also deletes what's under it, so it needs ?confirm=true. Without it you get a 409 that says what would be removed.
• Dates. YYYY-MM-DD. Timestamps are ISO 8601 in UTC.
• CORS. Allowed from any origin, so browser tools work. Keep tokens out of public web pages.

Errors

Every error has the same shape:

{
  "error": {
    "code": "invalid_request",
    "message": "expiryDate: Use YYYY-MM-DD",
    "details": [{ "field": "expiryDate", "message": "Use YYYY-MM-DD" }]
  }
}

Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.

OpenAPI

The spec at https://lemon.domains/api/v1/openapi.json describes every endpoint and field. Import it into Postman, Insomnia or a client generator, or hand it to your AI assistant.