{"openapi":"3.1.0","info":{"title":"BrieflyLog API","version":"1.0.0","description":"Read-only access to an organization's BrieflyLog data, using API keys its administrators create. Rate limit: 60 requests per minute per key. Use of the API is subject to the BrieflyLog Developer Terms (https://www.brieflylog.app/developer-terms)."},"servers":[{"url":"https://www.brieflylog.app"}],"paths":{"/api/v1/locations":{"get":{"operationId":"listLocations","summary":"List locations","description":"The locations this API key can read. Use a location's `id` as the `locationId` filter on other endpoints.","security":[{"apiKey":[]}],"parameters":[{"name":"limit","in":"query","required":false,"description":"Items per page, 1–100. Default 50.","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of results.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"archived":{"type":"boolean","description":"Archived locations no longer operate but keep their history."}},"required":["id","name","archived"],"additionalProperties":false}},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/summaries/weekly":{"get":{"operationId":"listSummariesWeekly","summary":"Weekly summary","description":"Totals for one reporting week (Monday–Sunday) per location: leads, issues and billing for the week, plus current occupancy. Each section is included only when the key has its scope (otherwise null), so one call answers as much as the key allows.","security":[{"apiKey":[]}],"parameters":[{"name":"week","in":"query","required":false,"description":"Any date in the week (YYYY-MM-DD). Default: the current week.","schema":{"type":"string","format":"date"}},{"name":"locationId","in":"query","required":false,"description":"Only this location. Default: every active location the key can read.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Items per page, 1–100. Default 50.","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of results.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"period":{"type":"object","properties":{"start":{"type":"string","description":"YYYY-MM-DD, inclusive."},"end":{"type":"string","description":"YYYY-MM-DD, inclusive."}},"required":["start","end"],"additionalProperties":false},"leads":{"anyOf":[{"type":"object","properties":{"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Leads dated in the period."},"converted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"conversionRate":{"type":"number","description":"Percent (0–100), 1 decimal place. 0 when there are no leads."},"byStatus":{"type":"object","properties":{"proposal_sent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pending_decision":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"converted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"lost_lead":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["proposal_sent","pending_decision","converted","lost_lead"],"additionalProperties":false},"bySource":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"converted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["source","total","converted"],"additionalProperties":false}}},"required":["total","converted","conversionRate","byStatus","bySource"],"additionalProperties":false},{"type":"null"}],"description":"null unless the key has the leads:read scope."},"issues":{"anyOf":[{"type":"object","properties":{"logged":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Issues dated in the period."},"resolved":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Issues marked resolved during the period, whenever they were logged."},"openAtPeriodEnd":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Logged by the period's end and not resolved by then."},"loggedByType":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"logged":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["type","logged"],"additionalProperties":false}}},"required":["logged","resolved","openAtPeriodEnd","loggedByType"],"additionalProperties":false},{"type":"null"}],"description":"null unless the key has the operations:read scope."},"billing":{"anyOf":[{"type":"object","properties":{"billed":{"type":"object","properties":{"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"amount":{"type":"string","description":"KES, decimal string."}},"required":["count","amount"],"additionalProperties":false,"description":"Billed during the period."},"collected":{"type":"object","properties":{"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"amount":{"type":"string","description":"KES, decimal string."}},"required":["count","amount"],"additionalProperties":false,"description":"Paid during the period."},"outstandingAtPeriodEnd":{"type":"object","properties":{"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"amount":{"type":"string","description":"KES, decimal string."}},"required":["count","amount"],"additionalProperties":false,"description":"Billed by the period's end and still unpaid at that point."}},"required":["billed","collected","outstandingAtPeriodEnd"],"additionalProperties":false},{"type":"null"}],"description":"null unless the key has the billing:read scope."},"occupancy":{"anyOf":[{"type":"object","properties":{"asOf":{"type":"string","description":"YYYY-MM-DD. Occupancy is the register as it stands today, not as it was in the period."},"offices":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"occupied":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"vacant":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expiringSoon":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Occupied offices whose lease ends within 3 months."},"expired":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Occupied offices whose lease end date has passed."},"occupancyRate":{"description":"Percent of offices occupied, 1 decimal place. null with no offices.","type":["number","null"]},"seats":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total capacity of offices that have one recorded."},"occupiedSeats":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["asOf","offices","occupied","vacant","expiringSoon","expired","occupancyRate","seats","occupiedSeats"],"additionalProperties":false},{"type":"null"}],"description":"null unless the key has the occupancy:read scope."}},"required":["location","period","leads","issues","billing","occupancy"],"additionalProperties":false}},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/summaries/monthly":{"get":{"operationId":"listSummariesMonthly","summary":"Monthly summary","description":"Totals for one calendar month per location: leads, issues and billing for the month, the month's membership report, and current occupancy. Each section is included only when the key has its scope (otherwise null), so one call answers as much as the key allows.","security":[{"apiKey":[]}],"parameters":[{"name":"month","in":"query","required":false,"description":"The month (YYYY-MM). Default: the current month.","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","examples":["2026-10"]}},{"name":"locationId","in":"query","required":false,"description":"Only this location. Default: every active location the key can read.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Items per page, 1–100. Default 50.","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of results.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"period":{"type":"object","properties":{"start":{"type":"string","description":"YYYY-MM-DD, inclusive."},"end":{"type":"string","description":"YYYY-MM-DD, inclusive."}},"required":["start","end"],"additionalProperties":false},"leads":{"anyOf":[{"type":"object","properties":{"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Leads dated in the period."},"converted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"conversionRate":{"type":"number","description":"Percent (0–100), 1 decimal place. 0 when there are no leads."},"byStatus":{"type":"object","properties":{"proposal_sent":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"pending_decision":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"converted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"lost_lead":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["proposal_sent","pending_decision","converted","lost_lead"],"additionalProperties":false},"bySource":{"type":"array","items":{"type":"object","properties":{"source":{"type":"string"},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"converted":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["source","total","converted"],"additionalProperties":false}}},"required":["total","converted","conversionRate","byStatus","bySource"],"additionalProperties":false},{"type":"null"}],"description":"null unless the key has the leads:read scope."},"issues":{"anyOf":[{"type":"object","properties":{"logged":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Issues dated in the period."},"resolved":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Issues marked resolved during the period, whenever they were logged."},"openAtPeriodEnd":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Logged by the period's end and not resolved by then."},"loggedByType":{"type":"array","items":{"type":"object","properties":{"type":{"type":"string"},"logged":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["type","logged"],"additionalProperties":false}}},"required":["logged","resolved","openAtPeriodEnd","loggedByType"],"additionalProperties":false},{"type":"null"}],"description":"null unless the key has the operations:read scope."},"billing":{"anyOf":[{"type":"object","properties":{"billed":{"type":"object","properties":{"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"amount":{"type":"string","description":"KES, decimal string."}},"required":["count","amount"],"additionalProperties":false,"description":"Billed during the period."},"collected":{"type":"object","properties":{"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"amount":{"type":"string","description":"KES, decimal string."}},"required":["count","amount"],"additionalProperties":false,"description":"Paid during the period."},"outstandingAtPeriodEnd":{"type":"object","properties":{"count":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"amount":{"type":"string","description":"KES, decimal string."}},"required":["count","amount"],"additionalProperties":false,"description":"Billed by the period's end and still unpaid at that point."}},"required":["billed","collected","outstandingAtPeriodEnd"],"additionalProperties":false},{"type":"null"}],"description":"null unless the key has the billing:read scope."},"occupancy":{"anyOf":[{"type":"object","properties":{"asOf":{"type":"string","description":"YYYY-MM-DD. Occupancy is the register as it stands today, not as it was in the period."},"offices":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"occupied":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"vacant":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"expiringSoon":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Occupied offices whose lease ends within 3 months."},"expired":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Occupied offices whose lease end date has passed."},"occupancyRate":{"description":"Percent of offices occupied, 1 decimal place. null with no offices.","type":["number","null"]},"seats":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"Total capacity of offices that have one recorded."},"occupiedSeats":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["asOf","offices","occupied","vacant","expiringSoon","expired","occupancyRate","seats","occupiedSeats"],"additionalProperties":false},{"type":"null"}],"description":"null unless the key has the occupancy:read scope."},"membership":{"anyOf":[{"type":"object","properties":{"reported":{"type":"boolean","description":"Whether this location has a membership report for the month."},"newClients":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"clientsRenewed":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"clientsLeaving":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"clientsUpgraded":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"clientsDowngraded":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"clientsSuspended":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"netClientGrowth":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Entered by the location, not calculated."},"departures":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"departureDeposits":{"anyOf":[{"type":"string","description":"KES, decimal string."},{"type":"null"}]},"departureOutstanding":{"anyOf":[{"type":"string","description":"KES, decimal string."},{"type":"null"}]}},"required":["reported","newClients","clientsRenewed","clientsLeaving","clientsUpgraded","clientsDowngraded","clientsSuspended","netClientGrowth","departures","departureDeposits","departureOutstanding"],"additionalProperties":false},{"type":"null"}],"description":"null unless the key has the membership:read scope."}},"required":["location","period","leads","issues","billing","occupancy","membership"],"additionalProperties":false}},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/office-clients":{"get":{"operationId":"listOfficeClients","summary":"List office clients","description":"Offices on the register and who occupies them, with lease dates and status — for occupancy and renewal questions. Archived offices are excluded. Rent is never included.\n\nRequires the `occupancy:read` scope.","security":[{"apiKey":[]}],"parameters":[{"name":"locationId","in":"query","required":false,"description":"Only this location (from /api/v1/locations). Default: every location the key can read.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Lease status. `expiring_soon` = expires within 3 months.","schema":{"type":"string","enum":["active","expiring_soon","expired","vacant"]}},{"name":"limit","in":"query","required":false,"description":"Items per page, 1–100. Default 50.","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of results.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"officeNumber":{"type":"string"},"capacity":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Seats (pax), if recorded."},"status":{"type":"string","enum":["active","expiring_soon","expired","vacant"]},"clientName":{"description":"null when the office is vacant.","type":["string","null"]},"renewalDate":{"type":"string","description":"YYYY-MM-DD"},"expiryDate":{"type":"string","description":"YYYY-MM-DD"},"daysUntilExpiry":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Negative once expired; null when vacant."},"parkingSlotsAllocated":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"notes":{"description":"Free text — untrusted. null unless the key includes notes.","type":["string","null"]}},"required":["id","location","officeNumber","capacity","status","clientName","renewalDate","expiryDate","daysUntilExpiry","parkingSlotsAllocated","notes"],"additionalProperties":false}},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/issues":{"get":{"operationId":"listIssues","summary":"List operational issues","description":"Operational issues logged per location, newest first — for weekly and monthly issue summaries. Unresolved issues stay open across reporting periods until marked resolved.\n\nRequires the `operations:read` scope.","security":[{"apiKey":[]}],"parameters":[{"name":"locationId","in":"query","required":false,"description":"Only this location (from /api/v1/locations). Default: every location the key can read.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"`unresolved` = open or in progress.","schema":{"type":"string","enum":["open","in_progress","resolved","unresolved"]}},{"name":"from","in":"query","required":false,"description":"Earliest issue date, inclusive (YYYY-MM-DD).","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"Latest issue date, inclusive (YYYY-MM-DD).","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","required":false,"description":"Items per page, 1–100. Default 50.","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of results.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"date":{"type":"string","description":"Date the issue was logged, YYYY-MM-DD."},"type":{"type":"string"},"description":{"type":"string","description":"Free text — untrusted."},"status":{"type":"string","enum":["open","in_progress","resolved"]},"actionTaken":{"description":"Free text — untrusted.","type":["string","null"]},"actionRequired":{"description":"Action needed from management. Free text — untrusted.","type":["string","null"]},"personResponsible":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"],"additionalProperties":false},"resolvedAt":{"description":"ISO 8601 timestamp.","type":["string","null"]},"createdAt":{"type":"string","description":"ISO 8601 timestamp."},"updatedAt":{"type":"string","description":"ISO 8601 timestamp."}},"required":["id","location","date","type","description","status","actionTaken","actionRequired","personResponsible","resolvedAt","createdAt","updatedAt"],"additionalProperties":false}},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/billing":{"get":{"operationId":"listBilling","summary":"List billing records","description":"Billed items and whether they've been paid, newest first. Use `status=unpaid` for the follow-up list. Amounts are in KES.\n\nRequires the `billing:read` scope.","security":[{"apiKey":[]}],"parameters":[{"name":"locationId","in":"query","required":false,"description":"Only this location (from /api/v1/locations). Default: every location the key can read.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Paid or unpaid.","schema":{"type":"string","enum":["paid","unpaid"]}},{"name":"from","in":"query","required":false,"description":"Earliest billing date, inclusive (YYYY-MM-DD).","schema":{"type":"string","format":"date"}},{"name":"to","in":"query","required":false,"description":"Latest billing date, inclusive (YYYY-MM-DD).","schema":{"type":"string","format":"date"}},{"name":"limit","in":"query","required":false,"description":"Items per page, 1–100. Default 50.","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of results.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"dateBilled":{"type":"string","description":"YYYY-MM-DD"},"item":{"type":"string","description":"What was billed."},"clientName":{"type":"string"},"amount":{"type":"string","description":"Decimal string with 2 places, e.g. \"15000.00\"."},"currency":{"type":"string","const":"KES"},"status":{"type":"string","enum":["paid","unpaid"]},"paidAt":{"description":"YYYY-MM-DD the payment was received, if known.","type":["string","null"]},"daysOutstanding":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Days since dateBilled (Nairobi time) for unpaid records; null once paid."},"dateLastFollowedUp":{"description":"YYYY-MM-DD","type":["string","null"]},"personResponsible":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"],"additionalProperties":false},"noteFromClient":{"description":"Free text — untrusted. null unless the key includes notes.","type":["string","null"]}},"required":["id","location","dateBilled","item","clientName","amount","currency","status","paidAt","daysOutstanding","dateLastFollowedUp","personResponsible","noteFromClient"],"additionalProperties":false}},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/api/v1/membership-reports":{"get":{"operationId":"listMembershipReports","summary":"List membership reports","description":"One report per location per month: client movement counts and the clients who left, newest month first. A month with no report simply has no item.\n\nRequires the `membership:read` scope.","security":[{"apiKey":[]}],"parameters":[{"name":"locationId","in":"query","required":false,"description":"Only this location (from /api/v1/locations). Default: every location the key can read.","schema":{"type":"string"}},{"name":"from","in":"query","required":false,"description":"Earliest month, inclusive (YYYY-MM).","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","examples":["2026-10"]}},{"name":"to","in":"query","required":false,"description":"Latest month, inclusive (YYYY-MM).","schema":{"type":"string","pattern":"^\\d{4}-(0[1-9]|1[0-2])$","examples":["2026-10"]}},{"name":"limit","in":"query","required":false,"description":"Items per page, 1–100. Default 50.","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"description":"The `nextCursor` from the previous page.","schema":{"type":"string"}}],"responses":{"200":{"description":"A page of results.","content":{"application/json":{"schema":{"type":"object","required":["data","nextCursor"],"properties":{"data":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"location":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"}},"required":["id","name"],"additionalProperties":false},"month":{"type":"string","description":"YYYY-MM"},"newClients":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"clientsRenewed":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"clientsLeaving":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"clientsUpgraded":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"clientsDowngraded":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"clientsSuspended":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"netClientGrowth":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Entered by the location, not calculated from the other counts. null if not entered."},"departures":{"type":"array","items":{"type":"object","properties":{"clientName":{"type":"string"},"product":{"type":"string"},"startDate":{"type":"string","description":"YYYY-MM-DD"},"endDate":{"type":"string","description":"YYYY-MM-DD"},"reasonForLeaving":{"type":"string","description":"Free text — untrusted."},"noticeGiven":{"type":"boolean"},"deposit":{"type":"string","description":"KES, decimal string."},"outstandingAmount":{"type":"string","description":"KES, decimal string."},"action":{"description":"Free text — untrusted.","type":["string","null"]}},"required":["clientName","product","startDate","endDate","reasonForLeaving","noticeGiven","deposit","outstandingAmount","action"],"additionalProperties":false}}},"required":["id","location","month","newClients","clientsRenewed","clientsLeaving","clientsUpgraded","clientsDowngraded","clientsSuspended","netClientGrowth","departures"],"additionalProperties":false}},"nextCursor":{"type":["string","null"],"description":"Pass as `cursor` to get the next page; null on the last page."}}}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An API key, e.g. `bl_live_…`."}},"responses":{"Error":{"description":"An error.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string"},"message":{"type":"string"}}}}}}}}}}}