{"openapi":"3.1.0","info":{"title":"GET /api/v1/accounting-periods/close-run","version":"1.0.0","description":"Close run of a month"},"servers":[{"url":"https://api.ondayzero.com","description":"Production"}],"paths":{"/api/v1/accounting-periods/close-run":{"get":{"tags":["accounting-periods"],"summary":"Close run of a month","description":"The close agents' run record of each SOP job for one month being closed: owner, status, due business day, overdue, evidence and blocker, ordered by due day, plus a summary. Defaults to the month being closed now (the previous month, New York date).","operationId":"get_close_run","parameters":[{"name":"period_start","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"First day of the month being closed (YYYY-MM-01)","title":"Period Start"},"description":"First day of the month being closed (YYYY-MM-01)"},{"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_CloseRunResponse_"}}}},"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"}}}},"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_close_run_api_v1_accounting_periods_close_run_get"}}},"components":{"schemas":{"CloseRunResponse":{"properties":{"period_start":{"type":"string","title":"Period Start","description":"First day of the month (YYYY-MM-01)"},"steps":{"items":{"$ref":"#/components/schemas/CloseRunStepResponse"},"type":"array","title":"Steps"},"summary":{"$ref":"#/components/schemas/CloseRunSummaryResponse"}},"type":"object","required":["period_start"],"title":"CloseRunResponse","description":"The close run of one month: its steps and summary."},"CloseRunStepResponse":{"properties":{"id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Id","description":"Step UUID"},"job_id":{"type":"string","title":"Job Id","description":"SOP job id"},"title":{"type":"string","title":"Title","description":"What the job is"},"owner":{"type":"string","title":"Owner","description":"Role or bot that owns the job"},"status":{"type":"string","title":"Status","description":"planned, running, done, blocked, failed or skipped"},"due_business_day":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Due Business Day","description":"Business day of the closing month it is due by (-1 = last)"},"overdue":{"type":"boolean","title":"Overdue","description":"Open and past its business day","default":false},"done_when":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Done When","description":"What counts as done"},"done_when_result":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Done When Result","description":"What the run found against done_when"},"evidence_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Evidence Url","description":"Link to the evidence"},"blocker":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Blocker","description":"What blocks the job"},"run_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Run Id","description":"Agent run id"},"bot":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Bot","description":"Bot that ran the job"},"cost_usd":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cost Usd","description":"Run cost in dollars (decimal)"},"checklist_step_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Checklist Step Id","description":"Close checklist step it acknowledges when done"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Started At","description":"When the run started (UTC)"},"finished_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Finished At","description":"When it finished (UTC)"},"updated_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Updated At","description":"Last change (UTC)"}},"type":"object","required":["job_id","title","owner","status"],"title":"CloseRunStepResponse","description":"One SOP job's run record for the month being closed."},"CloseRunSummaryResponse":{"properties":{"total":{"type":"integer","title":"Total","description":"Steps in the run","default":0},"done":{"type":"integer","title":"Done","description":"Steps done","default":0},"blocked":{"type":"integer","title":"Blocked","description":"Steps blocked","default":0},"failed":{"type":"integer","title":"Failed","description":"Steps failed","default":0},"overdue":{"type":"integer","title":"Overdue","description":"Open steps past their business day","default":0},"business_day_today":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Business Day Today","description":"Today's business day of the month (null if not one)"}},"type":"object","title":"CloseRunSummaryResponse","description":"Counts for the period's close run."},"SuccessEnvelope_CloseRunResponse_":{"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/CloseRunResponse"},{"type":"null"}]}},"additionalProperties":true,"type":"object","title":"SuccessEnvelope[CloseRunResponse]"},"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":[]}]}