{"openapi":"3.1.0","info":{"title":"Kometrics API","version":"1.0.0","description":"Read-only SaaS-metrics API (MRR, churn, customers, activities) computed from Stripe and Creem. ChartMogul-compatible vocabulary. Money is integer USD cents; rates are percent floats."},"servers":[{"url":"/api/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key from Settings → API keys (ko_…). HTTP Basic with the key as username also works."}}},"paths":{"/account":{"get":{"operationId":"getAccount","summary":"Account details","responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"currency":{"type":"string"},"time_zone":{"type":"string"},"week_start_on":{"type":"string"}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]}}}}}}},"/metrics/{metric}":{"get":{"operationId":"getMetrics","summary":"Metric series per period","description":"`all` returns every metric per period; `mrr` returns MRR with its five movement components; the rest return {date, value} pairs.","parameters":[{"name":"metric","in":"path","required":true,"schema":{"type":"string","enum":["all","mrr","arr","arpa","customer-count","mrr-growth-rate","customer-churn-rate","gross-mrr-churn-rate","net-mrr-churn-rate"]}},{"name":"start-date","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"start-date (YYYY-MM-DD, account timezone)"},{"name":"end-date","in":"query","required":true,"schema":{"type":"string","format":"date"},"description":"end-date (YYYY-MM-DD, account timezone)"},{"name":"interval","in":"query","schema":{"type":"string","enum":["day","week","month","quarter","year"],"default":"month"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"mrr":{"type":"integer","description":"USD cents"},"arr":{"type":"integer","description":"USD cents"},"customers":{"type":"integer"},"arpa":{"type":["integer","null"],"description":"USD cents"},"mrr-new-business":{"type":"integer","description":"USD cents"},"mrr-expansion":{"type":"integer","description":"USD cents"},"mrr-contraction":{"type":"integer","description":"USD cents"},"mrr-churn":{"type":"integer","description":"USD cents"},"mrr-reactivation":{"type":"integer","description":"USD cents"},"mrr-net-movement":{"type":"integer","description":"USD cents"},"mrr-growth-rate":{"type":["number","null"],"description":"percent, 2 decimals"},"customer-churn-rate":{"type":["number","null"],"description":"percent, 2 decimals"},"gross-mrr-churn-rate":{"type":["number","null"],"description":"percent, 2 decimals"},"net-mrr-churn-rate":{"type":["number","null"],"description":"percent, 2 decimals"},"subscriber-growth-rate":{"type":["number","null"],"description":"percent, 2 decimals"},"value":{"type":["number","null"],"description":"single-series metrics only"}}}}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]}}}}}}},"/customers":{"get":{"operationId":"listCustomers","summary":"List/search customers","parameters":[{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from the previous page."},{"name":"email","in":"query","schema":{"type":"string"},"description":"Exact email match."},{"name":"external_id","in":"query","schema":{"type":"string"}},{"name":"status","in":"query","schema":{"type":"string","enum":["active","cancelled"]}},{"name":"q","in":"query","schema":{"type":"string"},"description":"Substring over name/email/id."}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"external_id":{"type":"string"},"name":{"type":["string","null"]},"email":{"type":["string","null"],"description":"Omitted when the workspace has privacy mode on (see `anonymized`)."},"anonymized":{"type":"boolean","description":"Present and true when the workspace anonymizes customer PII; `name` is a stable pseudonym and `email` is never returned."},"country":{"type":["string","null"]},"source":{"type":"string"},"status":{"type":"string","enum":["active","cancelled","none"]},"mrr":{"type":"integer","description":"USD cents"},"arr":{"type":"integer","description":"USD cents"},"customer-since":{"type":"string","format":"date"},"last-activity":{"type":["string","null"],"format":"date"}}}},"cursor":{"type":"string"},"has_more":{"type":"boolean"}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]}}}}}}},"/customers/{external_id}":{"get":{"operationId":"getCustomer","summary":"Customer detail with subscriptions","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK: profile, mrr/arr/net-payments and subscriptions array."},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]}}}}}}},"/customers/{external_id}/activities":{"get":{"operationId":"getCustomerActivities","summary":"Customer's MRR movements, newest first","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]}}}}}}},"/customers/{external_id}/invoices":{"get":{"operationId":"getCustomerInvoices","summary":"Customer's invoices, newest first","parameters":[{"name":"external_id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK"},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]}}}}}}},"/activities":{"get":{"operationId":"listActivities","summary":"Account-wide MRR movements feed, newest first","parameters":[{"name":"per_page","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"cursor","in":"query","schema":{"type":"string"},"description":"Opaque cursor from the previous page."},{"name":"start-date","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"start-date (YYYY-MM-DD, account timezone)"},{"name":"end-date","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"end-date (YYYY-MM-DD, account timezone)"},{"name":"type","in":"query","schema":{"type":"string","enum":["new_business","expansion","contraction","churn","reactivation"]}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"entries":{"type":"array","items":{"type":"object","properties":{"id":{"type":"integer"},"type":{"type":"string"},"date":{"type":"string","format":"date"},"mrr-movement":{"type":"integer","description":"USD cents"},"mrr":{"type":"integer","description":"USD cents"},"customer-external-id":{"type":"string"},"subscription-external-id":{"type":["string","null"]}}}},"cursor":{"type":"string"},"has_more":{"type":"boolean"}}}}}},"401":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"type":"object","properties":{"code":{"type":"integer"},"message":{"type":"string"}},"required":["code","message"]}}}}}}}}}