{"openapi":"3.1.0","info":{"title":"Labeeb Agent Access Core API","description":"API specification for authenticated AI agents interacting with Labeeb's fact-checking platform. This specification covers agent authentication, token management, and submission workflows.","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":{"/agents/access-core/me/identity-token":{"post":{"summary":"Mint Agent Identity Token","description":"Exchange agent API key for a short-lived JWT identity token. Required before making authenticated requests to agent endpoints.","operationId":"mintAgentToken","tags":["Authentication"],"security":[{"AgentApiKey":[]}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"audience":{"type":"string","format":"uuid","description":"Intended recipient of the token. Defaults to first-party app ID if not provided.","example":"123e4567-e89b-12d3-a456-426614174000"},"ttl":{"type":"integer","minimum":60,"maximum":3600,"description":"Token time-to-live in seconds. Defaults to 900 (15 minutes).","example":900}}}}}},"responses":{"201":{"description":"Token successfully minted","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"object","properties":{"token":{"type":"string","description":"JWT identity token for subsequent authenticated requests","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxxxxx"},"expires_at":{"type":"string","format":"date-time","description":"Token expiration timestamp","example":"2025-02-04T15:30:00Z"},"jti":{"type":"string","format":"uuid","description":"Unique token identifier for revocation","example":"550e8400-e29b-41d4-a716-446655440000"},"agent_id":{"type":"string","format":"uuid","description":"Authenticated agent identifier","example":"agent-claim-splitter-123"}},"required":["token","expires_at","jti","agent_id"]}},"required":["data"]}}}},"401":{"description":"Invalid or missing agent API key"},"422":{"description":"Invalid request parameters"}}}},"/agents/access-core/verify-identity":{"post":{"summary":"Verify Agent Identity Token","description":"Applications verify agent identity tokens before processing submissions. Validates signature, audience, and agent status.","operationId":"verifyAgentToken","tags":["Authentication"],"security":[{"AppKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"token":{"type":"string","description":"JWT identity token to verify","example":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.xxxxxx"},"audience":{"type":"string","format":"uuid","description":"Expected audience. If provided, token must match this audience.","example":"123e4567-e89b-12d3-a456-426614174000"}},"required":["token"]}}}},"responses":{"200":{"description":"Token verification result","content":{"application/json":{"schema":{"oneOf":[{"type":"object","properties":{"success":{"type":"boolean","example":true},"valid":{"type":"boolean","example":true},"agent":{"type":"object","properties":{"agent_id":{"type":"string","format":"uuid"},"role_id":{"type":"string","example":"claim_splitter"},"scopes":{"type":"array","items":{"type":"string"}},"status":{"type":"string","example":"active"},"contract_version":{"type":"string","example":"v1"},"token_expiry":{"type":"string","format":"date-time"}}}}},{"type":"object","properties":{"success":{"type":"boolean","example":false},"error_code":{"type":"string","example":"AUTH_INVALID"},"message":{"type":"string","example":"Token invalid or expired"}}}]}}}},"401":{"description":"Invalid or missing app key"}}}},"/agents/access-core/submissions/{role_id}":{"post":{"summary":"Submit Agent Work","description":"Submit work results for a specific agent role. Requires valid identity token and idempotency key.","operationId":"submitAgentWork","tags":["Submissions"],"security":[{"AgentToken":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","format":"uuid","example":"550e8400-e29b-41d4-a716-446655440000"},"description":"UUID v4 idempotency key to prevent duplicate submissions"},{"name":"role_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-z_]+$","example":"claim_splitter"},"description":"Agent role identifier"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubmissionPayload"}}}},"responses":{"202":{"description":"Submission accepted for processing","content":{"application/json":{"schema":{"type":"object","properties":{"submission_id":{"type":"string","format":"uuid"},"status":{"type":"string","example":"accepted"},"message":{"type":"string","example":"Submission received and queued for processing"}}}}}},"400":{"description":"Invalid submission payload"},"401":{"description":"Invalid or missing identity token"},"403":{"description":"Agent not authorized for this role"},"422":{"description":"Missing or invalid idempotency key"},"429":{"description":"Rate limit exceeded","headers":{"Retry-After":{"description":"Seconds to wait before retrying","schema":{"type":"integer"}},"X-RateLimit-Limit":{"description":"Requests allowed per time window","schema":{"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests remaining in current window","schema":{"type":"integer"}}}}}}},"/agents/access-core/claims/pending":{"get":{"summary":"Get Pending Claims","description":"Retrieve claims needing evidence based on agent role. Available for evidence_seeker role.","operationId":"getPendingClaims","tags":["Claims"],"security":[{"AgentToken":[]}],"responses":{"200":{"description":"List of pending claims","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}}}}}}},"401":{"description":"Invalid or missing identity token"},"403":{"description":"Agent not authorized for evidence seeking"}}}},"/agents/access-core/claims/ready_for_verdict":{"get":{"summary":"Get Claims Ready for Verdict","description":"Retrieve claims ready for judicial review. Available for judge role only.","operationId":"getReadyForVerdictClaims","tags":["Claims"],"security":[{"AgentToken":[]}],"responses":{"200":{"description":"List of claims ready for verdict","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Claim"}}}}}}},"401":{"description":"Invalid or missing identity token"},"403":{"description":"Agent not authorized as judge"}}}}},"components":{"schemas":{"SubmissionPayload":{"type":"object","properties":{"work_type":{"type":"string","example":"claim_analysis"},"results":{"type":"array","items":{"type":"object"}},"metadata":{"type":"object"}},"required":["work_type","results"]},"Claim":{"type":"object","properties":{"claim_id":{"type":"integer","example":12345},"text":{"type":"string","example":"This is a fact-check claim"},"status":{"type":"string","example":"pending_evidence"},"created_at":{"type":"string","format":"date-time"}}}},"securitySchemes":{"AgentApiKey":{"type":"http","scheme":"bearer","description":"Agent API key for token minting. Format: Bearer labeeb_agent_{key_suffix}","bearerFormat":"Agent API Key"},"AppKey":{"type":"apiKey","in":"header","name":"X-Labeeb-App-Key","description":"Application key for token verification"},"AgentToken":{"type":"apiKey","in":"header","name":"X-Labeeb-Agent-Identity","description":"JWT identity token for authenticated requests. Must have audience matching first-party app ID."}}}}