Documentation

Quickstart

1. Get an API key

Sign up and generate an API key from your dashboard. Keys are prefixed with sk_.

2. Make your first request

Send a POST request to the /api/v1/check-consume endpoint with a subject, metric, and cost.

curl https://api.countr.dev/api/v1/check-consume \
  -H "Authorization: Bearer sk_xxx" \
  -d '{"subject":"user_123","metric":"api_calls","cost":1}'

3. Endpoints

POST/api/v1/check-consume

Checks whether a subject is within their limit for a given metric, then records the usage. Returns allowed: true and a remaining quota value when the request is permitted (where remaining is a number, or null when no limit is configured / quota is unlimited), or allowed: false with reason: "limit_exceeded" when the limit would be exceeded.

Authorization

Authorization: Bearer <token>

Pass your API key as a Bearer token.

Request body

{
  "subject": "user_123",   // string, required, max 200 chars
  "metric":  "api_calls",  // string, required, max 200 chars
  "cost":    1             // positive integer, required
}

Success response · 200 · allowed

{
  "allowed":   true,
  "remaining": 997,
  "reason":    null
}

Success response · 200 · denied

{
  "allowed":   false,
  "remaining": 0,
  "reason":    "limit_exceeded"
}

Error response · 400 / 401

{
  "error": {
    "code":    "validation_error",
    "message": "Invalid request body",
    "details": {
      "cost": "Cost must be a positive integer"
    }
  }
}

Possible error.code values: validation_error (400 — invalid or missing fields), invalid_json (400 — malformed JSON body), unauthorized (401 — missing or invalid API key), service_unavailable (503 — Redis not configured or temporarily unreachable), server_error (500 — unexpected internal error).

GET/api/v1/health

Returns the current service status and infrastructure readiness. No authentication required.

Success response · 200

{
  "status": "ok",
  "service": "countr",
  "environment": "unknown",
  "redisConfigured": true
}