{"openapi":"3.1.0","info":{"title":"Signal Username API","version":"0.1.0","description":"Three bounded rule-source adapters. Not native Sherlock/Maigret CLI execution. A client API key is required for scans and account access. v0.1.x preserves the published v1 request contract."},"servers":[{"url":"/"}],"paths":{"/v1/health":{"get":{"summary":"Service and release information","responses":{"200":{"description":"Service metadata","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/capabilities":{"get":{"summary":"Engines, supported sites and limits","responses":{"200":{"description":"Capabilities","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/privacy":{"get":{"summary":"Current privacy notice and registration readiness","responses":{"200":{"description":"Notice","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/clients":{"post":{"summary":"Register a human, bot or service; return a secret once","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Registration"}}}},"responses":{"201":{"description":"client_id and one-time api_key","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, expired or revoked API key","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit or concurrency limit","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Storage unavailable or registration not enabled","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/clients/me":{"get":{"security":[{"ApiKey":[]}],"summary":"Read registered profile","responses":{"200":{"description":"Profile","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, expired or revoked API key","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit or concurrency limit","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Storage unavailable or registration not enabled","content":{"application/json":{"schema":{"type":"object"}}}}}},"patch":{"security":[{"ApiKey":[]}],"summary":"Correct client profile","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Profile"}}}},"responses":{"200":{"description":"Updated profile","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, expired or revoked API key","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit or concurrency limit","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Storage unavailable or registration not enabled","content":{"application/json":{"schema":{"type":"object"}}}}}},"delete":{"security":[{"ApiKey":[]}],"summary":"Erase client profile, credentials, scans and application audit records","responses":{"200":{"description":"Deleted","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, expired or revoked API key","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit or concurrency limit","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Storage unavailable or registration not enabled","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/clients/me/export":{"get":{"security":[{"ApiKey":[]}],"summary":"Export current client data, scans and usage events","responses":{"200":{"description":"Data export","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, expired or revoked API key","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit or concurrency limit","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Storage unavailable or registration not enabled","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/clients/me/key":{"post":{"security":[{"ApiKey":[]}],"summary":"Rotate key; old key stops working, new key shown once","responses":{"200":{"description":"One-time key","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, expired or revoked API key","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit or concurrency limit","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Storage unavailable or registration not enabled","content":{"application/json":{"schema":{"type":"object"}}}}}},"delete":{"security":[{"ApiKey":[]}],"summary":"Revoke key immediately; export or delete account first if needed","responses":{"200":{"description":"Revoked","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, expired or revoked API key","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit or concurrency limit","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Storage unavailable or registration not enabled","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/clients/me/usage":{"get":{"security":[{"ApiKey":[]}],"summary":"Read usage events retained for 30 days","responses":{"200":{"description":"Usage events","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, expired or revoked API key","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit or concurrency limit","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Storage unavailable or registration not enabled","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/scans":{"post":{"security":[{"ApiKey":[]}],"summary":"Create a scan; three adapters run in parallel","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScanRequest"}}}},"responses":{"200":{"description":"Cached scan","content":{"application/json":{"schema":{"type":"object"}}}},"202":{"description":"Scan accepted","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, expired or revoked API key","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit or concurrency limit","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Storage unavailable or registration not enabled","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/scans/{scan_id}":{"parameters":[{"name":"scan_id","in":"path","required":true,"schema":{"type":"string"}}],"get":{"security":[{"ApiKey":[]}],"summary":"Read own partial or final result","responses":{"200":{"description":"Scan results","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, expired or revoked API key","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found or expired","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit or concurrency limit","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Storage unavailable or registration not enabled","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/v1/scans/{scan_id}/engines/{engine}":{"parameters":[{"name":"scan_id","in":"path","required":true,"schema":{"type":"string"}},{"name":"engine","in":"path","required":true,"schema":{"enum":["sherlock","maigret","whatsmyname"]}}],"get":{"security":[{"ApiKey":[]}],"summary":"Read one adapter result","responses":{"200":{"description":"Individual result","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"type":"object"}}}},"401":{"description":"Missing, expired or revoked API key","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"type":"object"}}}},"429":{"description":"Rate limit or concurrency limit","content":{"application/json":{"schema":{"type":"object"}}}},"503":{"description":"Storage unavailable or registration not enabled","content":{"application/json":{"schema":{"type":"object"}}}}}}}},"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","description":"sg_live_... key returned once at registration"}},"schemas":{"Profile":{"type":"object","additionalProperties":false,"required":["client_name","actor_type","responsible_entity","contact_email","country","purpose"],"properties":{"client_name":{"type":"string","maxLength":100},"actor_type":{"enum":["human","bot","service"]},"responsible_entity":{"type":"string","maxLength":200},"contact_email":{"type":"string","format":"email"},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"purpose":{"type":"string","minLength":10,"maxLength":1000}}},"Registration":{"allOf":[{"type":"object","required":["client_name","actor_type","responsible_entity","contact_email","country","purpose","notice_version","acknowledge_privacy","confirm_authorized_use"],"properties":{"client_name":{"type":"string"},"actor_type":{"enum":["human","bot","service"]},"responsible_entity":{"type":"string"},"contact_email":{"type":"string","format":"email"},"country":{"type":"string","pattern":"^[A-Z]{2}$"},"purpose":{"type":"string","minLength":10},"notice_version":{"type":"string"},"acknowledge_privacy":{"const":true},"confirm_authorized_use":{"const":true}}}]},"ScanRequest":{"type":"object","additionalProperties":false,"required":["input"],"properties":{"input":{"type":"object","required":["type","value"],"properties":{"type":{"const":"username"},"value":{"type":"string","maxLength":64}}},"engines":{"type":"array","minItems":1,"maxItems":3,"uniqueItems":true,"items":{"enum":["sherlock","maigret","whatsmyname"]}},"sites":{"type":"array","minItems":1,"maxItems":6,"uniqueItems":true,"items":{"enum":["GitHub","GitLab","HackerNews","Keybase","Reddit","Instagram","YouTube","Pinterest","Medium","Telegram","SoundCloud","Twitch"]}}}}}}}