Cyql GraphQL API

Access Rides, Stats, News, and more via an API-Call

POST /api/graphql

Overview

The Cyql API provides a GraphQL endpoint for querying club data.

All queries are sent as POST requests to /api/graphql with a JSON body containing your query.

Authentication

Every request must include a valid API key in the X-Api-Key header:

POST /api/graphql HTTP/1.1
Host: api.cyql.app
Content-Type: application/json
X-Api-Key: your-api-key-here

{
  "query": "{ clubStats { memberCount } }"
}

API keys are created in the Cyql Dashboard under Settings → API.

Rate Limiting

Each API key has a rate limit that resets weekly. The limits are designed to allow typical usage while preventing abuse. An error with ExceedingApiKeyLimit will be sent back when exceeding.

Rate Limit Headers

X-RateLimit-LimitMax requests allowed per week (For Key)

X-RateLimit-RemainingRequests left for this key

X-RateLimit-Remaining-ClubRequests left for the entire club (all keys combined)

X-RateLimit-ResetReset for next Monday at 00:00 (UTC)

When an error occurs the rate limits will be set to -1 to indicate this state, this can occur when providing and invalid key, the X-RateLimit-Reset will stay the same.

Query Complexity

Each API key has a maximum allowed query complexity. This is what determines the rate limit, see the Complexity section below for details.

Making Requests

To make a request, send a POST to /api/graphql with a JSON body containing your GraphQL query:

POST /api/graphql HTTP/1.1
Host: api.cyql.app
Content-Type: application/json
X-Api-Key: your-api-key-here
            
{
    "query": "query { clubStats { memberCount } }"
}

Responses will be in JSON format, with a data field containing the requested data:

{
    "data": {
        "clubStats": {
            "memberCount": 1234
        } }
}

Errors

Errors follow the standard GraphQL error format:

{
  "errors": [
    {
      "message": "ExceedingApiKeyLimit",
      "extensions": { "code": "ExceedingApiKeyLimit" } 
    }
  ] 
}

Common error codes include:

Error Codes

ApiKeyInvalidThe provided API key is invalid (deleted or incorrect).

ExceedingApiKeyLimitThe API key has exceeded its weekly request limit. Please wait until the limit resets.

ExceedingComplexityBudgetThe club-quota for this week has been exceeded.

ExceedingMaxComplexityPerQueryThe query exceeds the maximum allowed complexity for a single query. Try simplifying your query.

UnknownErrorAn unexpected error occurred. Please try again later or contact support if the issue persists.

Query Complexity Algorithm

Each API query is assigned a complexity cost based on the fields requested and pagination parameters. This prevents expensive queries from consuming too many resources.

How Complexity is Calculated

Base cost: Each field costs 1 point
Nested fields: Fields that contain other fields add 1
Paginated results: Fields named 'items' (in paginated responses) have their cost multiplied by (the page size divided by 10 (base), rounded up)
- Example: requesting 50 items multiplies the cost by 5 (50/10)
- This accounts for the work required to fetch and process larger pages

Example: Calculating Query Cost

query {
  # base cost: 1
  someQuery {
    title             # cost: 1
    description       # cost: 1
  },
  # base cost: 1        
  someOtherQuery(pageSize: 100) {
    items {
      title           # cost: 1 (10 times)
      description     # cost: 1 (10 times)
    }
    totalCount        # cost: 1
    page              # cost: 1
  }
}
          
# Total cost: 3 (someQuery) + 23 (someOtherQuery) = 26

Limits

Per-query limit: Each API key has a maximum complexity per query cannot exceed this. This is usually not a problem however.
Key limit: Keys have individual limits, so you can create multiple keys for different use cases.
Club budget: All API keys for a club share a combined weekly budget to prevent abuse. This budget reset every Monday at 00:00.

Optimization Tips

Request only the fields you need
Use smaller pageSize values when possible, the api returns if a next page is available so you can paginate through results.
Avoid deeply nested queries
Check the rate limit headers in responses to monitor your quota