Skip to content

Get Help

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.

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.

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.

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.

An unknown route, an unknown rawUpdateId/matchId/teamId, or /v1/latest when nothing has been stored yet.

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 {"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.

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.

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 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.

GET /v1/teams lists every canonicalized id, its display name and its aliases. See GET /v1/teams and Team identifiers.

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.

GET /v1/status reports collector, delivery, data-freshness, processing and media health. See Status.

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.

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.

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).

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.

/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.

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.

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.

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.

/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.

  • 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.
  • 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.json or /llms.txt that 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/teamId involved - see the diagnostic report format.
  • 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.

Two templates, depending on why you are writing. Copy the one that fits, fill it in, and send it to dev-support@chizumulu.net.

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 / 추가 정보:

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 / 추가 정보: