Quickstart

This guide gets you calling the CountTogether Public API in minutes.

1. Get an API Token

Obtain a personal API token from the settings of your CountTogether app. Tokens are long‑lived unless revoked.

2. Perform Your First Request

Example (curl):

curl -H "Authorization: Bearer YOUR_TOKEN" \
     https://developers.counttogether.app/v1/counters

Successful 200 response:

[
  {
    "id": "018f5b54-9b11-7c33-b347-a2b4e2a6a111",
    "displayName": "Daily Steps",
    "type": "UpDown",
    "members": [
      {
        "userId": "4f9b0c9d-9d3d-4f2b-9c97-5d6c3f0e4c11",
        "displayName": "You",
        "isAdmin": true
      }
    ],
    "data": { "value": 12450, "mode": "UpAndDown" }
  }
]

3. Open a WebSocket for Real-Time Updates

wscat -c wss://developers.counttogether.app/v1/ws -H "Authorization: Bearer YOUR_TOKEN"

Example incoming JSON-RPC 2.0 notification:

{
  "jsonrpc": "2.0",
  "method": "counterUpdated",
  "params": {
    "counterId": "018f5b54-9b11-7c33-b347-a2b4e2a6a111",
    "displayName": "Daily Steps",
    "data": { "value": 12500, "mode": "UpAndDown" }
  }
}

Other events: counterDeleted, counterMemberlistChanged.

4. Handle Errors

Error example (invalid token):

{ "message": "The requested resource was not found.", "code": -1100 }

See: Error Handling

5. Next Steps

Last modified: 01 October 2025