API Documentation

Base URL

https://api.cordax.net

JSON is the default output unless noted otherwise.

Interactive Explorer

The user-facing examples page now acts as an interactive API explorer. It uses same-origin proxy routes on this site, and those proxy routes attach a configured free-tier Bearer token on the server.

Interactive testing happens from the Examples page.
The browser never needs to know the free-tier demo token.
Configure the token in ApiDocs:DemoBearerToken.
External apps and server-to-server requests should still send Authorization: Bearer YOUR_TOKEN.

This keeps the interactive examples usable without exposing your free-tier token in frontend JavaScript.

Query Builder

The site now includes a dedicated Query Builder section for derived historical football questions. This sits above the raw fixture/resource API and is intended to expose answers rather than source-shaped event feeds.

The page route is /QueryBuilder.
The API route is POST /QueryBuilder/Search.
The first version uses a controlled parser rather than open-ended AI SQL generation.
Supported patterns include came from behind to win, conceded first but avoided defeat, scored in the last N minutes, won after trailing at half time, and team-specific late-goal losses.
The implementation lives in api/QueryBuilder/PatternSearchService.cs and api/QueryBuilder/PatternSearchRepository.cs.
To add new supported questions, extend PatternSearchType, add a parser branch in ParseQuery(...), and add the corresponding result logic in SearchAsync(...).
The current implementation queries normalized fixture and action data directly from MySQL rather than using the public fixtures API response shape.

Structured JSON request

{
  "PatternType": "CameFromBehindToWin",
  "Competition": "Premier League",
  "FromDateUtc": "2020-01-01",
  "ToDateUtc": "2026-04-05",
  "WidgetMode": "summary",
  "Format": "json"
}

Supported request fields

QueryText: optional natural-language query. The site UI currently uses structured fields instead, but the API still accepts text queries.
PatternType: one of CameFromBehindToWin, ConcededFirstAvoidedDefeat, ScoredLateOften, WonAfterTrailingAtHalfTime, or TeamScoredLateAndLost.
Competition: optional competition filter.
Team: optional team filter, used mainly for team-specific late-loss searches.
FromDateUtc/ToDateUtc: optional date scoping.
SinceYear: still supported by the API for convenience, but the website UI now uses explicit dates instead.
LateMinuteThreshold: optional minute threshold for late-goal patterns. Defaults to 85.
Format: json or widget.
WidgetMode: when Format=widget, use summary for team totals or detail for individual matching fixtures. This can also be passed as ?widgetMode=summary in the URL.

Examples

curl -X POST "https://api.cordax.net/QueryBuilder/Search" ^
  -H "Authorization: Bearer YOUR_TOKEN" ^
  -H "Content-Type: application/json" ^
  -d "{\"PatternType\":\"ScoredLateOften\",\"Competition\":\"Premier League\",\"FromDateUtc\":\"2020-01-01\",\"ToDateUtc\":\"2026-04-05\",\"LateMinuteThreshold\":85}"

curl -X POST "https://api.cordax.net/QueryBuilder/Search" ^
  -H "Authorization: Bearer YOUR_TOKEN" ^
  -H "Content-Type: application/json" ^
  -d "{\"QueryText\":\"teams that came from behind to win in the Premier League since 2020\",\"Format\":\"widget\"}"

curl -X POST "https://api.cordax.net/QueryBuilder/Search?widgetMode=summary" ^
  -H "Authorization: Bearer YOUR_TOKEN" ^
  -H "Content-Type: application/json" ^
  -d "{\"PatternType\":\"CameFromBehindToWin\",\"Competition\":\"Premier League\",\"FromDateUtc\":\"2020-01-01\",\"ToDateUtc\":\"2026-04-05\",\"Format\":\"widget\",\"WidgetMode\":\"summary\"}"

Authentication

GET /Account/Login

GET /Account/Register

GET /Dashboard

What is in place

Email/password accounts via ASP.NET Core Identity
Google sign-in support when client credentials are configured
A protected dashboard page for signed-in users
Bearer API tokens generated from the dashboard
Request logging to API_USAGE for authenticated API calls

Database setup

User accounts are stored in the existing FootyResults MySQL database.
The app currently expects the Identity tables to already exist.
Run the generated SQL in api/AuthSchema.sql before using account features.
Run api/schema.sql to create API_CLIENT, API_KEY, and API_USAGE.
Run api/billing-schema.sql to add API_PLAN and the Stripe subscription columns on API_CLIENT.

Identity tables

AspNetUsers
AspNetRoles
AspNetUserClaims
AspNetUserLogins
AspNetUserRoles
AspNetUserTokens
AspNetRoleClaims

API token tables

API_CLIENT
API_KEY
API_USAGE
API_PLAN

Google configuration

Set these config values before Google login will appear on the login page:

Authentication:Google:ClientId
Authentication:Google:ClientSecret

Stripe configuration

Set these config values before Stripe checkout will work:

