{"openapi":"3.1.0","info":{"title":"NamingSignal API","version":"0.2.0-preview","description":"Evidence-first naming brief, generation, domain/namespace checking, and finalist research. Registry not-found is not a purchase guarantee; trademark output is preliminary research only."},"externalDocs":{"description":"Public developer quickstart, key management, and agent setup prompt","url":"https://namingsignal.com/developers/docs"},"servers":[{"url":"https://namingsignal.com/"}],"security":[{"bearerAuth":[]}],"paths":{"/api/v1/health":{"get":{"operationId":"getHealth","summary":"Read provider readiness and applied policy limits","security":[],"responses":{"200":{"description":"Bounded JSON response with evidence, usage, and stable error fields where applicable.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/api/v1/brief":{"post":{"operationId":"compileBrief","summary":"Compile bounded project context into an editable naming brief","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Bounded JSON response with evidence, usage, and stable error fields where applicable.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/generate":{"post":{"operationId":"generateCandidates","summary":"Generate 4–50 candidates for one bounded batch","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["brief"],"properties":{"brief":{"type":"object","additionalProperties":true},"count":{"type":"integer","minimum":4,"maximum":50},"tlds":{"type":"array","minItems":1,"maxItems":5,"items":{"type":"string"}},"checkPrimaryDomain":{"type":"boolean","default":true},"excludedNames":{"type":"array","maxItems":500,"items":{"type":"string","minLength":2,"maxLength":32}},"iteration":{"type":"object","description":"Optional founder feedback for a new, non-duplicate round inside an existing naming project.","required":["feedback"],"properties":{"feedback":{"type":"string","minLength":1,"maxLength":2000},"likedNames":{"type":"array","maxItems":30,"items":{"type":"string","minLength":2,"maxLength":32}},"dislikedNames":{"type":"array","maxItems":30,"items":{"type":"string","minLength":2,"maxLength":32}}},"additionalProperties":false}},"additionalProperties":false}}}},"responses":{"200":{"description":"Bounded JSON response with evidence, usage, and stable error fields where applicable.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/check":{"post":{"operationId":"checkNames","summary":"Check and score names within the 150-domain-combination request cap","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Bounded JSON response with evidence, usage, and stable error fields where applicable.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/rank":{"post":{"operationId":"rankDomainSurvivors","summary":"Rank 2–30 domain survivors with an independent model and bounded fallback","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Bounded JSON response with evidence, usage, and stable error fields where applicable.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/v1/research":{"post":{"operationId":"researchFinalists","summary":"Research one to three finalists with explicit unknowns and manual actions","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"responses":{"200":{"description":"Bounded JSON response with evidence, usage, and stable error fields where applicable.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"429":{"$ref":"#/components/responses/RateLimited"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A user-owned NamingSignal API key created after sign-in at /developers/keys. Same-origin web calls may use the Clerk session instead."}},"responses":{"Unauthorized":{"description":"Missing, invalid, revoked, or unsupported credential. Create a user API key at /developers/keys and send it in the Authorization Bearer header.","headers":{"WWW-Authenticate":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"The account burst limit or monthly Naming Credit allowance was exceeded.","headers":{"Retry-After":{"schema":{"type":"integer"}},"X-RateLimit-Limit":{"schema":{"type":"integer"}},"X-RateLimit-Remaining":{"schema":{"type":"integer"}},"X-RateLimit-Reset":{"schema":{"type":"string","format":"date-time"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Error":{"description":"Safe error envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["error","code","retryable"],"properties":{"error":{"type":"string"},"code":{"type":"string"},"retryable":{"type":"boolean"},"retryAfterSeconds":{"type":"integer","minimum":0},"resetAt":{"type":"string","format":"date-time"}}}}}}