Plan faster
Calculate match totals and capacity requirements in one request.
01 / Built for competition organisers
A simpler way to plan cricket.
Use the API to estimate and structure a tournament for clubs, schools, community leagues and cricket organisations. It calculates provisional fixtures—not booked grounds, confirmed start times or official results.
Choose a format
Single round robin, double round robin, knockout or groups.
Integrate cleanly
JSON input and output with a published OpenAPI contract.
02 / Public endpoint
One endpoint. Four formats.
POST
https://cricstars.com/api/v1/tournament/planSend Content-Type: application/json. The API accepts only POST requests. GET returns HTTP 405.
03 / Example request
Start with an eight-team tournament.
The example below asks for a single round robin: eight teams playing 20 overs per innings, across two grounds with two slots per ground each day.
curl -X POST 'https://cricstars.com/api/v1/tournament/plan' \
-H 'Content-Type: application/json' \
--data '{"format":"single","teams":8,"overs":20,"grounds":2,"slots":2,"days":30}'04 / Interactive playground
Test a provisional plan.
Send a request to the live API from this page. The playground makes one call each time you press Run; it does not run automatically.
Fixed demonstration settings: 20 overs, 2 grounds, 2 match slots per ground per day, 30 playing days. Group format uses 2 groups and 2 qualifiers per group. Calls count towards your public IP's rate limit.
Select a format and run a request to see the live API response.
05 / Reading the result
Useful output, clearly provisional.
A successful response provides total matches, required playing days, whether it fits the requested day count, an array of proposed fixtures and warnings for organiser review.
{
"status": "provisional",
"format": "single",
"teams": 8,
"totalMatches": 28,
"requiredPlayingDays": 7,
"requestedPlayingDays": 30,
"fitsRequestedDays": true,
"fixtures": [ /* fixture objects omitted here */ ],
"warnings": [ /* organiser review notes */ ]
}The example is illustrative, not a literal JSON response. Use the live playground to inspect fixture objects. The value of requiredPlayingDays depends on capacity and the schedule produced.
06 / Request schema
Every field has a defined range.
| Field | Accepted values | Usage |
|---|---|---|
format | single, double, knockout, groups | Required |
teams | Integer 2–64 | Required |
overs | Integer 1–90 | Required |
grounds | Integer 1–32 | Required |
slots | Integer 1–12 | Required |
days | Integer 1–365 | Required |
groups | Integer 2–16 | Required for groups only |
qualify | Integer 1–8 | Required for groups only |
When using groups, the number of groups cannot exceed the number of teams. The number of qualifiers per group cannot exceed the smallest group's team count. Unknown fields are rejected.
07 / Integration safeguards
Limits and HTTP responses.
10 / 10 seconds
Burst limit per client IP.
30 / 60 seconds
Minute limit per client IP.
Maximum request body: 8,192 bytes. HTTP 429 includes a Retry-After header. Back off when you receive 429 or 503 rather than retrying immediately.
| Status | Meaning |
|---|---|
| 200 | Valid provisional tournament plan returned |
| 400 | Invalid JSON or unsupported input |
| 405 | Method not allowed; POST only |
| 413 | Request body exceeds 8,192 bytes |
| 415 | Content-Type must be application/json |
| 429 | Rate limit exceeded; honour Retry-After |
| 502 / 503 | Gateway or temporary service failure |
08 / Important planning limitation
A draft, not an official fixture list.
Knockout participants may be placeholders. The engine does not confirm actual match start times, ground availability, rest periods, weather reserve days or local competition rules. Competition organisers must review all fixtures before publishing.
Need an interactive planning experience rather than JSON integration? Use the Cricstars Tournament Format Planner.
09 / Frequently asked questions
Questions developers ask.
Does this API publish fixtures automatically?
No. It produces provisional fixtures for organiser review. You decide when and whether to publish them.
Can I plan group-stage competitions?
Yes. Set format to groups and provide groups and qualify in addition to the common required fields.
Can AI agents call the API?
Yes, when an AI platform allows a configured external HTTP tool or API connection. The OpenAPI 3.1 specification describes the contract; publishing it does not automatically connect every AI assistant.
Can I request real venue booking times?
No. The API works with numbered playing days, grounds and slots, not confirmed venue calendars.