Developers

Pilotariak developer portal

Pilotariak publishes Basque pelota data — clubs, competitions, categories, specialties and match results — through two free, open-source interfaces: the Frontis GraphQL API for applications and the Azkena MCP server for AI assistants. Both are read-only.

Quickstart

No sign-up or API key is needed for the GraphQL API. Pick a league and send a query:

List clubs in the LCAPB league
curl -s -X POST https://frontis-gateway.pilotariak.com/graphql \
  -H "Content-Type: application/json" \
  -H "X-Pilotariak-League: lcapb" \
  -d '{"query":"{ clubs { id name } }"}'

Frontis GraphQL API

  • Endpoint: https://frontis-gateway.pilotariak.com/graphql (HTTP POST, JSON body)
  • Authentication: none — the API is public and read-only
  • Required header: X-Pilotariak-League = lcapb (Côte d’Argent), lidfpb (Île-de-France) or ctpb (Comité Territorial)
  • Queries: clubs, club(id), competitions, competition(id), categories, category(id), specialties, specialty(id), results(competitionId, specialtyId, categoryId, phase), result(id), version
  • Schema: standard GraphQL introspection is enabled, so any GraphQL client or code generator can load it
  • Full reference: graphql-api skill · source on GitHub

Azkena MCP server

Azkena exposes the same data as Model Context Protocol tools so assistants such as Claude, Cursor or Codex can query it in natural language. Endpoint: https://mcp.pilotariak.com/mcp (Streamable HTTP, protocol 2026-07-28).

Tools: list_competitions, list_clubs, list_categories, list_specialties, list_results. Every tool takes a league argument.

MCP client configuration
{
  "mcpServers": {
    "pilotariak": {
      "type": "http",
      "url": "https://mcp.pilotariak.com/mcp"
    }
  }
}

Authentication

The GraphQL API and every discovery document on pilotariak.com are public. The MCP server requires an OAuth 2.1 access token: clients register dynamically, a person approves access on the consent screen, and the client exchanges the code with PKCE (S256). An unauthenticated request returns 401 with a WWW-Authenticate header pointing at the protected-resource metadata.

The step-by-step agent walkthrough is in auth.md. Metadata: protected resource (RFC 9728) · authorization server (RFC 8414).

Errors

GraphQL errors follow the GraphQL specification: the response carries an errors array, each entry with a human-readable message and a machine-readable extensions.code (BAD_REQUEST, GRAPHQL_VALIDATION_FAILED, …). The MCP server returns JSON errors such as {"error":"invalid_token"} with standard OAuth error codes.

Missing league header
{
  "errors": [{
    "message": "Missing X-Pilotariak-League header",
    "path": ["clubs"],
    "extensions": { "code": "BAD_REQUEST", "serviceName": "clubs" }
  }],
  "data": null
}

Rate limits, versions and environments

  • Azkena allows 60 requests per minute per client IP; beyond that it answers 429.
  • Frontis has no published quota — cache responses and avoid tight polling loops.
  • Check the deployed gateway version with the { version } query; changes are listed in each project’s GitHub releases.
  • There is no separate sandbox: all interfaces are read-only, so no call can modify data.

Machine-readable discovery

Source code and SDKs

Everything is Apache-2.0 on github.com/Pilotariak, including this website (Pilotariak/website, with an AGENTS.md for coding agents). There is no dedicated SDK: any GraphQL or MCP client library works. Issues and pull requests are welcome.