{"openapi":"3.1.0","info":{"title":"Claimlight API","version":"1.1.0","description":"Provider-neutral evidence checking for writing surfaces. Verdicts describe available evidence rather than absolute truth."},"servers":[{"url":"/api/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/installations":{"post":{"security":[],"summary":"Create an anonymous installation credential","responses":{"201":{"description":"Installation created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Installation"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/installations/current":{"delete":{"summary":"Delete this installation and all Claimlight records","responses":{"204":{"description":"Installation data deleted"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/sessions":{"post":{"security":[],"summary":"Exchange an installation credential for a short-lived session","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Installation"}}}},"responses":{"200":{"description":"Session created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"426":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/checks":{"post":{"summary":"Classify a sentence and start evidence research","parameters":[{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCheck"}}}},"responses":{"200":{"$ref":"#/components/responses/Check"},"202":{"$ref":"#/components/responses/Check"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/checks/{id}":{"get":{"summary":"Read or poll a check","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$"}}],"responses":{"200":{"$ref":"#/components/responses/Check"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}},"delete":{"summary":"Cancel provider work and delete a check","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$"}}],"responses":{"204":{"description":"Deleted"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/checks/{id}/rewrite":{"post":{"summary":"Correct one claim in the author's voice","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RewriteRequest"}}}},"responses":{"200":{"description":"Rewrite generated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Rewrite"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/checks/{id}/feedback":{"post":{"summary":"Submit verdict or source feedback for one claim","parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string","pattern":"^[a-zA-Z0-9_-]+$"}},{"$ref":"#/components/parameters/IdempotencyKey"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Feedback"}}}},"responses":{"202":{"description":"Feedback accepted"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/configuration":{"get":{"security":[],"summary":"Read public adapter, version, and rollout configuration","responses":{"200":{"description":"Configuration"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"415":{"$ref":"#/components/responses/Error"},"422":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/health":{"get":{"security":[],"summary":"Liveness probe","responses":{"200":{"description":"Alive"}}}},"/ready":{"get":{"security":[],"summary":"Dependency readiness probe","responses":{"200":{"description":"Ready"},"503":{"description":"Degraded"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"Claimlight installation session"}},"parameters":{"IdempotencyKey":{"in":"header","name":"Idempotency-Key","required":true,"schema":{"type":"string","minLength":16,"maxLength":128}}},"responses":{"Check":{"description":"Current check state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Check"}}}},"Error":{"description":"Stable API error. Rate-limit responses also include Retry-After and X-RateLimit headers.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Installation":{"type":"object","additionalProperties":false,"required":["installationId","credential"],"properties":{"installationId":{"type":"string","example":"installation_92ef9178-1898-40df-a516-b43f86c5510e"},"credential":{"type":"string","minLength":40,"writeOnly":true}}},"Session":{"type":"object","required":["token","expiresAt"],"properties":{"token":{"type":"string"},"expiresAt":{"type":"string","format":"date-time"}}},"CreateCheck":{"type":"object","additionalProperties":false,"required":["sentenceId","sentence","documentRevision"],"properties":{"sentenceId":{"type":"string","maxLength":160},"sentence":{"type":"string","maxLength":2500},"documentRevision":{"type":"string","maxLength":160},"locale":{"type":"string","maxLength":32},"context":{"type":"string","maxLength":5000}}},"Check":{"type":"object","required":["id","status","classification","createdAt","expiresAt","results"],"properties":{"id":{"type":"string"},"status":{"$ref":"#/components/schemas/Status"},"classification":{"$ref":"#/components/schemas/Classification"},"createdAt":{"type":"string","format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"retryAfterMs":{"type":"integer"},"guidance":{"type":"string"},"results":{"type":"array","items":{"$ref":"#/components/schemas/ClaimResult"}},"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"ClaimResult":{"type":"object","required":["schemaVersion","checkId","sentenceId","claimId","claimText","classification","verdict","confidence","evidence","consultedSources"],"properties":{"schemaVersion":{"const":"1.1.0"},"checkId":{"type":"string"},"sentenceId":{"type":"string"},"claimId":{"type":"string"},"claimText":{"type":"string"},"normalizedClaim":{"type":"string"},"classification":{"$ref":"#/components/schemas/Classification"},"verdict":{"$ref":"#/components/schemas/Verdict"},"confidence":{"type":"number","minimum":0,"maximum":1},"explanation":{"type":"string"},"evidence":{"type":"array","items":{"$ref":"#/components/schemas/Evidence"}},"consultedSources":{"type":"array","items":{"$ref":"#/components/schemas/ConsultedSource"}},"suggestedCorrection":{"type":["string","null"]},"preservedVoiceRewrite":{"type":["string","null"]},"researchedAt":{"type":"string","format":"date-time"},"provider":{"type":"object","required":["name","model"],"properties":{"name":{"type":"string"},"model":{"type":"string"}}}}},"Evidence":{"type":"object","required":["id","title","publisher","url","relationship","sourceType","accessedAt"],"properties":{"id":{"type":"string"},"title":{"type":"string"},"publisher":{"type":"string"},"url":{"type":"string","format":"uri","pattern":"^https://"},"publishedAt":{"type":["string","null"]},"excerpt":{"type":"string","maxLength":500},"relationship":{"type":"string","enum":["supports","contradicts","contextualizes"]},"sourceType":{"type":"string","enum":["primary","secondary","unknown"]},"accessedAt":{"type":"string","format":"date-time"}}},"ConsultedSource":{"type":"object","required":["id","title","url","accessedAt"],"properties":{"id":{"type":"string"},"title":{"type":["string","null"]},"url":{"type":"string","format":"uri","pattern":"^https://"},"accessedAt":{"type":"string","format":"date-time"}}},"RewriteRequest":{"type":"object","additionalProperties":false,"required":["claimId"],"properties":{"claimId":{"type":"string"},"surroundingText":{"type":"string","maxLength":5000},"voiceSample":{"type":"string","maxLength":5000}}},"Rewrite":{"type":"object","required":["replacement","explanation"],"properties":{"replacement":{"type":"string"},"explanation":{"type":"string"}}},"Feedback":{"type":"object","additionalProperties":false,"required":["claimId","kind"],"properties":{"claimId":{"type":"string"},"kind":{"type":"string","enum":["verdict-helpful","verdict-unhelpful","source-helpful","source-unhelpful"]},"sourceId":{"type":"string"},"note":{"type":"string","maxLength":500}}},"Status":{"type":"string","enum":["queued","researching","completed","failed","cancelled","expired"]},"Verdict":{"type":"string","enum":["supported","contradicted","mixed","unverified"]},"Classification":{"type":"string","enum":["neutral","opinion","advice","factual-claim","needs-context"]},"Error":{"type":"object","required":["error"],"properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"}}},"ErrorDetail":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}