Stripe:SecretKey
Stripe:WebhookSecret

Billing flow

Plans are stored in API_PLAN with codes FREE and PREMIUM.
Paid plans are monthly Stripe subscriptions created from the dashboard.
Upgrades apply immediately and Stripe charges the prorated difference for the rest of the billing period.
Downgrades, including switching to FREE, are scheduled for the end of the current billing period.
Checkout returns to /Billing/Success.
Stripe should POST subscription events to https://api.cordax.net/Billing/Webhook.
API_CLIENT stores the Stripe customer ID, subscription ID, pending plan, status, and current period end.

Bearer token flow

Create an account or sign in.
Open /Dashboard and generate an API token.
Copy the token immediately. Only its hash is stored in the database.
Send it on every football data request as Authorization: Bearer your_token.
Deactivate a token from the dashboard when needed.

Tier capability policy

Plan-specific API capabilities are defined in api/Auth/ApiAccessPolicyService.cs.
The current fixture rule is: FREE tokens only receive action events for fixtures in the last 12 hours.
To add another plan later, add a new branch in GetPolicy(planCode) and return the appropriate limits.
The fixtures endpoint applies the policy in api/Controllers/FixturesController.cs before rendering JSON, XML, or widget output.
Keep API_PLAN.CODE values aligned with the plan codes used in ApiAccessPolicyService.

Example header

Authorization: Bearer cordax_xxxxxx.yyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyyy

Examples

https://api.cordax.net/Account/Login
https://api.cordax.net/Account/Register
https://api.cordax.net/Dashboard
https://api.cordax.net/Billing/Webhook

Standings

GET /Standings/{league}/{season}

GET /Standings/{league}/{division}/{season}

GET /Standings/{league}/{season}/format/widget

GET /Standings/{league}/{division}/{season}/format/widget

Parameter	Required	Notes
`league`	Yes	Competition name, URL encoded.
`division`	No	Use only when the competition has divisions.
`season`	Yes	Current format is slug-style, for example `2025-26`.

Examples

curl -H "Authorization: Bearer YOUR_TOKEN" "https://api.cordax.net/Standings/Premier%20League/2025-26"

The HTML widget view only shows: TEAM_NAME, PLAYED, WON, DRAWN, LOST, GD, PTS, FORM. JSON returns the full stored procedure result.

Fixtures

GET /Fixtures

GET /Fixtures/{key}/{value}/...

Query parameter	Required	Notes
`from`	No	Date filter in `yyyy-MM-dd` format. Supports `today`.
`to`	No	Date filter end in `yyyy-MM-dd` format. Supports `today`.
`competition`	No	Competition name.
`division`	No	Division name.
`season`	No	Competition season, for example `2025-26`.
`team`	No	Matches where the team is either home or away.
`status`	No	`active` or an exact match such as `HT`, `FT`, `PENS`, `AET`, `Awarded`, `Scheduled`, `Suspended`, `Match Postponed`, or `Match Cancelled`.
`format`	No	`json`, `xml`, or `widget`. Default is `json`.

Examples

curl -H "Authorization: Bearer YOUR_TOKEN" "https://api.cordax.net/Fixtures/team/Portsmouth/season/2025-26/competition/Championship/status/active"

status=active includes in-play minute statuses plus HT and FT. Any other supplied status is matched directly against MATCH_STATUS. format=widget returns an embeddable fixture widget fragment.

Competitions

GET /Competitions

GET /Competitions/{key}/{value}/...

Query parameter	Required	Notes
`country`	No	Filters competitions to a country name such as `England`.

Examples

curl -H "Authorization: Bearer YOUR_TOKEN" "https://api.cordax.net/Competitions/country/England"

Known competition examples

COMPETITION_ID	COMPETITION	COUNTRY_ID	CODE
1	Premier League	1	Premier League
2	Championship	1	Championship
3	League One	1	League One
4	League Two	1	League Two
5	National League	1	National League
6	National League N / S	1	National League N / S

Competition Seasons

GET /CompetitionSeasons

Query parameter	Required	Notes
`competition`	No	Competition name filter.
`division`	No	Division name filter. Leave blank for competitions without divisions.
`description`	No	Season description filter, for example `2025-26`.

Examples

curl -H "Authorization: Bearer YOUR_TOKEN" "https://api.cordax.net/CompetitionSeasons?competition=Championship&description=2025-26"

Competition Season Teams

GET /Competition

Query parameter	Required	Notes
`competition`	No	Competition name filter.
`description`	No	Season description filter, for example `2025-26`.

Examples

curl -H "Authorization: Bearer YOUR_TOKEN" "https://api.cordax.net/Competition?competition=National%20League%20N%20%2F%20S&division=North&description=2025-26"

Returns the distinct teams found through FIXTURE rows for the selected competition, optional division, and season.

Base URL

Interactive Explorer

Query Builder

Authentication

Standings

Fixtures

Competitions

Competition Seasons

Competition Season Teams