Cyql GraphQL API

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

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.

Query Builder

Build GraphQL queries visually by selecting fields and configuring arguments.

query {
  # Select a query to see preview
}

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 (or ExceedingComplexityBudget for the club quota) will be sent back when exceeding, with HTTP status 429 Too Many Requests and a Retry-After header containing the number of seconds until the limit resets. Do not retry before that time.

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:

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

Schema Reference

Auto-generated from the GraphQL schema. Click a type to expand its fields.

Queries

Types

Paged Results

Enums