{"openapi":"3.0.3","info":{"title":"AgentPay Backend","version":"1.0.0","description":"Metering, billing, and settlement gateway for AgentPay."},"paths":{"/health":{"get":{"summary":"Shallow health check"}},"/api/v1/health/deep":{"get":{"summary":"Deep health with process diagnostics"}},"/api/v1/health/ready":{"get":{"summary":"Readiness check for load balancers"}},"/api/v1/version":{"get":{"summary":"App version"}},"/api/v1/changelog":{"get":{"summary":"Changelog entries"}},"/api/v1/openapi.json":{"get":{"summary":"OpenAPI document"}},"/api/v1/stats":{"get":{"summary":"Aggregate stats snapshot"}},"/api/v1/metrics":{"get":{"summary":"Prometheus metrics"}},"/api/v1/events":{"get":{"summary":"Audit log (?since=&limit=)"}},"/api/v1/events/summary":{"get":{"summary":"Audit log summary"}},"/api/v1/config":{"get":{"summary":"Read runtime config"},"patch":{"summary":"Update runtime config","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/configPatch"}}}}}},"/api/v1/services":{"get":{"summary":"List services"},"post":{"summary":"Register a service","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/serviceCreate"}}}}}},"/api/v1/services/bulk":{"post":{"summary":"Register services in bulk","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/bulkServices"}}}}}},"/api/v1/services/{serviceId}":{"get":{"summary":"Fetch one service"},"delete":{"summary":"Unregister service"}},"/api/v1/services/{serviceId}/metadata":{"get":{"summary":"Fetch service metadata"},"put":{"summary":"Set service metadata","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/serviceMetadataPut"}}}}}},"/api/v1/services/{serviceId}/price":{"patch":{"summary":"Update price only","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/servicePricePatch"}}}}}},"/api/v1/services/{serviceId}/disabled":{"patch":{"summary":"Enable or disable a service","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/serviceDisabledPatch"}}}}}},"/api/v1/services/{serviceId}/usage":{"get":{"summary":"Service usage total"}},"/api/v1/services/{serviceId}/agents":{"get":{"summary":"List agents on a service"}},"/api/v1/services/{serviceId}/agents/top":{"get":{"summary":"Top agents on a service"}},"/api/v1/usage":{"post":{"summary":"Record usage","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/usageRecord"}}}}}},"/api/v1/usage/bulk":{"post":{"summary":"Batched record","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/bulkUsage"}}}}}},"/api/v1/usage/export.json":{"get":{"summary":"Export usage as JSON"}},"/api/v1/usage/export.csv":{"get":{"summary":"Export usage as CSV"}},"/api/v1/usage/{agent}/{serviceId}":{"get":{"summary":"Read an agent/service usage total"},"delete":{"summary":"Reset an agent/service usage counter"}},"/api/v1/services/{serviceId}/disable":{"post":{"summary":"Disable a service"}},"/api/v1/services/{serviceId}/enable":{"post":{"summary":"Enable a service"}},"/api/v1/billing/total":{"get":{"summary":"Aggregate billing totals"}},"/api/v1/billing/{agent}/{serviceId}":{"get":{"summary":"Quote billing for an agent/service pair"}},"/api/v1/charges":{"get":{"summary":"List tenant charges"},"post":{"summary":"Create an idempotent charge"}},"/api/v1/agents":{"get":{"summary":"List agents with usage"}},"/api/v1/agents/{agent}/total":{"get":{"summary":"Total outstanding usage for an agent"}},"/api/v1/agents/{agent}/usage":{"get":{"summary":"Per-service usage for an agent"}},"/api/v1/settle":{"post":{"summary":"Drain & quote bill"}},"/api/v1/settle/bulk":{"post":{"summary":"Drain all services for one agent"}},"/api/v1/api-keys":{"get":{"summary":"List api keys"},"post":{"summary":"Create api key","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/apiKeyCreate"}}}}}},"/api/v1/api-keys/{prefix}":{"delete":{"summary":"Revoke by prefix"}},"/api/v1/webhooks":{"get":{"summary":"List webhooks"},"post":{"summary":"Register webhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/webhookCreate"}}}}}},"/api/v1/webhooks/{id}":{"get":{"summary":"Fetch one webhook"},"delete":{"summary":"Unregister webhook"},"patch":{"summary":"Update webhook","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/webhookPatch"}}}}}},"/api/v1/webhooks/{id}/test":{"post":{"summary":"Simulate webhook delivery"}},"/api/v1/admin/pause":{"post":{"summary":"Pause writes"}},"/api/v1/admin/unpause":{"post":{"summary":"Resume"}},"/api/v1/admin/status":{"get":{"summary":"Read pause flag"}},"/api/v1/admin/reset":{"post":{"summary":"Clear all in-memory state"}}},"components":{"schemas":{"apiKeyCreate":{"type":"object","additionalProperties":false,"required":["label"],"properties":{"label":{"type":"string","minLength":1,"maxLength":64}}},"bulkServices":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"required":["serviceId","priceStroops"],"properties":{"serviceId":{"type":"string","minLength":1,"maxLength":128},"priceStroops":{"type":"integer","minimum":0}}}}}},"bulkUsage":{"type":"object","additionalProperties":false,"required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["agent","serviceId","requests"],"properties":{"agent":{"type":"string","minLength":1,"maxLength":256},"serviceId":{"type":"string","minLength":1,"maxLength":128},"requests":{"type":"integer","exclusiveMinimum":0}}}}}},"configPatch":{"type":"object","additionalProperties":false,"required":[],"properties":{"rateLimitPerWindow":{"type":"integer","minimum":1},"rateLimitWindowMs":{"type":"integer","minimum":1},"bulkMaxItems":{"type":"integer","minimum":1},"eventLogCap":{"type":"integer","minimum":1},"usageStoreMaxKeys":{"type":"integer","minimum":1},"servicesStoreMaxKeys":{"type":"integer","minimum":1},"webhookStoreMaxKeys":{"type":"integer","minimum":1},"apiKeyStoreMaxKeys":{"type":"integer","minimum":1}}},"serviceCreate":{"type":"object","additionalProperties":false,"required":["serviceId","priceStroops"],"properties":{"serviceId":{"type":"string","minLength":1,"maxLength":128},"priceStroops":{"type":"integer","minimum":0},"expectedVersion":{"type":"integer","minimum":1}}},"serviceDisabledPatch":{"type":"object","additionalProperties":false,"required":["disabled","expectedVersion"],"properties":{"disabled":{"type":"boolean"},"expectedVersion":{"type":"integer","minimum":1}}},"serviceMetadataPut":{"type":"object","additionalProperties":false,"required":["description","owner","expectedVersion"],"properties":{"description":{"type":"string","maxLength":256},"owner":{"type":"string","minLength":1,"maxLength":256},"expectedVersion":{"type":"integer","minimum":1}}},"servicePricePatch":{"type":"object","additionalProperties":false,"required":["priceStroops","expectedVersion"],"properties":{"priceStroops":{"type":"integer","minimum":0},"expectedVersion":{"type":"integer","minimum":1}}},"settle":{"type":"object","additionalProperties":false,"required":["agent","serviceId"],"properties":{"agent":{"type":"string"},"serviceId":{"type":"string"}}},"usageRecord":{"type":"object","additionalProperties":false,"required":["agent","serviceId","requests"],"properties":{"agent":{"type":"string","minLength":1,"maxLength":256},"serviceId":{"type":"string","minLength":1,"maxLength":128},"requests":{"type":"integer","exclusiveMinimum":0}}},"webhookCreate":{"type":"object","additionalProperties":false,"required":["url","events"],"properties":{"url":{"type":"string","maxLength":2048,"pattern":"^https?://"},"events":{"type":"array","items":{"type":"string"},"minItems":1}}},"webhookPatch":{"type":"object","additionalProperties":false,"required":[],"properties":{"url":{"type":"string","maxLength":2048,"pattern":"^https?://"},"events":{"type":"array","items":{"type":"string"},"minItems":1}}},"BillingQuote":{"type":"object","properties":{"agent":{"type":"string"},"serviceId":{"type":"string"},"requests":{"type":"integer"},"priceStroops":{"type":"integer"},"billedStroops":{"type":"string","description":"Exact billed amount in stroops as a decimal string."}}},"BillingTotal":{"type":"object","properties":{"totalStroops":{"type":"string","description":"Aggregate billed amount in stroops as a decimal string."},"disabledStroops":{"type":"string"},"unpricedRequests":{"type":"integer"}}}}}}