{
  "openapi": "3.1.0",
  "info": {
    "title": "Headless Domains API",
    "description": "API for registering and managing agent identities on Headless Domains, optimized for autonomous AI agents.",
    "version": "1.0.0",
    "x-guidance": "To register or renew a domain, you must pay via MPP using pathUSD. If you do not have an API key, you may omit the Authorization header and a Headless identity will be automatically created using your Tempo wallet address. Send a POST request without a receipt to receive a 402 challenge, then fulfill the payment and re-submit.",
    "contact": {
      "name": "Headless Domains Support",
      "url": "https://headlessdomains.com"
    }
  },
  "x-service-info": {
    "name": "Headless Domains",
    "description": "Agentic identity and decentralized domains on Handshake.",
    "url": "https://headlessdomains.com",
    "docs": {
      "homepage": "https://docs.headlessdomains.com"
    }
  },
  "servers": [
    {
      "url": "https://headlessdomains.com"
    }
  ],
  "paths": {
    "/api/v1/domains/search": {
      "get": {
        "summary": "Search Domain Availability",
        "description": "Check if a domain name is available for registration across all supported namespaces, or check a specific namespace.",
        "operationId": "searchDomain",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "required": true,
            "description": "The domain name to search (e.g. 'myagent' or 'myagent.agent')",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Search results retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {"type": "string", "example": "success"},
                    "query": {"type": "string"},
                    "results": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "domain": {"type": "string"},
                          "tld": {"type": "string"},
                          "available": {"type": "boolean"},
                          "human_price": {"type": "number"},
                          "agent_price": {"type": "number"},
                          "reason": {"type": "string"}
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/domains/{domain_name}/bmos-status": {
      "get": {
        "summary": "Check BMOS Integration Status",
        "description": "External binding check to verify if a domain is actively linked to a BuildMyOnlineStore (BMOS) storefront. Enforces strict 1-to-1 domain-to-storefront mappings.",
        "operationId": "getBmosStatus",
        "parameters": [
          {
            "name": "domain_name",
            "in": "path",
            "required": true,
            "description": "The full domain name to check (e.g. 'mike.agent')",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Status retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "is_bound": {
                      "type": "boolean",
                      "example": true
                    },
                    "storefront_id": {
                      "type": "string",
                      "nullable": true,
                      "example": "ddd7af53-792d-4ed8-891b-1adfe4f94f53"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Domain not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {"type": "string", "example": "error"},
                    "message": {"type": "string", "example": "Domain not found"}
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/lookup/{domain_name}": {
      "get": {
        "summary": "Lookup Domain Profile",
        "description": "Retrieve public profile information, active capabilities, and agentic commerce storefront details for a given domain.",
        "operationId": "domainLookup",
        "parameters": [
          {
            "name": "domain_name",
            "in": "path",
            "required": true,
            "description": "The full domain name to look up (e.g. 'myagent.chatbot')",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Domain profile retrieved successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {"type": "string", "example": "success"},
                    "domain": {"type": "object"},
                    "identity": {"type": "object"},
                    "manifests": {"type": "object"},
                    "profile": {
                      "type": "object",
                      "description": "The decentralized bio/profile fields for the domain",
                      "properties": {
                        "commerce_catalog": {
                          "type": "object",
                          "description": "Agentic commerce storefront integration data",
                          "properties": {
                            "provider": {"type": "string", "example": "bmos"},
                            "storefront_id": {"type": "string"},
                            "feed_url": {"type": "string", "format": "uri"},
                            "status": {"type": "string"}
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Domain not found"
          }
        }
      }
    },
    "/api/v1/domains/register": {
      "post": {
        "summary": "Register a Domain",
        "description": "Allows an AI agent to autonomously register a domain using Machine Payments Protocol (MPP).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "domain",
                  "namespace",
                  "years",
                  "agreed_to_terms"
                ],
                "properties": {
                  "domain": {
                    "type": "string"
                  },
                  "namespace": {
                    "type": "string"
                  },
                  "years": {
                    "type": "integer"
                  },
                  "agreed_to_terms": {
                    "type": "boolean"
                  },
                  "payment_method": {
                    "type": "string",
                    "enum": [
                      "mpp",
                      "gems"
                    ]
                  },
                  "receipt": {
                    "type": "string"
                  },
                  "reseller_channel": {
                    "type": "string",
                    "description": "Optional identifier for integration partners (e.g. 'arp.run')"
                  },
                  "target_owner_id": {
                    "type": "string",
                    "description": "Optional user ID to assign the domain to, overriding the API key owner."
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Domain successfully registered."
          },
          "402": {
            "description": "Payment Required. Returns an MPP challenge."
          }
        }
      }
    },
    "/api/v1/renew": {
      "post": {
        "summary": "Renew a Domain",
        "description": "Allows an agent to autonomously renew its own domain using MPP.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "domain",
                  "years",
                  "payment_method",
                  "receipt"
                ],
                "properties": {
                  "domain": {
                    "type": "string"
                  },
                  "years": {
                    "type": "integer"
                  },
                  "payment_method": {
                    "type": "string",
                    "enum": [
                      "mpp"
                    ]
                  },
                  "receipt": {
                    "type": "string"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Domain successfully renewed."
          },
          "402": {
            "description": "Payment Required. Returns an MPP challenge."
          }
        }
      }
    },
    "/api/v1/domains/{domain_name}/reset-lock": {
      "post": {
        "summary": "Clear Registration Lock",
        "description": "If an autonomous MPP registration flow is interrupted midway, the domain may become lock-stalled to prevent double-spending. Use this endpoint to explicitly clear the stale lock before re-attempting registration.",
        "operationId": "resetDomainLock",
        "parameters": [
          {
            "name": "domain_name",
            "in": "path",
            "required": true,
            "description": "The full domain name to unlock (e.g. 'myagent.chatbot')",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lock cleared successfully",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {"type": "string", "example": "success"},
                    "message": {"type": "string", "example": "Cleared lock for myagent.chatbot"}
                  }
                }
              }
            }
          },
          "404": {
            "description": "Domain or lock not found"
          }
        }
      }
    },
    "/api/v1/domains/for-sale": {
      "get": {
        "summary": "Browse Secondary Market",
        "description": "Discover domains currently listed for sale by humans and AI agents.",
        "parameters": [
          {
            "name": "currency",
            "in": "query",
            "schema": {
              "type": "string",
              "enum": [
                "gems",
                "usd"
              ]
            },
            "description": "Filter listings by supported currency."
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            },
            "description": "Number of results to return."
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            },
            "description": "Pagination offset."
          }
        ],
        "responses": {
          "200": {
            "description": "List of available domains on the secondary market."
          },
          "402": {
            "description": "Payment Required. Returns an MPP challenge."
          }
        }
      }
    },
    "/api/v1/domains/buy-secondary": {
      "post": {
        "summary": "Purchase on Secondary Market",
        "description": "Allows an AI agent to autonomously purchase a listed domain via pathUSD (MPP).",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "domain"
                ],
                "properties": {
                  "domain": {
                    "type": "string"
                  },
                  "receipt": {
                    "type": "string",
                    "description": "MPP payment authorization"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successfully purchased the domain."
          },
          "402": {
            "description": "Payment Required. Returns an MPP challenge matching the seller's asking price."
          }
        }
      }
    },
    "/api/v1/domains/make-offer": {
      "post": {
        "summary": "Submit a Numeric Offer",
        "description": "Submit a numeric offer for a listed domain to negotiate price securely.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "domain",
                  "amount",
                  "currency"
                ],
                "properties": {
                  "domain": {
                    "type": "string"
                  },
                  "amount": {
                    "type": "number"
                  },
                  "currency": {
                    "type": "string",
                    "enum": [
                      "gems",
                      "pathusd"
                    ]
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Offer submitted successfully."
          },
          "400": {
            "description": "Bad request. May include code 'offer_below_minimum' with the seller's `minimum` and `currency` when the offer is below the per-domain floor."
          },
          "402": {
            "description": "Payment Required. Returns an MPP challenge."
          }
        }
      }
    },
    "/api/v1/domains/offers": {
      "get": {
        "summary": "View Domain Offers",
        "description": "View incoming offers for domains you own, and outgoing offers you have submitted.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "List of pending, accepted, and rejected offers."
          },
          "402": {
            "description": "Payment Required. Returns an MPP challenge."
          }
        }
      }
    },
    "/api/v1/domains/activity": {
      "get": {
        "summary": "Transaction History",
        "description": "Retrieve a ledger of your agent's historical transactions (registrations, renewals, purchases, transfers).",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Ledger of DomainOrder records."
          },
          "402": {
            "description": "Payment Required. Returns an MPP challenge."
          }
        }
      }
    },
    "/api/v1/domains/sold": {
      "get": {
        "summary": "Historical Secondary Sales",
        "description": "Public aggregation endpoint for directories to discover historical secondary market sales and volume.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 50
            }
          },
          {
            "name": "offset",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of completed secondary market sales."
          },
          "402": {
            "description": "Payment Required. Returns an MPP challenge."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    }
  }
}