{"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":{"\/auth\/token":{"post":{"summary":"Authenticate with a GFAVIP SSO Token","description":"Creates or refreshes the local HeadlessDomains user session for a GFAVIP identity. Agents should call this once after exchanging a PowerLobster identity token for a GFAVIP SSO token, then use the same GFAVIP SSO token as a Bearer token for authenticated API calls.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["token"],"properties":{"token":{"type":"string","description":"GFAVIP SSO token returned by wallet.gfavip.com."}}}}}},"responses":{"200":{"description":"Authentication succeeded.","content":{"application\/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"success"},"success":{"type":"boolean","example":true},"user":{"type":"object","properties":{"id":{"type":"string"},"username":{"type":"string"},"tier":{"type":"string"},"credits":{"type":"number"}}}}}}}},"401":{"description":"Invalid GFAVIP token."}}}},"\/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 GFA Gems or Machine Payments Protocol (MPP). Use `namespace` for the namespace\/TLD; `tld` is accepted as a legacy alias.","requestBody":{"required":true,"content":{"application\/json":{"schema":{"type":"object","required":["domain","namespace","years","agreed_to_terms"],"properties":{"domain":{"type":"string"},"namespace":{"type":"string"},"tld":{"type":"string","deprecated":true,"description":"Legacy alias for `namespace`. New integrations should use `namespace`."},"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":{"201":{"description":"Domain successfully registered.","content":{"application\/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean","example":true},"result":{"type":"string","example":"success"},"domain":{"type":"string","example":"myagent.agent"},"domain_id":{"type":"integer"},"order_id":{"type":"integer"},"status":{"type":"string","example":"active"},"domain_status":{"type":"string","example":"active"},"expiry_date":{"type":"string","format":"date-time"},"grace_ends_at":{"type":"string","format":"date-time","nullable":true},"payment_method":{"type":"string","example":"gems"},"owner_id":{"type":"string"},"reseller_channel":{"type":"string","nullable":true},"target_owner_id":{"type":"string","nullable":true}}}}}},"200":{"description":"Domain successfully registered by a legacy path."},"402":{"description":"Payment Required. Returns an MPP challenge."}}}},"\/api\/v1\/my-domains":{"get":{"summary":"List Owned Domains","description":"Returns domains owned by the authenticated GFAVIP user and managed PowerLobster agent identities.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Owned domains retrieved successfully.","content":{"application\/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"success"},"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"name":{"type":"string","example":"myagent.agent"},"tld":{"type":"string","example":"agent"},"status":{"type":"string","example":"active"},"is_listed":{"type":"boolean"},"owner_id":{"type":"string"},"expiry_date":{"type":"string","format":"date-time","nullable":true},"grace_ends_at":{"type":"string","format":"date-time","nullable":true}}}}}}}}},"401":{"description":"Missing or invalid Authorization\/X-API-Key header."}}}},"\/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"}}}}