{"openapi":"3.1.0","info":{"title":"Security Flare JSON API","summary":"Read your ISO/IEC 27001:2022 control catalogue and per-tenant readiness state over HTTPS.","description":"Public reads (no auth) plus a sketch of the cookie-bound authenticated surface. Companion human-readable docs at /api-docs.","version":"1.0.0","contact":{"name":"Security Flare","email":"hello@securityflare.com.au"},"license":{"name":"Proprietary — see /terms","url":"https://app.securityflare.com.au/terms"}},"servers":[{"url":"https://app.securityflare.com.au","description":"Production"}],"tags":[{"name":"Catalogue","description":"Public reads of the ISO 27001:2022 Annex A controls."},{"name":"Authenticated registers","description":"Cookie-bound tenant-scoped CRUD. RLS keeps each tenant isolated."},{"name":"Exports","description":"Spreadsheet exports for auditor handoff. All require an authenticated session."},{"name":"Health","description":"Public service liveness probes."}],"paths":{"/healthz":{"get":{"tags":["Health"],"summary":"Liveness probe","description":"Returns 200 with body `ok` when the Worker is reachable. No DB/DO/Queue touched.","responses":{"200":{"description":"OK","content":{"text/plain":{"example":"ok"}}}}}},"/api/controls":{"get":{"tags":["Catalogue"],"summary":"List ISO 27001:2022 Annex A controls","description":"Returns the 93 Annex A controls — code, theme, name, purpose, automation tier, primary Microsoft product. Cached at the edge for 5 minutes.","parameters":[{"name":"theme","in":"query","description":"Filter to one Annex A theme.","schema":{"type":"string","enum":["Organizational","People","Physical","Technological"]}},{"name":"automation","in":"query","description":"Filter by automation tier — Automated (A), Partial (P), Manual (M).","schema":{"type":"string","enum":["A","P","M"]}},{"name":"new","in":"query","description":"When `true`, returns only the 11 controls newly introduced in the 2022 revision.","schema":{"type":"string","enum":["true"]}},{"name":"q","in":"query","description":"Substring search across code, name, purpose.","schema":{"type":"string","maxLength":80}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ControlList"}}}},"400":{"$ref":"#/components/responses/BadRequest"}}}},"/api/controls/{code}":{"get":{"tags":["Catalogue"],"summary":"Get one control by code","description":"Returns every column in the catalogue for the named control: purpose, ISO clauses cross-referenced, Essential 8 mapping, the Microsoft Graph endpoints used to evidence it.","parameters":[{"name":"code","in":"path","required":true,"description":"Annex A control code (e.g. `A.5.1`).","schema":{"type":"string","pattern":"^A\\.\\d+\\.\\d+$"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ControlDetail"}}}},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/risks/export.xlsx":{"get":{"tags":["Exports"],"summary":"Risk register export","description":"Streams the tenant's risk register as a single-sheet XLSX workbook. Filename includes ISO date. Cache-control private,no-store.","security":[{"sessionCookie":[]}],"responses":{"200":{"description":"OK; binary XLSX body.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/soa/export.xlsx":{"get":{"tags":["Exports"],"summary":"Statement of Applicability export","description":"Streams the tenant's live SoA derived from risk→control links as a single-sheet XLSX workbook. Filename includes ISO date. Cache-control private,no-store.","security":[{"sessionCookie":[]}],"responses":{"200":{"description":"OK; binary XLSX body.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/objectives/export.xlsx":{"get":{"tags":["Exports"],"summary":"§6.2 objectives export","description":"Streams the tenant's information-security objectives register as a single-sheet XLSX workbook. Filename includes ISO date. Cache-control private,no-store.","security":[{"sessionCookie":[]}],"responses":{"200":{"description":"OK; binary XLSX body.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/interested-parties/export.xlsx":{"get":{"tags":["Exports"],"summary":"§4.2 interested parties export","description":"Streams the tenant's stakeholder register with addressed enum as a single-sheet XLSX workbook. Filename includes ISO date. Cache-control private,no-store.","security":[{"sessionCookie":[]}],"responses":{"200":{"description":"OK; binary XLSX body.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/isms-scope/export.xlsx":{"get":{"tags":["Exports"],"summary":"§4.3 ISMS scope export (full version history)","description":"Streams the tenant's ISMS scope statement + every previous published version as a single-sheet XLSX workbook. Filename includes ISO date. Cache-control private,no-store.","security":[{"sessionCookie":[]}],"responses":{"200":{"description":"OK; binary XLSX body.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/audit-log":{"get":{"tags":["Authenticated registers"],"summary":"Tenant-side audit-log viewer (org_admin only)","description":"Append-only record of mutations against the tenant. Filter + paginate via the query string. Required by A.8.15.","security":[{"sessionCookie":[]}],"parameters":[{"name":"action","in":"query","schema":{"type":"string"}},{"name":"entityType","in":"query","schema":{"type":"string"}},{"name":"actorUserId","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"from","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"to","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"cursor","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200}}],"responses":{"200":{"description":"OK; cursor-based pagination via `nextCursor`."},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/objectives":{"get":{"tags":["Authenticated registers"],"summary":"§6.2 information security objectives","description":"Lists §6.2 information security objectives for the signed-in tenant.","security":[{"sessionCookie":[]}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/interested-parties":{"get":{"tags":["Authenticated registers"],"summary":"§4.2 interested parties","description":"Lists §4.2 interested parties register for the signed-in tenant.","security":[{"sessionCookie":[]}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}},"/api/isms-scope":{"get":{"tags":["Authenticated registers"],"summary":"§4.3 ISMS scope statement","description":"Lists §4.3 scope record; append-only versions for the signed-in tenant.","security":[{"sessionCookie":[]}],"responses":{"200":{"description":"OK"},"401":{"$ref":"#/components/responses/Unauthorized"},"403":{"$ref":"#/components/responses/Forbidden"}}}}},"components":{"schemas":{"ControlList":{"type":"object","required":["count","controls"],"properties":{"count":{"type":"integer","minimum":0},"controls":{"type":"array","items":{"$ref":"#/components/schemas/ControlSummary"}}}},"ControlSummary":{"type":"object","required":["id","code","theme","name","newIn2022","automationTier"],"properties":{"id":{"type":"string","format":"uuid"},"code":{"type":"string","example":"A.5.1"},"theme":{"type":"string","enum":["Organizational","People","Physical","Technological"]},"name":{"type":"string"},"newIn2022":{"type":"boolean"},"controlTypes":{"type":"array","items":{"type":"string","enum":["Preventive","Detective","Corrective"]}},"automationTier":{"type":"string","enum":["A","P","M"]},"primaryMicrosoftProduct":{"type":"string","nullable":true},"purpose":{"type":"string"}}},"ControlDetail":{"allOf":[{"$ref":"#/components/schemas/ControlSummary"},{"type":"object","properties":{"isoClauses":{"type":"array","items":{"type":"string"}},"essential8":{"type":"array","items":{"type":"string"}},"graphEndpoints":{"type":"array","items":{"type":"string"}}}}]},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}},"responses":{"BadRequest":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"Unauthorized — no session cookie","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Forbidden":{"description":"Forbidden — role or org status disallows the action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"securitySchemes":{"sessionCookie":{"type":"apiKey","in":"cookie","name":"__Host-sf-session","description":"Opaque session id set by Microsoft Entra ID sign-in. Treat as a bearer."}}}}