Counters Endpoint
Retrieve all counters accessible to the authenticated user.
GET /v1/counters
Returns an array of Counter objects.
Request
Headers:
Curl:
Successful Response (200)
Empty Result
If the user owns or shares no counters, the endpoint returns [].
Authentication Errors
Missing / invalid token →
401 Unauthorized
Error Body (Business Errors)
Errors generated inside the pipeline use the structure documented in Errors.
Notes
No pagination yet (the typical number of counters per user is expected to be small). Pagination may be introduced later; treat additional unknown top-level fields as forward-compatible.
The endpoint is idempotent and safe.
Field Reference (Counter)
Field | Type | Description |
|---|---|---|
id | string (UUID v7) | Unique counter identifier |
displayName | string | Human readable name (5..40 chars) |
type | enum | Counter category controlling |
members | array | Current member list (see Data Models) |
data | object or null | Type-specific payload |
See Counter Data Models for data shapes.
Mutating Endpoints for UpDown Counters
POST /v1/counters/{counterId}/increment
Increment the value of an UpDown counter by 1. Returns the new numeric value as a plain number.
Request example:
Response (200):
POST /v1/counters/{counterId}/decrement
Decrement the value by 1 (only if the counter mode permits decrement operations). Returns the new value.
Response (200):
Possible Errors
HTTP | Code | Reason |
|---|---|---|
400 | InvalidOperationForCounterType | Counter type not UpDown or mode disallows operation |
401 | (auth) | Missing or invalid token |
403 | (authz) | User not a member / lacks permission |
404 | NotFound | Counter does not exist or not visible |
Realtime Integration
Successful mutations emit a JSON-RPC notification with method: "counterUpdated" containing the updated state.
Idempotency
Not idempotent. Repeating the same POST increments/decrements again.
Rate Limiting
These requests count towards the same sliding window user limit. Excessive mutation may lead to 429 responses.