{"openapi":"3.1.0","info":{"title":"GET /api/v1/benchmarks/me","version":"1.0.0","description":"Peer benchmarks for a month"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/benchmarks/me":{"get":{"tags":["benchmarks"],"summary":"Peer benchmarks for a month","description":"The business's operating ratios for the month (gross margin, DSO, DPO, inventory turns, ad spend and opex to revenue, business days to close, trust grade, auto-coded share), the cohorts it falls into and, for the first cohort with 20 or more contributors, the cohort quartiles and the business's percentile. Smaller cohorts are null with a reason.","operationId":"get_my_benchmarks","parameters":[{"name":"month","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"YYYY-MM; default the last complete month","title":"Month"},"description":"YYYY-MM; default the last complete month"},{"name":"authorization","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Authorization"}},{"name":"x-business-id","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"X-Business-Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SuccessEnvelope_MyBenchmarksResponse_"}}}},"400":{"description":"Bad Request - Invalid input","content":{"application/json":{"example":{"error":"validation_error","message":"Validation failed: due_date: Input should be a valid date","errors":{"due_date":"Input should be a valid date"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Missing or expired token, an MCP OAuth token used against the REST API, or no access to this business","content":{"application/json":{"example":{"error":"unauthorized","message":"Authentication required","code":"AUTH_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden - Insufficient permissions","content":{"application/json":{"example":{"error":"forbidden","message":"You don't have permission to access this resource","code":"AUTH_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found - Resource does not exist","content":{"application/json":{"example":{"error":"not_found","message":"Resource not found","code":"NOT_FOUND_001","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"},"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"error":"validation_error","message":"Validation failed: amount: Input should be a valid integer","errors":{"amount":"Input should be a valid integer"},"code":"GEN_002","request_id":"3f0e7c2a-9b4d-4e1a-8c6f-2d5b7a1e9c30"}}}}},"x-fastapi-operation-id":"get_my_benchmarks_api_v1_benchmarks_me_get"}}},"components":{"schemas":{"BenchmarkMetricRow":{"properties":{"key":{"type":"string","title":"Key"},"label":{"type":"string","title":"Label"},"unit":{"type":"string","title":"Unit","description":"bps, days, x, grade or pct"},"higher_is_better":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Higher Is Better","description":"How to read the percentile; null when neither direction is better"},"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value","description":"The business's own value this month"},"display":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Display","description":"Own value for display (the letter for trust_grade)"},"cohort":{"anyOf":[{"$ref":"#/components/schemas/CohortQuartiles"},{"type":"null"}],"description":"Null when the cohort is too small"},"percentile":{"$ref":"#/components/schemas/PercentileValue"}},"additionalProperties":false,"type":"object","required":["key","label","unit","higher_is_better","value","percentile"],"title":"BenchmarkMetricRow","description":"One metric: the business's value, the cohort quartiles and the rank."},"CohortQuartiles":{"properties":{"n":{"type":"integer","title":"N","description":"Contributors with a value for this metric"},"p25":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P25"},"p50":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P50"},"p75":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"P75"}},"additionalProperties":false,"type":"object","required":["n"],"title":"CohortQuartiles","description":"The cohort's distribution for one metric; null when too small."},"CohortRef":{"properties":{"key":{"type":"string","title":"Key","description":"industry, revenue_band or channel_mix"},"value":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Value","description":"The business's value for the key; null when unknown"},"description":{"type":"string","title":"Description","description":"Plain-language label for the cell"},"n":{"type":"integer","title":"N","description":"Contributors in the cell this month (0 when unknown)"},"qualifies":{"type":"boolean","title":"Qualifies","description":"n meets the minimum cohort size"}},"additionalProperties":false,"type":"object","required":["key","value","description","n","qualifies"],"title":"CohortRef","description":"One cohort cell the business belongs to and whether it can be shown."},"MyBenchmarksResponse":{"properties":{"business_id":{"type":"string","title":"Business Id"},"month":{"type":"string","title":"Month","description":"YYYY-MM"},"enabled":{"type":"boolean","title":"Enabled","description":"False when benchmarks_opt_in is off"},"contributing":{"type":"boolean","title":"Contributing"},"cohort":{"anyOf":[{"$ref":"#/components/schemas/CohortRef"},{"type":"null"}],"description":"The cohort the percentiles are ranked in (the first that qualifies)"},"cohorts":{"items":{"$ref":"#/components/schemas/CohortRef"},"type":"array","title":"Cohorts"},"metrics":{"items":{"$ref":"#/components/schemas/BenchmarkMetricRow"},"type":"array","title":"Metrics"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"Why metrics are empty or percentiles are null"},"computed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Computed At"}},"additionalProperties":false,"type":"object","required":["business_id","month","enabled","contributing"],"title":"MyBenchmarksResponse","description":"``GET /benchmarks/me``: the business against its peers for one month."},"PercentileValue":{"properties":{"value":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Value"},"reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Reason","description":"cohort_too_small, no_cohort, no_value or opted_out when null"}},"additionalProperties":false,"type":"object","title":"PercentileValue","description":"Where the business sits in its cohort for one metric, 0-100."},"SuccessEnvelope_MyBenchmarksResponse_":{"properties":{"success":{"type":"boolean","title":"Success","default":true},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"code":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Code"},"data":{"anyOf":[{"$ref":"#/components/schemas/MyBenchmarksResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[MyBenchmarksResponse]"},"ErrorResponse":{"title":"ErrorResponse","type":"object","description":"Envelope returned by every non-2xx response. Branch on `code` (stable) rather than `message` (human-readable, may change).","required":["error","message","code"],"properties":{"error":{"type":"string","description":"Error category: `validation_error`, `unauthorized`, `forbidden`, `not_found`, `conflict`, `rate_limited`, `server_error`, or `service_unavailable`."},"message":{"type":"string","description":"Human-readable explanation, safe to show to end users."},"code":{"type":"string","description":"Stable machine-readable code in `CATEGORY_NNN` form (e.g. `NOT_FOUND_006`, `AUTH_010`, `GEN_002`)."},"request_id":{"type":"string","description":"Correlation id for support requests. Echoes the `x-request-id` request header when one was supplied."},"errors":{"type":"object","additionalProperties":{"type":"string"},"description":"Field-level validation messages keyed by field name. Present on 400/422 validation failures only."}}}},"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Token","description":"API token authentication. Format: `Bearer dz_...`"}}},"security":[{"BearerAuth":[]}]}