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

curl -H "Authorization: Bearer YOUR_TOKEN" \
     "https://developers.counttogether.app/v2/counters?timezone=Europe/Berlin"

Successful 200 response:

[
  {
    "id": "018f5b54-9b11-7c33-b347-a2b4e2a6a111",
    "name": "Daily Steps",
    "type": "UpDown",
    "value": 12450,
    "created": "2025-01-01T00:00:00Z"
  },
  {
    "id": "018f5b54-9b11-7c33-b347-a2b4e2a6a222",
    "name": "Running Streak",
    "type": "FromDate",
    "startDate": "2025-01-01",
    "value": 45,
    "created": "2025-01-01T00:00:00Z"
  }
]

3. Increment a Counter

curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  https://developers.counttogether.app/v2/counters/018f5b54-9b11-7c33-b347-a2b4e2a6a111/increment

Response: 12451

Or increment by a custom amount:

curl -X POST -H "Authorization: Bearer YOUR_TOKEN" \
  https://developers.counttogether.app/v2/counters/018f5b54-9b11-7c33-b347-a2b4e2a6a111/increment/5

Response: 12456

4. Open a WebSocket for Real-Time Updates

wscat -c "wss://developers.counttogether.app/v2/ws?timezone=Europe/Berlin" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example incoming JSON-RPC 2.0 notification:

{
  "jsonrpc": "2.0",
  "method": "counterUpdated",
  "params": {
    "counterId": "018f5b54-9b11-7c33-b347-a2b4e2a6a111",
    "name": "Daily Steps",
    "type": "UpDown",
    "value": 12456
  }
}

Other events: counterDeleted, counterMemberlistChanged.

5. Handle Errors

Error example (invalid token):

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

See: Error Handling

6. Next Steps

21 April 2026