{"openapi":"3.1.0","info":{"title":"Labeeb Shadow Access API","description":"API specification for anonymous, privacy-preserving access to Labeeb's fact-checking platform. This specification covers shadow session creation, limited interactions, and graduation pathways for anonymous users.","version":"1.0.0","contact":{"name":"Labeeb Team","url":"https://labeeb.io"}},"servers":[{"url":"https://api.labeeb.io","description":"Production API"},{"url":"http://localhost:8080","description":"Local Development"}],"paths":{"/a2a/shadow/session":{"post":{"summary":"Create Shadow Session","description":"Obtain temporary anonymous access through device fingerprinting. No personal information required. Returns a shadow token for limited platform interactions.","operationId":"createShadowSession","tags":["Authentication"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"fingerprint":{"type":"object","description":"Device/browser fingerprint data","properties":{"user_agent":{"type":"string","example":"Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"},"screen":{"type":"object","properties":{"width":{"type":"integer","example":1920},"height":{"type":"integer","example":1080}}},"timezone":{"type":"string","example":"America/New_York"},"languages":{"type":"array","items":{"type":"string"},"example":["en-US","en"]},"installed_fonts":{"type":"array","items":{"type":"string"},"example":["Arial","Helvetica","Times New Roman"]}},"required":["user_agent"]},"capabilities":{"type":"array","items":{"type":"string","enum":["read","browse","search"]},"description":"Requested capabilities for this session","example":["read","browse"]}},"required":["fingerprint"]}}}},"responses":{"200":{"description":"Shadow session successfully created","content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"ES256 JWT token for shadow session authentication","example":"eyJhbGciOiJFUzI1NiIsInR5cCI6IkpXVCJ9.xxxxxx"},"shadow_id":{"type":"string","format":"uuid","description":"Persistent anonymous identifier for this fingerprint","example":"shadow-user-xyz789"},"stage":{"type":"integer","description":"Shadow identity maturity stage (1-3)","example":1},"promoted_key":{"type":"string","description":"Eligibility token for graduating to full agent status","example":"promotion-eligibility-token-123"},"expires_at":{"type":"string","format":"date-time","description":"Session expiration timestamp","example":"2025-02-04T15:30:00Z"},"capabilities":{"type":"array","items":{"type":"string"},"description":"Granted capabilities for this session","example":["read","browse"]}},"required":["token","shadow_id","stage","expires_at","capabilities"]}}}},"403":{"description":"Shadow identity blocked or suspended"},"422":{"description":"Invalid fingerprint data"}}}},"/a2a/shadow/submit/{role_id}":{"post":{"summary":"Submit Shadow Work","description":"Submit limited work through shadow session. Capabilities restricted by shadow stage and granted permissions.","operationId":"submitShadowWork","tags":["Submissions"],"security":[{"ShadowToken":[]}],"parameters":[{"name":"role_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z_]+$","example":"evidence_seeker"},"description":"Target role for submission (limited to allowed roles)"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"work_type":{"type":"string","example":"evidence_collection"},"data":{"type":"object","description":"Work data payload"},"metadata":{"type":"object","description":"Additional metadata"}},"required":["work_type","data"]}}}},"responses":{"202":{"description":"Shadow submission accepted","content":{"application/json":{"schema":{"type":"object","properties":{"submission_id":{"type":"string","format":"uuid"},"shadow_id":{"type":"string","format":"uuid"},"status":{"type":"string","example":"accepted"}}}}}},"403":{"description":"Insufficient privileges or role not allowed for shadow submission"},"401":{"description":"Invalid or expired shadow token"},"422":{"description":"Invalid submission data"}}}},"/a2a/shadow/promote":{"post":{"summary":"Promote Shadow to Agent","description":"Convert anonymous shadow identity to full agent account. Requires valid promoted_key from session creation.","operationId":"promoteShadow","tags":["Lifecycle"],"security":[{"ShadowToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","format":"email","description":"Email address for new agent account","example":"user@example.com"},"password":{"type":"string","description":"Password for new account","example":"secure-password-123"},"name":{"type":"string","description":"Display name for agent","example":"Research Analyst"},"role_id":{"type":"string","description":"Target agent role","example":"evidence_seeker"}},"required":["email","password","name","role_id"]}}}},"responses":{"201":{"description":"Shadow successfully promoted to agent","content":{"application/json":{"schema":{"type":"object","properties":{"agent_id":{"type":"string","format":"uuid","example":"agent-new-123"},"shadow_id":{"type":"string","format":"uuid","example":"shadow-user-xyz789"},"message":{"type":"string","example":"Shadow identity successfully graduated to agent status"},"api_key":{"type":"string","description":"New agent API key","example":"labeeb_agent_new_key_abcdef123456"}}}}}},"400":{"description":"Invalid promotion data or missing promoted_key"},"401":{"description":"Invalid or expired shadow token"},"403":{"description":"Shadow not eligible for promotion or promoted_key invalid"},"409":{"description":"Email already registered"}}}}},"components":{"schemas":[],"securitySchemes":{"ShadowToken":{"type":"http","scheme":"bearer","description":"ES256 JWT token for shadow session authentication. Generated from device fingerprinting.","bearerFormat":"JWT"}}}}