{"openapi":"3.0.3","info":{"title":"Aggrete Console API","version":"0.4.0","description":"The console's HTTP API. Authenticate with a scoped API token (`Authorization: Bearer agc_...`); the token carries a role and every call is checked by the same permission matrix as a signed-in user."},"servers":[{"url":"/","description":"This console"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Dashboard","description":"Overview data and time-series."},{"name":"Audit","description":"Decision log, admin-action log, export and evidence."},{"name":"Policy","description":"Draft from a document, preview, publish, version and roll back."},{"name":"Connectors","description":"Configure upstream systems behind the proxy."},{"name":"Protection","description":"Protection packs."},{"name":"Alerts","description":"Threshold notifications."},{"name":"Exceptions","description":"Exception and break-glass workflow."},{"name":"Tokens","description":"Programmatic access tokens."},{"name":"Users","description":"Users and roles."},{"name":"Session","description":"Who am I, sign-in."}],"paths":{"/api/me":{"get":{"tags":["Session"],"summary":"Current identity","description":"The signed-in user, role and the capability map the UI gates on.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}}}},"/api/console":{"get":{"tags":["Dashboard"],"summary":"Dashboard payload","description":"Everything the Overview renders: headline, stats, packs, activity, people, report, integrity.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}}}},"/api/trends":{"get":{"tags":["Dashboard"],"summary":"Time-series","description":"Daily checked/refused counts, the decision split and the top domains.","security":[{"bearerAuth":[]}],"parameters":[{"name":"range","in":"query","required":false,"schema":{"type":"string"},"description":"today | 7d | 30d | 90d | all","example":"30d"}],"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}}}},"/api/overview":{"get":{"tags":["Dashboard"],"summary":"Overview headline","description":"The headline, trend and 'needs attention' items.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}}}},"/api/audit":{"get":{"tags":["Audit"],"summary":"List decisions","description":"Filterable decision log.","security":[{"bearerAuth":[]}],"parameters":[{"name":"range","in":"query","required":false,"schema":{"type":"string"},"description":"today | 7d | 30d | 90d | all","example":"7d"},{"name":"decision","in":"query","required":false,"schema":{"type":"string"},"description":"deny | alert | allow","example":"deny"},{"name":"user","in":"query","required":false,"schema":{"type":"string"},"description":"person / email"},{"name":"rule","in":"query","required":false,"schema":{"type":"string"},"description":"rule id"},{"name":"limit","in":"query","required":false,"schema":{"type":"string"},"description":"max rows","example":"300"}],"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"view.audit"}},"/api/audit/export":{"get":{"tags":["Audit"],"summary":"Export decisions","description":"Stream the filtered decision log as CSV or JSON for a SIEM.","security":[{"bearerAuth":[]}],"parameters":[{"name":"format","in":"query","required":false,"schema":{"type":"string"},"description":"csv | json","example":"csv"},{"name":"range","in":"query","required":false,"schema":{"type":"string"},"description":"window","example":"30d"},{"name":"decision","in":"query","required":false,"schema":{"type":"string"},"description":"filter"},{"name":"user","in":"query","required":false,"schema":{"type":"string"},"description":"filter"},{"name":"rule","in":"query","required":false,"schema":{"type":"string"},"description":"filter"}],"responses":{"200":{"description":"text/csv or application/json download"}},"x-required-permission":"audit.export"}},"/api/actions":{"get":{"tags":["Audit"],"summary":"Admin-action log","description":"The tamper-evident log of administrative actions, with an integrity check.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"view.audit"}},"/api/audit/verify":{"get":{"tags":["Audit"],"summary":"Verify decision chain","description":"Re-walk the decision log hash chain and report whether it is intact.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}}}},"/api/evidence":{"get":{"tags":["Audit"],"summary":"Evidence pack","description":"A JSON bundle: period summary, both integrity chains and the policy version history.","security":[{"bearerAuth":[]}],"parameters":[{"name":"range","in":"query","required":false,"schema":{"type":"string"},"description":"window","example":"30d"}],"responses":{"200":{"description":"application/json download"}},"x-required-permission":"audit.export"}},"/api/receipt/{ts}/{user}":{"get":{"tags":["Audit"],"summary":"Refusal receipt","description":"A signed receipt for a specific refusal.","security":[{"bearerAuth":[]}],"parameters":[{"name":"ts","in":"path","required":true,"schema":{"type":"string"},"description":"decision timestamp"},{"name":"user","in":"path","required":true,"schema":{"type":"string"},"description":"person"}],"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}}}},"/api/rules":{"get":{"tags":["Policy"],"summary":"Current policy","description":"The live rules and the raw coc.yaml.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}}}},"/api/ingest":{"post":{"tags":["Policy"],"summary":"Document to draft rules","description":"Upload a policy document (multipart file); returns draft rules with provenance. Uses the model path when a key is present, else the offline pattern drafter.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Draft rules"},"400":{"description":"Unreadable document"}},"x-required-permission":"policy.import"}},"/api/policy/preview":{"post":{"tags":["Policy"],"summary":"Preview impact","description":"Replay draft rules against real decision history; returns per-rule would-refuse counts.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rules":{"type":"array"},"range":{"type":"string"}}}}}},"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"policy.author"}},"/api/policy/publish":{"post":{"tags":["Policy"],"summary":"Publish","description":"Write draft rules to the live policy (append or replace); snapshots the previous version.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rules":{"type":"array"},"mode":{"type":"string"}}}}}},"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"policy.publish"}},"/api/policy/versions":{"get":{"tags":["Policy"],"summary":"Version history","description":"Published policy snapshots.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"policy.author"}},"/api/policy/version/{id}":{"get":{"tags":["Policy"],"summary":"Get a version","description":"The coc.yaml of one version.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"version id"}],"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"policy.author"}},"/api/policy/diff":{"get":{"tags":["Policy"],"summary":"Diff","description":"Unified diff of a version against the current policy (or another version).","security":[{"bearerAuth":[]}],"parameters":[{"name":"a","in":"query","required":false,"schema":{"type":"string"},"description":"version id"},{"name":"b","in":"query","required":false,"schema":{"type":"string"},"description":"version id (optional)"}],"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"policy.author"}},"/api/policy/rollback":{"post":{"tags":["Policy"],"summary":"Roll back","description":"Restore a prior version (snapshots the current one first).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"}}}}}},"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"policy.publish"}},"/api/connectors":{"get":{"tags":["Connectors"],"summary":"List connectors","description":"Configured connectors (no secrets) and the available types.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"connector.config"},"post":{"tags":["Connectors"],"summary":"Add or update","description":"Create or update a connector; the secret is encrypted at rest.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"type":{"type":"string"},"name":{"type":"string"},"params":{"type":"object"},"domain":{"type":"string"},"secret":{"type":"string"},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"connector.config"}},"/api/connectors/test":{"post":{"tags":["Connectors"],"summary":"Test connection","description":"Reach the live provider with the connector client; returns ok/detail.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"type":{"type":"string"},"params":{"type":"object"},"secret":{"type":"string"},"id":{"type":"string"}}}}}},"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"connector.config"}},"/api/connectors/{id}":{"post":{"tags":["Connectors"],"summary":"Enable / disable","description":"Toggle a connector.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"connector id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"connector.config"},"delete":{"tags":["Connectors"],"summary":"Remove","description":"Delete a connector.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"connector id"}],"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"connector.config"}},"/api/packs":{"get":{"tags":["Protection"],"summary":"List packs","description":"Protection packs and their enabled state.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}}},"post":{"tags":["Protection"],"summary":"Toggle a pack","description":"Enable or disable a protection pack.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"packs.toggle"}},"/api/alerts":{"get":{"tags":["Alerts"],"summary":"List alerts","description":"Alert rules, metrics and channel types.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"alerts.config"},"post":{"tags":["Alerts"],"summary":"Add or update","description":"Create/update a threshold alert.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"metric":{"type":"string"},"threshold":{"type":"integer"},"channel":{"type":"string"},"channel_type":{"type":"string"},"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"alerts.config"}},"/api/alerts/test":{"post":{"tags":["Alerts"],"summary":"Send test","description":"Send a test message to a channel (webhook, email or Teams).","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"channel":{"type":"string"},"channel_type":{"type":"string"}}}}}},"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"alerts.config"}},"/api/alerts/check":{"post":{"tags":["Alerts"],"summary":"Evaluate now","description":"Evaluate all alerts against today and fire any over threshold.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"alerts.config"}},"/api/alerts/{id}":{"post":{"tags":["Alerts"],"summary":"Enable / disable","description":"Toggle an alert.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"alert id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"enabled":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"alerts.config"},"delete":{"tags":["Alerts"],"summary":"Remove","description":"Delete an alert.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"alert id"}],"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"alerts.config"}},"/api/exceptions":{"get":{"tags":["Exceptions"],"summary":"List exceptions","description":"All exception and break-glass requests.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"view.audit"},"post":{"tags":["Exceptions"],"summary":"Request","description":"Request a time-boxed exception; set break_glass for an emergency grant.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rule":{"type":"string"},"justification":{"type":"string"},"hours":{"type":"number"},"break_glass":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"exception.request"}},"/api/exceptions/{id}":{"post":{"tags":["Exceptions"],"summary":"Approve / deny","description":"Decide a pending exception. The requester can never approve their own.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"exception id"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"approve":{"type":"boolean"}}}}}},"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"exception.approve"}},"/api/tokens":{"get":{"tags":["Tokens"],"summary":"List tokens","description":"Named tokens (no secret value) and the assignable roles.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"tokens.manage"},"post":{"tags":["Tokens"],"summary":"Create","description":"Mint a scoped token; the value is returned once.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"role":{"type":"string"}}}}}},"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"tokens.manage"}},"/api/tokens/{id}":{"delete":{"tags":["Tokens"],"summary":"Revoke","description":"Revoke a token immediately.","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"token id"}],"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"tokens.manage"}},"/api/users":{"get":{"tags":["Users"],"summary":"List users","description":"Users, their roles and whether a password is set.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"users.manage"},"post":{"tags":["Users"],"summary":"Add or update","description":"Create/update a user; optional password enables local sign-in.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string"},"name":{"type":"string"},"role":{"type":"string"},"password":{"type":"string"}}}}}},"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"users.manage"}},"/api/users/{email}":{"post":{"tags":["Users"],"summary":"Set role / password","description":"Change a user's role or set a new password.","security":[{"bearerAuth":[]}],"parameters":[{"name":"email","in":"path","required":true,"schema":{"type":"string"},"description":"user email"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"role":{"type":"string"},"password":{"type":"string"}}}}}},"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"users.manage"},"delete":{"tags":["Users"],"summary":"Remove","description":"Delete a user.","security":[{"bearerAuth":[]}],"parameters":[{"name":"email","in":"path","required":true,"schema":{"type":"string"},"description":"user email"}],"responses":{"200":{"description":"OK"},"403":{"description":"Role not permitted"}},"x-required-permission":"users.manage"}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"agc_...","description":"A console API token. Create one on the API Tokens screen."}}}}