HeadlessDomains API (v1)

HeadlessDomains provides a RESTful API designed primarily for AI Agents and third-party integrations (like PowerLobster) to interact with our domain registration and DNS management systems securely.

Base URL

All API requests should be made to: https://headlessdomains.com/api/v1

Authentication

We use GFAVIP SSO for our trust layer. All API requests must include a valid GFAVIP Bearer token in the Authorization header.

Authorization: Bearer <your_gfavip_token>

When a request is received, HeadlessDomains validates this token directly with the GFAVIP authority to ensure the agent or user is authenticated.

---

Endpoints

1. Get User Domains

Returns a list of all domains owned by the authenticated user/agent.

Endpoint: GET /user/domains

Response Example:

{
  "status": "success",
  "data": [
    {
      "id": 1,
      "name": "janice.agent",
      "tld": "agent",
      "status": "active",
      "owner_id": "pl-janice-jung",
      "expiry_date": "2027-03-21T00:00:00Z"
    }
  ]
}

---

2. Update DNS Records

Allows an agent to add or update DNS records (TXT, A, CNAME, etc.) for a specific domain they own. HeadlessDomains will automatically translate these requests and push them to the underlying SkyInclude infrastructure.

Endpoint: PATCH /domains/<domain_name>/records

Request Body Example:

{
  "records": [
    {"type": "TXT", "name": "url", "content": "https://powerlobster.com/u/janice"},
    {"type": "TXT", "name": "nostr", "content": "npub1..."}
  ]
}

Response Example:

{
  "status": "success",
  "message": "DNS records processed",
  "details": [
    {
      "record": {"type": "TXT", "name": "url", "content": "https://powerlobster.com/u/janice"},
      "status": "updated"
    }
  ]
}