Skip to content

Command Center (Milestone 1A)

Headless Command is the beginning of the Headless Domains command layer.

It is designed to let:

  • users
  • AI agents
  • external systems

interact with Headless Domains through a cleaner structured command interface.

This first release is intentionally narrow and safe.

Current Status

Milestone 1A is now live with:

  • one endpoint: POST /api/v1/command
  • structured JSON only
  • dry_run mode only
  • no direct state-changing execution yet

This means agents can already test:

  • command formatting
  • authentication
  • dry-run planning
  • normalized responses

without changing live domain state.

Why This Exists

Headless Domains already supports agent workflows.

Headless Command adds a cleaner command surface so agents do not need to learn multiple route-specific flows for every operation.

The long-term direction is:

  • dry_run
  • confirm
  • execute

But Milestone 1A only implements:

  • dry_run

Endpoint

Endpoint: POST /api/v1/command

Content-Type: application/json

Authentication

You must authenticate with either:

  • a normal logged-in Headless Domains session
  • or a Bearer API key

For external agents, Bearer API key is the recommended method.

Authorization Header

Authorization: Bearer <your_api_key>

How To Get An API Key

Log into Headless Domains and generate an API key from your dashboard.

Current API keys look like:

  • hd_live_...

Use that value in the Bearer header.

Important Limitation

Milestone 1A is easiest to test from:

  • curl
  • terminal
  • Python script
  • external agent tool

Testing directly in a browser page may fail or be inconvenient because:

  • you may not have the right auth header
  • browser context may not be the same as your agent context
  • direct browser testing is less useful than testing the real agent call path

Request Format

General Shape

{
  "action": "show_expiring_domains",
  "mode": "dry_run",
  "params": {},
  "request_id": "optional-client-id"
}

Fields

  • action: command name
  • mode: currently only dry_run
  • params: action-specific object
  • request_id: optional caller trace ID

Supported Actions

Milestone 1A currently supports:

  • show_expiring_domains
  • renew_domain

1. show_expiring_domains

Returns a dry-run view of domains you can manage that expire within a given number of days.

Example Request

curl -X POST https://headlessdomains.com/api/v1/command \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -d '{
    "action": "show_expiring_domains",
    "mode": "dry_run",
    "params": {
      "within_days": 30
    },
    "request_id": "test-expiring-001"
  }'

Example Response

{
  "success": true,
  "action": "show_expiring_domains",
  "mode": "dry_run",
  "request_id": "test-expiring-001",
  "result": {
    "summary": "Found 2 domain(s) expiring within 30 day(s).",
    "requires_confirmation": false,
    "requires_payment": false,
    "warnings": [],
    "resolved": {
      "within_days": 30,
      "managed_user_ids": ["user-id-1", "agent-id-2"]
    },
    "data": {
      "count": 2,
      "domains": [
        {
          "id": 41,
          "domain": "myagent.chatbot",
          "status": "active",
          "is_active": true,
          "owner_id": "agent-id-2",
          "expiry_date": "2026-05-02T12:00:00",
          "days_until_expiry": 14
        }
      ]
    },
    "next_step": null
  }
}

2. renew_domain

Returns a dry-run plan for renewing a domain.

This does not charge anything and does not renew the domain yet.

Example Request

curl -X POST https://headlessdomains.com/api/v1/command \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -d '{
    "action": "renew_domain",
    "mode": "dry_run",
    "params": {
      "domain": "myagent.chatbot",
      "years": 1,
      "payment_preference": "mpp"
    },
    "request_id": "test-renew-001"
  }'

Example Response

{
  "success": true,
  "action": "renew_domain",
  "mode": "dry_run",
  "request_id": "test-renew-001",
  "result": {
    "summary": "Renew myagent.chatbot for 1 year(s).",
    "requires_confirmation": true,
    "requires_payment": true,
    "warnings": [],
    "resolved": {
      "domain": "myagent.chatbot",
      "domain_id": 41,
      "years": 1,
      "purchase_channel": "agent_mpp",
      "payment_method": "mpp",
      "tld": "chatbot",
      "current_expiry_date": "2026-05-02T12:00:00"
    },
    "pricing": {
      "currency_unit": "pathUSD",
      "unit_price": 1.25,
      "gross_price": 1.25,
      "discount_amount": 0.0,
      "net_price": 1.25
    },
    "next_step": "confirm"
  }
}

Payment Preference

For renew_domain, payment_preference can influence the dry-run planning result.

Current practical values:

  • mpp
  • agent_mpp
  • agent

Anything else currently falls back to the human/gems planning path.

Current Limitations

Milestone 1A does not yet support:

  • confirm
  • execute
  • register_domain
  • set_price
  • set_listing_status

If you send one of those modes or unsupported actions, you should expect a clear error response.

Common Error Responses

Unauthorized

{
  "success": false,
  "error": {
    "code": "unauthorized",
    "message": "Authentication required. Use session auth or Bearer API key."
  }
}

Unsupported Action

{
  "success": false,
  "action": "register_domain",
  "mode": "dry_run",
  "error": {
    "code": "unsupported_action",
    "message": "Unsupported action 'register_domain' for Milestone 1A."
  }
}

Mode Not Implemented

{
  "success": false,
  "action": "renew_domain",
  "mode": "execute",
  "error": {
    "code": "mode_not_implemented",
    "message": "Only dry_run mode is implemented in Milestone 1A."
  }
}

Suggested Testing Sequence For Agents

If you are helping test this feature, use this order:

  1. verify your API key works
  2. call show_expiring_domains
  3. call renew_domain for a domain you own
  4. confirm the dry-run pricing and summary look correct
  5. report any mismatches in:
  6. auth
  7. ownership access
  8. domain lookup
  9. pricing
  10. response formatting

What To Report During Testing

When sharing feedback, include:

  • full request payload
  • whether session auth or Bearer API key was used
  • response status code
  • response JSON
  • the domain used in testing

That will make debugging much faster.

Next Planned Steps

After Milestone 1A, the roadmap is:

  1. add more dry-run actions
  2. add confirmation flow
  3. add safe execute support
  4. add register_domain
  5. connect command execution with MPP-aware payment flow