{"openapi":"3.1.1","info":{"title":"Nomancy API","version":"1.2.0","description":"For fun. Data is flawed and incomplete; these are guesses, not identities. No API key is required. Browser CORS is enabled without credentials. Results are ranked possibilities; no confidence scores are returned. Source credits, licence terms and processing disclosures are available at /data; the Link response header points to the credits."},"servers":[{"url":"/"}],"security":[],"paths":{"/api/v1/guess":{"get":{"operationId":"guessNames","summary":"Guess names from initials or a username","description":"Send exactly one of initials or username. The username reader is experimental; matches are possible interpretations, never identified people.","parameters":[{"name":"initials","in":"query","required":false,"description":"Send initials or username. 2–4 initials; spaces, periods, and hyphens are allowed. Unicode letters are supported.","schema":{"type":"string","minLength":2,"maxLength":32,"description":"Send initials or username. 2–4 initials; spaces, periods, and hyphens are allowed. Unicode letters are supported.","example":"JRB"}},{"name":"username","in":"query","required":false,"description":"Experimental alternative to initials. 2–64 characters, with an optional leading @. Recognizes complete names, initials, and anchored prefixes. First-name-only readings add a source-weighted surname guess. Numbers are ignored, never used to infer age.","schema":{"type":"string","minLength":2,"maxLength":65,"description":"Experimental alternative to initials. 2–64 characters, with an optional leading @. Recognizes complete names, initials, and anchored prefixes. First-name-only readings add a source-weighted surname guess. Numbers are ignored, never used to infer age.","example":"alexjsmith"}},{"name":"country","in":"query","required":false,"description":"Optional country code from /api/v1/options. Supported local combinations come first, followed by worldwide alternatives when exhausted. Omit for worldwide names; codes are case-insensitive.","schema":{"type":"string","description":"Optional country code from /api/v1/options. Supported local combinations come first, followed by worldwide alternatives when exhausted. Omit for worldwide names; codes are case-insensitive.","example":"CA"}},{"name":"order","in":"query","required":false,"description":"The order of the initials or username components. Last-first means last, first, then any middle names or initials.","schema":{"type":"string","enum":["first-last","last-first"],"default":"first-last","description":"The order of the initials or username components. Last-first means last, first, then any middle names or initials."}},{"name":"sex","in":"query","required":false,"description":"Name style hint: female favors feminine-associated names; male favors masculine-associated names. Not an identity prediction.","schema":{"type":"string","enum":["any","female","male"],"default":"any","description":"Name style hint: female favors feminine-associated names; male favors masculine-associated names. Not an identity prediction."}},{"name":"ageGroup","in":"query","required":false,"description":"Optional birth-cohort hint: any, under-30, 30-59, or 60-plus. Coverage varies by country and birth year; see /data.","schema":{"type":"string","enum":["any","under-30","30-59","60-plus"],"default":"any","description":"Optional birth-cohort hint: any, under-30, 30-59, or 60-plus. Coverage varies by country and birth year; see /data."}},{"name":"useLocation","in":"query","required":false,"description":"Use country supplied by a configured trusted hosting edge. No external IP lookup is made. Explicit country wins; unavailable or unsupported location falls back worldwide.","schema":{"type":"boolean","default":false,"description":"Use country supplied by a configured trusted hosting edge. No external IP lookup is made. Explicit country wins; unavailable or unsupported location falls back worldwide."}},{"name":"limit","in":"query","required":false,"description":"Number of guesses per page, from 1 to 50. Defaults to 10.","schema":{"type":"integer","minimum":1,"maximum":50,"default":10,"description":"Number of guesses per page, from 1 to 50. Defaults to 10."}},{"name":"details","in":"query","required":false,"description":"Include structured name parts, applied filters, coverage, and username parsing. Omit for just names and nextCursor.","schema":{"type":"boolean","default":false,"description":"Include structured name parts, applied filters, coverage, and username parsing. Omit for just names and nextCursor."}},{"name":"cursor","in":"query","required":false,"description":"Opaque nextCursor from the previous response. Keep all search filters unchanged; limit may change. Start again after a data/model update.","schema":{"type":"string","minLength":1,"maxLength":2048,"description":"Opaque nextCursor from the previous response. Keep all search filters unchanged; limit may change. Start again after a data/model update."}}],"responses":{"200":{"description":"Names and nextCursor by default; structured details when details=true. An empty array means no further matches.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/GuessResponse"},{"$ref":"#/components/schemas/DetailedGuessResponse"}]}}}},"400":{"description":"Invalid input or an invalid/expired cursor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"408":{"description":"Request body did not arrive within five seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request or query exceeds 4096 bytes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Ranking or username segmentation exceeded its work budget. Start a new search, use a shorter username, or different initials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request allowance exhausted. Shared with the website; 12 per 10 seconds, 60 per minute, and 1,000 per day per client. Service-wide caps also apply.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"The server could not complete the guess.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Rate limiting is unavailable; guessing is temporarily suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}}}}},"post":{"operationId":"guessNamesFromJson","summary":"Guess names from a JSON request","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GuessRequest"}}}},"responses":{"200":{"description":"Same response as GET.","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/GuessResponse"},{"$ref":"#/components/schemas/DetailedGuessResponse"}]}}}},"400":{"description":"Invalid input or an invalid/expired cursor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"408":{"description":"Request body did not arrive within five seconds.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"Request or query exceeds 4096 bytes.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"415":{"description":"Use Content-Type: application/json.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Ranking or username segmentation exceeded its work budget. Start a new search, use a shorter username, or different initials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Request allowance exhausted. Shared with the website; 12 per 10 seconds, 60 per minute, and 1,000 per day per client. Service-wide caps also apply.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}}},"500":{"description":"The server could not complete the guess.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Rate limiting is unavailable; guessing is temporarily suspended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}}}}}},"/api/v1/options":{"get":{"operationId":"getOptions","summary":"Supported countries, filters, defaults, and limits","responses":{"200":{"description":"Available settings and request allowances, with a link to coverage and source credits.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Options"}}}}}}}},"components":{"schemas":{"UsernameSegment":{"type":"object","additionalProperties":false,"required":["role","kind","text","value"],"properties":{"role":{"type":"string","enum":["first","middle","last"]},"kind":{"type":"string","enum":["name","initial","prefix"]},"text":{"type":"string"},"value":{"type":"string"}}},"UsernameReading":{"type":"object","additionalProperties":false,"required":["value","status","segments","ignoredNumbers","unparsed","ambiguous","alternatives"],"description":"Experimental dictionary interpretation, not an identified person. Only the selected segmentation is expanded into guesses; short fused name fragments can return both literal names and longer prefix completions. Explicitly separated full names stay fixed. Alternatives expose other segmentations. No age/sex is inferred from the handle. Missing first/surname fields stay empty.","properties":{"value":{"type":"string"},"status":{"type":"string","enum":["parsed","partial","unmatched"]},"segments":{"type":"array","maxItems":4,"items":{"$ref":"#/components/schemas/UsernameSegment"}},"ignoredNumbers":{"type":"array","items":{"type":"string"}},"unparsed":{"type":"array","items":{"type":"string"}},"ambiguous":{"type":"boolean"},"alternatives":{"type":"array","maxItems":3,"items":{"type":"object","additionalProperties":false,"required":["segments"],"properties":{"segments":{"type":"array","items":{"$ref":"#/components/schemas/UsernameSegment"}}}}}}},"GuessRequest":{"type":"object","additionalProperties":false,"oneOf":[{"required":["initials"]},{"required":["username"]}],"properties":{"initials":{"type":"string","minLength":2,"maxLength":32,"description":"Send initials or username. 2–4 initials; spaces, periods, and hyphens are allowed. Unicode letters are supported.","example":"JRB"},"username":{"type":"string","minLength":2,"maxLength":65,"description":"Experimental alternative to initials. 2–64 characters, with an optional leading @. Recognizes complete names, initials, and anchored prefixes. First-name-only readings add a source-weighted surname guess. Numbers are ignored, never used to infer age.","example":"alexjsmith"},"country":{"type":"string","description":"Optional country code from /api/v1/options. Supported local combinations come first, followed by worldwide alternatives when exhausted. Omit for worldwide names; codes are case-insensitive.","example":"CA"},"order":{"type":"string","enum":["first-last","last-first"],"default":"first-last","description":"The order of the initials or username components. Last-first means last, first, then any middle names or initials."},"sex":{"type":"string","enum":["any","female","male"],"default":"any","description":"Name style hint: female favors feminine-associated names; male favors masculine-associated names. Not an identity prediction."},"ageGroup":{"type":"string","enum":["any","under-30","30-59","60-plus"],"default":"any","description":"Optional birth-cohort hint: any, under-30, 30-59, or 60-plus. Coverage varies by country and birth year; see /data."},"useLocation":{"type":"boolean","default":false,"description":"Use country supplied by a configured trusted hosting edge. No external IP lookup is made. Explicit country wins; unavailable or unsupported location falls back worldwide."},"limit":{"type":"integer","minimum":1,"maximum":50,"default":10,"description":"Number of guesses per page, from 1 to 50. Defaults to 10."},"details":{"type":"boolean","default":false,"description":"Include structured name parts, applied filters, coverage, and username parsing. Omit for just names and nextCursor."},"cursor":{"type":"string","minLength":1,"maxLength":2048,"description":"Opaque nextCursor from the previous response. Keep all search filters unchanged; limit may change. Start again after a data/model update."}}},"Guess":{"type":"object","additionalProperties":false,"required":["name","first","middle","last"],"properties":{"name":{"type":"string"},"first":{"type":"string","description":"Empty when a username supplies only a surname."},"middle":{"type":"array","items":{"type":"string"},"maxItems":2},"last":{"type":"string","description":"Empty when a username supplies only a given name."}}},"GuessResponse":{"type":"object","additionalProperties":false,"required":["guesses","nextCursor"],"properties":{"guesses":{"type":"array","maxItems":50,"items":{"type":"string"},"description":"Full names in ranked order. An explicit country puts supported local combinations before worldwide alternatives."},"nextCursor":{"type":["string","null"],"description":"Send as cursor with unchanged filters. Null means exhausted. Page size and details may change."}}},"DetailedGuessResponse":{"type":"object","additionalProperties":false,"required":["initials","order","country","sex","ageGroup","locationSource","guesses","pagination","dataVersion","notice"],"properties":{"initials":{"type":"string","description":"Normalized initials in the requested order."},"username":{"$ref":"#/components/schemas/UsernameReading"},"order":{"type":"string","enum":["first-last","last-first"],"default":"first-last","description":"The order of the initials or username components. Last-first means last, first, then any middle names or initials."},"country":{"type":["string","null"],"description":"Effective country, or null for worldwide."},"sex":{"type":"string","enum":["any","female","male"],"default":"any","description":"Name style hint: female favors feminine-associated names; male favors masculine-associated names. Not an identity prediction."},"ageGroup":{"type":"string","enum":["any","under-30","30-59","60-plus"],"default":"any","description":"Optional birth-cohort hint: any, under-30, 30-59, or 60-plus. Coverage varies by country and birth year; see /data."},"locationSource":{"type":"string","enum":["manual","edge","none"]},"guesses":{"type":"array","maxItems":50,"items":{"$ref":"#/components/schemas/Guess"},"description":"Ranked within each tier: supported local combinations first, then worldwide alternatives. Model scores are not identity confidence and are not exposed."},"pagination":{"type":"object","required":["limit","nextCursor"],"additionalProperties":false,"properties":{"limit":{"type":"integer","minimum":1,"maximum":50,"default":10,"description":"Number of guesses per page, from 1 to 50. Defaults to 10."},"nextCursor":{"type":["string","null"],"description":"Send as cursor with unchanged filters. Null means exhausted. Page size may change."}}},"ageCoverage":{"type":"object","required":["countries","countryCovered"],"additionalProperties":false,"description":"Present when an age group is selected. Ontario, British Columbia and Alberta form a regional Canadian proxy.","properties":{"countries":{"type":"array","items":{"type":"string"}},"countryCovered":{"type":"boolean"}}},"dataVersion":{"type":"string","description":"Data build identifier. Cursors also expire when the model or cohort year changes."},"notice":{"type":"string","const":"For fun. Data is flawed and incomplete; these are guesses, not identities."}}},"Options":{"type":"object","required":["name","version","notice","countries","ageGroups","sexes","orders","defaults","limits","data"],"properties":{"name":{"type":"string","const":"Nomancy"},"version":{"type":"string","const":"1.2.0"},"notice":{"type":"string","const":"For fun. Data is flawed and incomplete; these are guesses, not identities."},"countries":{"type":"array","items":{"type":"object","required":["code","name"],"properties":{"code":{"type":"string"},"name":{"type":"string"}}}},"ageGroups":{"type":"array","items":{"type":"object","required":["id","label"],"properties":{"id":{"type":"string","enum":["any","under-30","30-59","60-plus"]},"label":{"type":"string"}}}},"sexes":{"type":"array","items":{"type":"string","enum":["any","female","male"]}},"orders":{"type":"array","items":{"type":"string","enum":["first-last","last-first"]}},"defaults":{"type":"object","required":["order","sex","ageGroup","useLocation","limit","details"],"properties":{"order":{"type":"string","enum":["first-last","last-first"],"default":"first-last","description":"The order of the initials or username components. Last-first means last, first, then any middle names or initials."},"sex":{"type":"string","enum":["any","female","male"],"default":"any","description":"Name style hint: female favors feminine-associated names; male favors masculine-associated names. Not an identity prediction."},"ageGroup":{"type":"string","enum":["any","under-30","30-59","60-plus"],"default":"any","description":"Optional birth-cohort hint: any, under-30, 30-59, or 60-plus. Coverage varies by country and birth year; see /data."},"useLocation":{"type":"boolean","default":false,"description":"Use country supplied by a configured trusted hosting edge. No external IP lookup is made. Explicit country wins; unavailable or unsupported location falls back worldwide."},"limit":{"type":"integer","minimum":1,"maximum":50,"default":10,"description":"Number of guesses per page, from 1 to 50. Defaults to 10."},"details":{"type":"boolean","default":false,"description":"Include structured name parts, applied filters, coverage, and username parsing. Omit for just names and nextCursor."}}},"limits":{"type":"object","required":["minInitials","maxInitials","maxUsernameLength","maxPageSize","maxRequestBytes","requestRates"],"properties":{"minInitials":{"type":"integer","const":2},"maxInitials":{"type":"integer","const":4},"maxUsernameLength":{"type":"integer","const":64},"maxPageSize":{"type":"integer","const":50},"maxRequestBytes":{"type":"integer","const":4096},"requestRates":{"type":"array","items":{"type":"object","required":["scope","limit","seconds"],"properties":{"scope":{"type":"string","enum":["client","service"]},"limit":{"type":"integer","minimum":1},"seconds":{"type":"integer","minimum":1}}}}}},"data":{"type":"object","required":["attributionUrl"],"properties":{"attributionUrl":{"type":"string","description":"Path to coverage notes, source credits, and licence qualifications."}}}}},"Error":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message"],"properties":{"code":{"type":"string","enum":["invalid_request","invalid_json","invalid_cursor","request_timeout","request_too_large","search_too_complex","unsupported_media_type","rate_limited","service_unavailable","internal_error"]},"message":{"type":"string"}}}}}}}}