{"openapi":"3.1.0","info":{"title":"GovReady AI Governance Companion","version":"1.0.0","description":"Free EU AI Act navigator, AI tool risk checker, governance maturity audit. Every regulatory claim returns citations to EUR-Lex (CELEX 32024R1689) and to the Future of Life Institute's Article Explorer. By GovReady.","contact":{"name":"GovReady","url":"https://governanceready.com","email":"hello@governanceready.com"},"license":{"name":"Free use, attribution appreciated"}},"servers":[{"url":"https://companion.governanceready.com/api/v1","description":"Production"}],"components":{"schemas":{"Locale":{"type":"string","description":"BCP-47 language tag. Native: 'en', 'sk'. Other EU locales fall back to the nearest anchor.","example":"en"},"Citation":{"type":"object","properties":{"label":{"type":"string"},"tier":{"type":"integer"},"primary_law_url":{"type":"string","format":"uri"},"primary_law_locale_url":{"type":"string","format":"uri"},"primary_law_summary":{"type":"string","description":"Paraphrased summary of the law (always treat as guidance)."},"primary_law_summary_locale":{"type":"string"},"primary_law_excerpt":{"type":"string","description":"Verbatim legal text (only when excerpt_kind = 'verbatim')."},"primary_law_excerpt_locale":{"type":"string"},"primary_law_excerpt_kind":{"type":"string","enum":["summary","verbatim"]},"analysis_url":{"type":"string","format":"uri"},"analysis_publisher":{"type":"string"},"verified_at":{"type":"string"}}}}},"paths":{"/health":{"get":{"operationId":"health","summary":"Health check","description":"Returns OK when the service is up. No side effects.","responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"type":"object","properties":{"status":{"type":"string","example":"ok"},"timestamp":{"type":"string","format":"date-time"}}}}}}}}},"/navigator/classify":{"post":{"operationId":"classifyUseCase","summary":"Classify an AI use case under the EU AI Act","description":"Returns the AI Act risk class (prohibited / high / limited / minimal / gpai), applicable Articles, concrete obligations, phased compliance timeline, and citations.","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["description"],"properties":{"description":{"type":"string","description":"One- or two-sentence description of the AI use case.","example":"An AI tool that screens CVs and ranks candidates for an HR team."},"sector":{"type":"string","description":"Industry sector (e.g., HR, healthcare, finance, public sector)."},"deployment_context":{"type":"string","description":"Where and how the system is deployed (e.g., 'EU-wide SaaS', 'internal hospital tool')."},"locale":{"$ref":"#/components/schemas/Locale"}}}}}},"responses":{"200":{"description":"Classification result"}}}},"/navigator/article/{id}":{"get":{"operationId":"getArticle","summary":"Fetch annotated EU AI Act Article","description":"Returns the Article with chapter/section, plain-language summary, paraphrased excerpt and citations.","parameters":[{"name":"id","in":"path","required":true,"description":"Article identifier in the form 'art-N' (e.g., art-9).","schema":{"type":"string","pattern":"^art-\\d+$","example":"art-9"}},{"name":"locale","in":"query","required":false,"description":"Response language. Defaults to 'en'.","schema":{"$ref":"#/components/schemas/Locale"}}],"responses":{"200":{"description":"Article"}}}},"/navigator/term/{term}":{"get":{"operationId":"lookupTerm","summary":"Look up an EU AI Act glossary term","parameters":[{"name":"term","in":"path","required":true,"description":"Glossary key (e.g., 'high_risk_ai', 'gpai', 'provider').","schema":{"type":"string","example":"high_risk_ai"}},{"name":"locale","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Locale"}}],"responses":{"200":{"description":"Glossary term and citations"}}}},"/navigator/overlap":{"post":{"operationId":"regulatoryOverlap","summary":"Cross-reference the AI Act with GDPR / NIS2 / DORA / MDR","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["use_case","frameworks"],"properties":{"use_case":{"type":"string","example":"AI tool that screens CVs for an HR team"},"frameworks":{"type":"array","minItems":1,"items":{"type":"string","enum":["gdpr","nis2","dora","mdr"]},"example":["gdpr"]},"locale":{"$ref":"#/components/schemas/Locale"}}}}}},"responses":{"200":{"description":"Overlap analysis"}}}},"/navigator/sources":{"get":{"operationId":"listSources","summary":"List authoritative sources used by the Companion","parameters":[{"name":"tier","in":"query","required":false,"description":"Filter by source tier (1 = primary law, 2 = official authority, 3 = analysis, 4 = standard, 5 = member-state).","schema":{"type":"integer","minimum":1,"maximum":5}}],"responses":{"200":{"description":"Sources"}}}},"/tools/lookup":{"get":{"operationId":"lookupTool","summary":"Look up an AI tool by name and return its compliance profile","parameters":[{"name":"name","in":"query","required":true,"description":"Common name of the AI tool (e.g., 'ChatGPT', 'Microsoft Copilot', 'Cursor').","schema":{"type":"string","example":"ChatGPT"}},{"name":"locale","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Locale"}}],"responses":{"200":{"description":"Tool compliance profile"}}}},"/tools/workflow":{"post":{"operationId":"analyzeWorkflow","summary":"Analyse an AI workflow involving multiple tools","x-openai-isConsequential":false,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["description"],"properties":{"description":{"type":"string","description":"Description of the end-to-end AI workflow (which tools, which data, which decisions).","example":"We use ChatGPT to draft customer replies, then Copilot writes them in M365, then approval is automatic."},"locale":{"$ref":"#/components/schemas/Locale"}}}}}},"responses":{"200":{"description":"Workflow analysis"}}}},"/tools/categories":{"get":{"operationId":"listToolCategories","summary":"List the AI tool taxonomy categories","parameters":[{"name":"locale","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Locale"}}],"responses":{"200":{"description":"Tool categories"}}}},"/tools/vendor-questions":{"get":{"operationId":"vendorDueDiligence","summary":"Get vendor due-diligence questions, optionally for a tool category","parameters":[{"name":"category","in":"query","required":false,"description":"Tool category id (e.g., 'general_chat', 'workspace_ai', 'code_generation'). Empty = all.","schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"schema":{"$ref":"#/components/schemas/Locale"}}],"responses":{"200":{"description":"Vendor due-diligence questions"}}}},"/audit/start":{"post":{"operationId":"startAudit","summary":"Start a 12-question governance maturity audit","requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"locale":{"$ref":"#/components/schemas/Locale"}},"example":{"locale":"en"}}}}},"responses":{"200":{"description":"First question and session_id"}}}},"/audit/answer":{"post":{"operationId":"submitAuditAnswer","summary":"Submit one answer to the audit; returns next question or done=true","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["session_id","question_id","answer"],"properties":{"session_id":{"type":"string","format":"uuid"},"question_id":{"type":"string","example":"policy-formal"},"answer":{"type":"string","description":"Option id (typically 'a', 'b', 'c', or 'd').","example":"a"}}}}}},"responses":{"200":{"description":"Next question or final result"}}}},"/audit/result/{id}":{"get":{"operationId":"getAuditResult","summary":"Fetch the result of a completed audit by session id","parameters":[{"name":"id","in":"path","required":true,"description":"Session id returned from /audit/start.","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Audit result"}}}},"/audit/email-pdf":{"post":{"operationId":"emailAuditPdf","summary":"Send the audit result as a PDF (lead capture, requires explicit consents)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["session_id","email","name","consent_terms","consent_gdpr"],"properties":{"session_id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"company":{"type":"string"},"locale":{"$ref":"#/components/schemas/Locale"},"consent_terms":{"type":"boolean","description":"Must be true."},"consent_gdpr":{"type":"boolean","description":"Must be true."},"consent_marketing":{"type":"boolean"}}}}}},"responses":{"200":{"description":"Email queued / sent"}}}},"/verify/{reference}":{"get":{"operationId":"verifyCertificate","summary":"Verify a GovReady public certificate by reference","parameters":[{"name":"reference","in":"path","required":true,"description":"Certificate reference (e.g., 'AEG-2026-0042').","schema":{"type":"string","example":"AEG-2026-0042"}}],"responses":{"200":{"description":"Verification result"}}}},"/waitlist":{"post":{"operationId":"languageWaitlist","summary":"Join the waitlist for native locale support (Tier C languages)","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","locale"],"properties":{"email":{"type":"string","format":"email"},"locale":{"$ref":"#/components/schemas/Locale"}},"example":{"email":"user@example.com","locale":"de"}}}}},"responses":{"200":{"description":"Waitlist accepted"}}}},"/feedback":{"post":{"operationId":"submitFeedback","summary":"Submit a 1-5 rating for the answer just received","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["session_id","tool_name","rating"],"properties":{"session_id":{"type":"string","description":"Any session id from earlier in the conversation."},"tool_name":{"type":"string","description":"The tool that produced the answer (e.g., 'classify_use_case')."},"rating":{"type":"integer","minimum":1,"maximum":5},"comment":{"type":"string"}}}}}},"responses":{"200":{"description":"Feedback stored"}}}}}}