{"openapi":"3.1.0","info":{"title":"DomainListener External API","version":"2026-07-26","description":"Scoped personal-key access to DomainListener domains, groups, monitors, and research queue.\nAll workspace operations are tenant-bound by the authenticated actor. Personal API key reads\nare limited to 120 requests per minute; inspect the RateLimit response headers for the active window.\n"},"servers":[{"url":"https://domainlistener.com"}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1":{"get":{"summary":"Discover the DomainListener API","description":"Returns public links for the API documentation, OpenAPI contract, read-only sandbox, and personal API key management.","operationId":"getApiIndex","security":[],"responses":{"200":{"$ref":"#/components/responses/ApiIndex"}}}},"/api/v1/sandbox":{"get":{"summary":"Read sandbox sample data","description":"Returns deterministic, read-only sample domain data so clients can verify JSON parsing without credentials or workspace access.","operationId":"getSandboxSample","security":[],"responses":{"200":{"$ref":"#/components/responses/Sandbox"}}}},"/api/v1/domains":{"get":{"summary":"List tracked domains","description":"Returns the authenticated user's tracked domains, bounded by the domains:read scope and tenant isolation.","operationId":"listDomains","responses":{"200":{"$ref":"#/components/responses/DomainList"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}},"post":{"summary":"Create a tracked domain","description":"Adds one domain to the authenticated user's portfolio after plan-limit and validation checks.","operationId":"createDomain","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"example.com"}}}}}},"responses":{"201":{"$ref":"#/components/responses/Domain"},"400":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}}},"/api/v1/domains/{id}":{"parameters":[{"$ref":"#/components/parameters/Id"}],"get":{"summary":"Get a tracked domain","description":"Returns one tracked domain owned by the authenticated user.","operationId":"getDomain","responses":{"200":{"$ref":"#/components/responses/Domain"},"404":{"$ref":"#/components/responses/Error"}}},"patch":{"summary":"Change a tracked domain group","description":"Assigns an owned domain to an owned group, or clears its group when groupId is null.","operationId":"updateDomain","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["groupId"],"properties":{"groupId":{"type":["string","null"],"format":"uuid"}}}}}},"responses":{"200":{"$ref":"#/components/responses/Domain"},"404":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Delete a tracked domain","description":"Permanently removes one tracked domain owned by the authenticated user.","operationId":"deleteDomain","responses":{"204":{"description":"Deleted"},"404":{"$ref":"#/components/responses/Error"}}}},"/api/v1/groups":{"get":{"summary":"List domain groups","description":"Returns the authenticated user's seeded and custom domain groups.","operationId":"listGroups","responses":{"200":{"$ref":"#/components/responses/GroupList"}}},"post":{"summary":"Create a custom group","description":"Creates one custom domain group for the authenticated user after plan-limit validation.","operationId":"createGroup","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":80}}}}}},"responses":{"201":{"$ref":"#/components/responses/Group"},"403":{"$ref":"#/components/responses/Error"}}}},"/api/v1/groups/{id}":{"parameters":[{"$ref":"#/components/parameters/Id"}],"patch":{"summary":"Set group sort order","description":"Updates the display order of one custom group owned by the authenticated user.","operationId":"updateGroup","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["sortOrder"],"properties":{"sortOrder":{"type":"integer","minimum":0}}}}}},"responses":{"200":{"$ref":"#/components/responses/Group"}}},"delete":{"summary":"Delete a custom group","description":"Deletes one custom group owned by the authenticated user without deleting its domains.","operationId":"deleteGroup","responses":{"204":{"description":"Deleted"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"}}}},"/api/v1/monitors":{"get":{"summary":"List uptime monitors","description":"Returns the authenticated user's uptime monitors and their current status.","operationId":"listMonitors","responses":{"200":{"$ref":"#/components/responses/MonitorList"}}},"post":{"summary":"Create an uptime monitor","description":"Creates an HTTP uptime monitor after URL validation and plan-limit checks.","operationId":"createMonitor","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorCreate"}}}},"responses":{"201":{"$ref":"#/components/responses/Monitor"},"400":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}}},"/api/v1/monitors/{id}":{"parameters":[{"$ref":"#/components/parameters/Id"}],"get":{"summary":"Get an uptime monitor","description":"Returns one uptime monitor owned by the authenticated user.","operationId":"getMonitor","responses":{"200":{"$ref":"#/components/responses/Monitor"},"404":{"$ref":"#/components/responses/Error"}}},"patch":{"summary":"Update an uptime monitor","description":"Updates mutable settings for one uptime monitor owned by the authenticated user.","operationId":"updateMonitor","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MonitorUpdate"}}}},"responses":{"200":{"$ref":"#/components/responses/Monitor"},"400":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Delete an uptime monitor","description":"Permanently removes one uptime monitor owned by the authenticated user.","operationId":"deleteMonitor","responses":{"204":{"description":"Deleted"},"404":{"$ref":"#/components/responses/Error"}}}},"/api/v1/research-queue":{"get":{"summary":"List research queue items","description":"Returns acquisition candidates in the authenticated user's research queue.","operationId":"listResearchQueue","responses":{"200":{"$ref":"#/components/responses/ResearchQueueList"}}},"post":{"summary":"Add one domain to the research queue","description":"Adds one unique domain candidate to the authenticated user's research queue.","operationId":"createResearchQueueItem","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["domainName"],"properties":{"domainName":{"type":"string","example":"example.com"},"source":{"type":"string","enum":["manual","api_feed"],"default":"api_feed"}}}}}},"responses":{"201":{"$ref":"#/components/responses/ResearchQueueItem"},"409":{"$ref":"#/components/responses/Error"}}}},"/api/v1/research-queue/{id}":{"parameters":[{"$ref":"#/components/parameters/Id"}],"get":{"summary":"Get a research queue item","description":"Returns one research queue item owned by the authenticated user.","operationId":"getResearchQueueItem","responses":{"200":{"$ref":"#/components/responses/ResearchQueueItem"},"404":{"$ref":"#/components/responses/Error"}}},"patch":{"summary":"Update a research queue item","description":"Updates the verdict, notes, or maximum bid for one owned research candidate.","operationId":"updateResearchQueueItem","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"verdict":{"type":["string","null"],"enum":["buy","watch","skip","backorder",null]},"notes":{"type":["string","null"],"maxLength":10000},"maxBid":{"type":["number","null"],"minimum":0}}}}}},"responses":{"200":{"$ref":"#/components/responses/ResearchQueueItem"},"400":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Delete a research queue item","description":"Permanently removes one research candidate owned by the authenticated user.","operationId":"deleteResearchQueueItem","responses":{"204":{"description":"Deleted"},"404":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"DomainListener personal API key"}},"parameters":{"Id":{"name":"id","in":"path","required":true,"description":"Resource UUID owned by the authenticated user.","schema":{"type":"string","format":"uuid"}}},"headers":{"DomainListenerApiVersion":{"schema":{"type":"string"},"description":"Version selected for the response."},"RequestId":{"schema":{"type":"string"},"description":"Support correlation identifier."},"RateLimitLimit":{"schema":{"type":"integer"},"description":"Requests permitted in the active window."},"RateLimitRemaining":{"schema":{"type":"integer"},"description":"Requests left in the active window."},"RateLimitReset":{"schema":{"type":"integer"},"description":"Unix timestamp at the next window boundary."}},"schemas":{"Domain":{"type":"object","required":["id","name"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string","example":"example.com"},"groupId":{"type":["string","null"],"format":"uuid"},"registrar":{"type":["string","null"]},"status":{"type":["string","null"]},"expiryDate":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"Group":{"type":"object","required":["id","name","sortOrder"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"sortOrder":{"type":"integer"},"isDefault":{"type":"boolean"},"createdAt":{"type":"string","format":"date-time"}}},"Monitor":{"type":"object","required":["id","name","url","isActive"],"properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"url":{"type":"string","format":"uri"},"isActive":{"type":"boolean"},"isUp":{"type":["boolean","null"]},"checkIntervalMinutes":{"type":"integer","minimum":1},"publicStatusEnabled":{"type":"boolean"},"publicSlug":{"type":["string","null"]},"lastCheckedAt":{"type":["string","null"],"format":"date-time"},"createdAt":{"type":"string","format":"date-time"}}},"ResearchQueueItem":{"type":"object","required":["id","domainName","source"],"properties":{"id":{"type":"string","format":"uuid"},"domainName":{"type":"string","example":"example.com"},"source":{"type":"string","enum":["manual","api_feed"]},"verdict":{"type":["string","null"],"enum":["buy","watch","skip","backorder",null]},"notes":{"type":["string","null"]},"maxBid":{"type":["number","null"],"minimum":0},"createdAt":{"type":"string","format":"date-time"},"updatedAt":{"type":"string","format":"date-time"}}},"ApiIndexData":{"type":"object","required":["name","version","documentation","openapi","sandbox","authentication"],"properties":{"name":{"type":"string","const":"DomainListener External API"},"version":{"type":"string","example":"2026-07-26"},"documentation":{"type":"string","format":"uri"},"openapi":{"type":"string","format":"uri"},"sandbox":{"type":"string","format":"uri"},"authentication":{"type":"object","required":["type","keyManagement","note"],"properties":{"type":{"type":"string","const":"Bearer"},"keyManagement":{"type":"string","format":"uri"},"note":{"type":"string"}}}}},"SandboxData":{"type":"object","required":["environment","authenticated","readOnly","sampleDomain","next"],"properties":{"environment":{"type":"string","const":"sandbox"},"authenticated":{"type":"boolean","const":false},"readOnly":{"type":"boolean","const":true},"sampleDomain":{"$ref":"#/components/schemas/Domain"},"next":{"type":"object","required":["createAccount","createApiKey","firstRequest"],"properties":{"createAccount":{"type":"string","format":"uri"},"createApiKey":{"type":"string","format":"uri"},"firstRequest":{"type":"string","format":"uri"}}}}},"MonitorCreate":{"type":"object","required":["name","url"],"properties":{"name":{"type":"string","maxLength":160},"url":{"type":"string","format":"uri"},"checkIntervalMinutes":{"type":"integer","minimum":1}}},"MonitorUpdate":{"type":"object","properties":{"name":{"type":"string","maxLength":160},"url":{"type":"string","format":"uri"},"isActive":{"type":"boolean"},"publicStatusEnabled":{"type":"boolean"},"publicSlug":{"type":["string","null"]},"checkIntervalMinutes":{"type":"integer","minimum":1}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","resolution","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"resolution":{"type":"string","description":"Action an API client can take to resolve the error."},"requestId":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}},"responses":{"ApiIndex":{"description":"Public API discovery metadata","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ApiIndexData"}}}}}},"Sandbox":{"description":"Deterministic read-only sandbox response","content":{"application/json":{"schema":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/SandboxData"}}}}}},"Domain":{"description":"Domain","headers":{"DomainListener-API-Version":{"$ref":"#/components/headers/DomainListenerApiVersion"},"X-Request-Id":{"$ref":"#/components/headers/RequestId"}},"content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Domain"}}}}}},"DomainList":{"description":"Domains","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Domain"}}}}}}},"Group":{"description":"Group","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Group"}}}}}},"GroupList":{"description":"Groups","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Group"}}}}}}},"Monitor":{"description":"Monitor","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/Monitor"}}}}}},"MonitorList":{"description":"Monitors","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Monitor"}}}}}}},"ResearchQueueItem":{"description":"Research queue item","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"$ref":"#/components/schemas/ResearchQueueItem"}}}}}},"ResearchQueueList":{"description":"Research queue items","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ResearchQueueItem"}}}}}}},"Error":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}