Get Help
What can we help you with?
Section titled “What can we help you with?”API request errors
Section titled “API request errors”Is the endpoint correct?
Section titled “Is the endpoint correct?”The base URL is https://api.chizumulu.net. Every route is listed in Endpoints; a path that is not listed there returns 404 {"error":"not found"}. Check for a typo, a missing path segment (rawUpdateId, matchId, teamId) and a /v1/ prefix.
Is the HTTP method correct?
Section titled “Is the HTTP method correct?”Every public route is GET only. A different method on a real path is not 405 - it returns 404 {"error":"not found"}, the same as an unknown path. See Read-only.
Invalid query parameters
Section titled “Invalid query parameters”An unrecognized query parameter name is silently ignored. A recognized one that fails validation is a 400 with a message describing the problem (for example cursor is invalid, status must be one of ...). See each route’s parameter table in Endpoints.
400 Bad Request
Section titled “400 Bad Request”Always {"error":"<message>"}. Common causes: a malformed cursor, since, after, rawUpdateId or matchId; an empty filter value (team=, status=); or, for /v1/matches, a status outside its closed enum. The message is for humans, not for matching in code - check the shape of your request against Endpoints, not the exact wording.
404 Not Found
Section titled “404 Not Found”An unknown route, an unknown rawUpdateId/matchId/teamId, or /v1/latest when nothing has been stored yet.
429 Too Many Requests
Section titled “429 Too Many Requests”Requests may be limited by infrastructure or rate-limiting controls in front of the API when request volume is too high. Reduce your request rate and try again after a short wait. If the issue persists, contact Developer Support with the endpoint, request rate, and timestamp.
500/502/503 responses
Section titled “500/502/503 responses”500 {"error":"internal error"} can come from any route on an unexpected failure. 502 {"error":"video feed unavailable"} is specific to /v1/videos and /v1/videos/latest when YouTube is unreachable and nothing is cached. 503 only ever appears on the internal collector-to-API path, never on a public /v1/* route.
CORS errors
Section titled “CORS errors”Public GET responses under /v1/*, /openapi.json and /llms.txt send Access-Control-Allow-Origin: *. The OPTIONS preflight on those routes allows only GET and OPTIONS, no custom request headers and no credentials - a request that adds a header, uses another method or sends credentials will fail preflight by design. See Practical notes.
Why does /v1/live return an empty list?
Section titled “Why does /v1/live return an empty list?”By design: a match is listed there only while it is credibly live right now (fresh update, plausible minute, nothing contradicting it). A quiet result means nothing currently meets that bar, not that the service is broken. See GET /v1/live.
Difference between /v1/live and /v1/matches
Section titled “Difference between /v1/live and /v1/matches”/v1/live is the conservative, presentation-safe subset. /v1/matches is discovery over every derived match the projection knows, including stale or historical ones, with filters. See GET /v1/matches.
Cursor pagination issues
Section titled “Cursor pagination issues”cursor is opaque: pass it back exactly as nextCursor gave it, with the same filters that produced it. An edited or hand-built cursor is 400 cursor is invalid. See Pagination.
Where to find a teamId
Section titled “Where to find a teamId”GET /v1/teams lists every canonicalized id, its display name and its aliases. See GET /v1/teams and Team identifiers.
How to find a matchId
Section titled “How to find a matchId”It is a field of each item from /v1/live or /v1/matches, not something you construct. /v1/structured does not have a matchId - that identifier belongs to the separate derived-match layer. See Derived matches.
How to check API status
Section titled “How to check API status”GET /v1/status reports collector, delivery, data-freshness, processing and media health. See Status.
Where to find the OpenAPI specification
Section titled “Where to find the OpenAPI specification”https://api.chizumulu.net/openapi.json (OpenAPI 3.1). It is the contract for field names, enums and response shapes; a machine-readable summary for agents is at https://api.chizumulu.net/llms.txt.
minute vs minuteText
Section titled “minute vs minuteText”minuteText is the literal clock as written in the source ("45+2'"). minute is deterministically normalized from it (base plus stated stoppage), null when there is no parseable clock. Never an estimate. See minuteText vs minute.
Filtering /v1/matches
Section titled “Filtering /v1/matches”Supported filters are status, competitionCode, teamId, teamAlias and updatedSince, combined with limit/cursor. status is a closed enum (an unsupported value is 400); the others give an empty page for a value that matches nothing. See GET /v1/matches.
Existing integration suddenly behaving differently
Section titled “Existing integration suddenly behaving differently”Check /openapi.json first: field names and shapes there are the contract, and new fields can be added without notice (additive change). Free-text values (processing.error, korean.text, the exact wording of an error message) are explicitly not stable and can change. If the shape itself changed in a way /openapi.json does not explain, email us (below).
Unexpected behavior
Section titled “Unexpected behavior”Data appears stale
Section titled “Data appears stale”The API reflects exactly what the collector observed and when; a quiet upstream feed is normal, not a fault. Check /v1/status for collector/delivery health before assuming something is wrong. See Completeness and timing.
A match is missing from /v1/live
Section titled “A match is missing from /v1/live”/v1/live intentionally omits anything not credibly, freshly live - a stale, ambiguous or finished match is not deleted, it simply is not listed there. Find it at /v1/matches or /v1/matches/{matchId} instead. See GET /v1/live.
A derived match has quality: conflict
Section titled “A derived match has quality: conflict”The projection kept an observation apart because it contradicted the match it would otherwise have joined (for example the status or score moved backward). This is deliberate: a false merge is treated as worse than a missed one. See Derived matches.
Team identity/aliases
Section titled “Team identity/aliases”homeTeam/awayTeam are always the spelling as written in the source; teamId only groups known spellings of the same club. An unreviewed or ambiguous name simply has no id yet - it is never guessed. See Team identifiers and Team aliases.
Unexpected score/status
Section titled “Unexpected score/status”Nothing is corrected: a mistake in the source (a wrong score, an odd status) is returned as written, not fixed. See What the API does not infer.
Structured vs derived data differences
Section titled “Structured vs derived data differences”/v1/structured is one item per observation, faithful to that one post. /v1/live and /v1/matches are a separate, derived projection that stitches several observations of the same real match together under one matchId, conservatively. The two layers can legitimately disagree while both are correct for what they represent. See Raw vs structured and Derived matches.
Feature requests and improvements
Section titled “Feature requests and improvements”- Requesting a new endpoint or filter. Name the endpoint/filter you’d want and the field(s) it should act on.
- Requesting additional match or team data. Say which field is missing and on which route.
- Reporting an integration pain point. Tell us where the current shape or behavior makes your integration harder than it should be.
- Explain the use case. What are you building, and why is the current behavior not enough for it? A concrete example request/response helps more than a general description.
Report a bug
Section titled “Report a bug”- A reproducible API bug. A request that should behave one way per the docs/OpenAPI but does not.
- A documentation bug. Something in these docs,
/openapi.jsonor/llms.txtthat is wrong, missing or contradicts the live API. - An incorrect response shape. A field missing, extra, or of the wrong type versus
/openapi.json. - Incorrect data behavior. The API accepted or returned something that contradicts its own documented rules (not the same as the source data itself being wrong - see Unexpected behavior for that).
- What to include. The exact request (method, URL, query parameters), the full response body, the timestamp, and any
matchId/rawUpdateId/teamIdinvolved - see the diagnostic report format.
Collaboration inquiries
Section titled “Collaboration inquiries”- Integrations. Building a product or service on top of Chizumulu API.
- Data or project collaboration. Working together on the data, the project, or adjacent tooling.
- Research, media or club-related inquiries. Using the data for research, coverage, or club-side purposes.
- Include: your project or organization, the scope of what you have in mind, your intended use of the data, and how to reach you.
Anything that does not fit the categories above - tell us as clearly as you can what you need.
Security
Section titled “Security”Email template
Section titled “Email template”Two templates, depending on why you are writing. Copy the one that fits, fill it in, and send it to dev-support@chizumulu.net.
Diagnostic report
Section titled “Diagnostic report”For API request errors, unexpected behavior and bug reports.
Subject / 제목:Category / 카테고리: (API request errors / Unexpected behavior / Report a bug)Endpoint / 엔드포인트:Request / 요청: (method, full URL, query parameters, headers if relevant)Observed behavior / 실제 동작:Expected behavior / 예상 동작:Timestamp / 발생 시각: (UTC if possible)Relevant IDs / 관련 ID: matchId: rawUpdateId: teamId: other:Response or error / 응답 또는 오류: (full response body/status if available)Reproduction steps / 재현 방법:Additional context / 추가 정보:General inquiry
Section titled “General inquiry”For feature requests, collaboration inquiries and other.
Subject / 제목:Category / 카테고리: (Feature request / Collaboration / Other)Project or organization / 프로젝트 또는 조직:Description / 설명: (the use case, or what you'd like added/changed, and why)Scope and intended use / 범위 및 활용 목적: (for collaboration inquiries)Contact details / 연락처:Additional context / 추가 정보: