{"openapi":"3.1.0","info":{"title":"PII Shield Detection API","version":"1.0.0","description":"Detect personal information (PII) in text and get a block/allow decision. Hosted in Canada (Toronto). Send text, receive detected entities, a severity, and should_block."},"servers":[{"url":"https://vervian-api.fly.dev","description":"Production"}],"paths":{"/pii/v1/detect":{"post":{"summary":"Detect PII in text","operationId":"detect","security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetectRequest"},"examples":{"simple":{"value":{"text":"John Smith, SSN 123-45-6789"}}}}}},"responses":{"200":{"description":"Detection result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DetectResponse"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key"}},"schemas":{"DetectRequest":{"type":"object","properties":{"text":{"type":"string","description":"The text to scan. Max 50000 chars for API keys."},"conversationId":{"type":"string","description":"Optional. Enables cross-message accumulation when session tracking is on."},"guardrailTerms":{"type":"array","description":"Optional custom terms to always block.","items":{"type":"object","properties":{"term":{"type":"string"}}}}},"required":["text"]},"DetectResponse":{"type":"object","properties":{"request_id":{"type":"string"},"should_block":{"type":"boolean","description":"The single authoritative block/allow decision."},"severity":{"type":"string","enum":["none","low","medium","high"]},"total_score":{"type":"number"},"threshold":{"type":"number"},"entities":{"type":"array","items":{"$ref":"#/components/schemas/Entity"}},"triggered_combos":{"type":"array","items":{"type":"object"}},"session_state":{"type":"string","enum":["disabled","active","degraded","no-conversation","no-auth"]},"applied_laws":{"type":"array","items":{"type":"string"},"description":"Always empty until the law engine ships (piishield#171/#172)."},"detector_error":{"type":"string","description":"Present only when the detector reply was unreadable and the request failed closed."},"processing_time_ms":{"type":"number"}},"required":["request_id","should_block","severity","total_score","threshold","entities"]},"Entity":{"type":"object","properties":{"entity_id":{"type":"string","description":"Internal registry id, e.g. E055."},"type":{"type":"string","description":"Entity type, e.g. SSN."},"text":{"type":"string","description":"The detected substring."},"span":{"type":["array","null"],"items":{"type":"integer"},"description":"Best-effort [start, end] character offsets in the input, or null."},"category":{"type":"string"},"severity":{"type":"string"},"weight":{"type":"number"}}},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"}},"required":["code","message"]}}}},"responses":{"Error":{"description":"Error envelope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}