{"openapi":"3.1.0","info":{"title":"Aargon Revenue Intelligence API","version":"1.0.0","description":"Public, Bearer-authenticated surface of the Aargon Revenue Intelligence platform. Every request must carry `Authorization: Bearer aar_live_<prefix>_<secret>`. Rate limits are per-key; the response includes `X-RateLimit-Limit` and `X-RateLimit-Remaining`.","contact":{"name":"Aargon Platform","url":"https://aargon.ai"}},"servers":[{"url":"https://api.aargon.ai","description":"Production"}],"components":{"securitySchemes":{"bearerApiKey":{"type":"http","scheme":"bearer","bearerFormat":"aar_live_<prefix>_<secret>"}},"schemas":{"ClientSnapshot":{"type":"object","properties":{"client":{"type":"object","additionalProperties":true},"range":{"type":"object","properties":{"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"preset":{"type":"string"}}},"kpis":{"type":"object","additionalProperties":true},"monthly":{"type":"array","items":{"type":"object","additionalProperties":true}},"aging":{"type":"array","items":{"type":"object","additionalProperties":true}},"divisions":{"type":"array","items":{"type":"object","additionalProperties":true}},"collectors":{"type":"array","items":{"type":"object","additionalProperties":true}},"activity":{"type":"array","items":{"type":"object","additionalProperties":true}},"summary":{"type":"object","additionalProperties":true}},"required":["client","range","kpis","monthly"]},"WebhookEvent":{"type":"object","properties":{"id":{"type":"string"},"kind":{"type":"string","enum":["payment.received","placement.posted","invoice.issued","report.ready","anomaly.detected","threshold.crossed"]},"clientId":{"type":"string"},"occurredAt":{"type":"string","format":"date-time"},"data":{"type":"object","additionalProperties":true}},"required":["id","kind","clientId","occurredAt","data"]},"Error":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"}},"required":["error"]}}},"security":[{"bearerApiKey":[]}],"paths":{"/api/v1/snapshot":{"get":{"summary":"Fetch the current ClientSnapshot for the caller's scope.","parameters":[{"name":"range","in":"query","required":false,"schema":{"type":"string","enum":["last-30-days","last-90-days","ytd","last-13-months","trailing-24-months"],"default":"last-13-months"}},{"name":"client","in":"query","required":false,"description":"Required only when the API key is unscoped (not attached to a single client).","schema":{"type":"string"}}],"responses":{"200":{"description":"Snapshot envelope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientSnapshot"}}}},"401":{"description":"Missing or invalid API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Key lacks the required scope.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Client not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded.","headers":{"Retry-After":{"description":"Seconds until the bucket refills.","schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/health/live":{"get":{"summary":"Liveness probe — does the process have a working event loop?","security":[],"responses":{"200":{"description":"OK."}}}},"/api/health/ready":{"get":{"summary":"Readiness probe — are dependencies (DB, config) healthy?","security":[],"responses":{"200":{"description":"Ready."},"503":{"description":"Not ready (DB unreachable or config missing)."}}}},"/api/version":{"get":{"summary":"Build metadata. Safe to call unauthenticated.","security":[],"responses":{"200":{"description":"Version envelope."}}}},"/outgoing-webhook":{"post":{"summary":"Receiver contract — customer-hosted endpoint. Aargon POSTs events in this shape to subscribed URLs. Verify `X-Aargon-Signature: t=<ts>,v1=<hmac>` with the shared secret.","security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEvent"}}}},"responses":{"2XX":{"description":"Any 2xx — Aargon treats as delivered."},"default":{"description":"Non-2xx — Aargon logs the attempt and may retry."}}}}}}