{"openapi":"3.0.3","info":{"title":"TMFAST Feed API","version":"1.0.0","description":"Posts competition graphics to Discord, edits the posted messages later, and serves TMFAST Feed competition and player data from Cloudflare D1.\n\n**Authentication.** Send the key as `x-api-key` or `Authorization: Bearer <key>`. Only `GET /health`, `GET /docs`, `GET /openapi.json` and the public picture `GET /comp/<id>.png` skip it. If the Worker has no `API_KEY` set, nothing is protected.\n\n**Errors** are JSON: `{ \"ok\": false, \"error\": \"...\" }`.\n\n**CPU.** Drawing a full-size graphic needs more CPU than a Cloudflare Free plan request gets (10 ms), so JSON `POST /post` and uncached picture requests can answer `503 error code: 1102`. The CLI avoids that by uploading a PNG it drew locally.","contact":{"name":"TMFAST Feed","url":"https://tmfast.au"}},"servers":[{"url":"https://results.pengi.au"}],"tags":[{"name":"Posting","description":"Draw and post graphics, then edit the posted messages."},{"name":"Images","description":"Public picture links for Discord and browsers."},{"name":"Reading","description":"Competitions and players from D1."},{"name":"Meta","description":"Service health."}],"security":[{"ApiKeyAuth":[]}],"paths":{"/post":{"post":{"tags":["Posting"],"summary":"Post a competition","operationId":"postCompetition","description":"Draws the graphic, posts it to the webhook for the competition's `tier`, and saves the competition to D1. `POST /`, `/leaderboard` and `/render` are aliases.\n\nSend `Accept: image/png` to get the picture back without posting or saving anything.\n\nThe CLI sends `multipart/form-data` with the picture it has already drawn: `payload_json` holds the competition and `files[0]` the PNG. A request that carries a picture is not drawn again on the Worker.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompetitionInput"}},"multipart/form-data":{"schema":{"type":"object","required":["payload_json"],"properties":{"payload_json":{"type":"string","description":"The competition, as JSON.","example":"{\"comp\":\"SCC Division 5\",\"id\":\"scc-d5\",\"results\":[\"A\",\"B\",\"C\"]}"},"files[0]":{"type":"string","format":"binary","description":"The PNG to post, already drawn."}}}}}},"responses":{"200":{"description":"Posted and saved (or the PNG, when `Accept: image/png` was sent).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostResponse"}},"image/png":{"schema":{"type":"string","format":"binary"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorised"},"500":{"$ref":"#/components/responses/Failed"}}}},"/comps/{id}/edit":{"post":{"tags":["Posting"],"summary":"Edit a posted graphic","operationId":"editCompetition","description":"Draws the competition again and edits the Discord message that was posted for it. Needs the database. `POST /comps/{id}/repost` is the old name. The edit goes to the webhook recorded when the message was posted.\n\n`multipart/form-data` works here too, with `payload_json` and `files[0]`; `pnpm run edit` and `pnpm fix rename` send their PNG that way.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"scc-d5"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditRequest"}},"multipart/form-data":{"schema":{"type":"object","properties":{"payload_json":{"type":"string","description":"The request, as JSON."},"files[0]":{"type":"string","format":"binary","description":"The PNG to use."}}}}}},"responses":{"200":{"description":"The message was edited.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EditResponse"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorised"},"404":{"description":"No such competition (and no `body` sent)."},"409":{"description":"No Discord message id is recorded; send `message`."},"422":{"description":"Fewer than 3 results, or the body cannot be drawn."},"500":{"$ref":"#/components/responses/Failed"}}}},"/comp/{id}.png":{"get":{"tags":["Images"],"summary":"Competition picture","operationId":"competitionImage","security":[],"description":"A picture of the competition, drawn from the database. Public, so the link works in Discord and in a browser preview. `/comps/{id}.png` also works.\n\nThe picture is cached for 10 minutes and answered with an `ETag`. Every uncached picture is drawn inside the request, which can exceed the Free plan's CPU budget and answer `503 error code: 1102`.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"scc-d5"}],"responses":{"200":{"description":"The picture.","content":{"image/png":{"schema":{"type":"string","format":"binary"}}}},"304":{"description":"The `ETag` matches; nothing changed."},"404":{"description":"No such competition, or pictures are switched off with `COMP_IMAGES=off`."},"422":{"description":"Fewer than 3 results, or the competition cannot be drawn."}}}},"/comps":{"get":{"tags":["Reading"],"summary":"List competitions","operationId":"listCompetitions","description":"Competitions, newest first, with the winner of each. Needs a bound D1 database.","parameters":[{"name":"tier","in":"query","schema":{"type":"string"},"example":"TMFAST"},{"name":"type","in":"query","schema":{"type":"string","enum":["solo","team","duel"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"The competitions.","content":{"application/json":{"schema":{"type":"object","required":["ok","count","comps"],"properties":{"ok":{"type":"boolean","example":true},"count":{"type":"integer","example":1},"comps":{"type":"array","items":{"$ref":"#/components/schemas/CompetitionSummary"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorised"},"501":{"$ref":"#/components/responses/NoDatabase"}}}},"/comps/{id}":{"get":{"tags":["Reading"],"summary":"One competition","operationId":"getCompetition","description":"One competition with its results, ordered by placement. Add `raw=1` for the request it was posted with.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"example":"scc-d5"},{"name":"raw","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"The competition and its results.","content":{"application/json":{"schema":{"type":"object","required":["ok","comp","results"],"properties":{"ok":{"type":"boolean","example":true},"comp":{"$ref":"#/components/schemas/CompetitionDetail"},"results":{"type":"array","items":{"$ref":"#/components/schemas/Result"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorised"},"404":{"description":"No such competition."},"501":{"$ref":"#/components/responses/NoDatabase"}}}},"/players":{"get":{"tags":["Reading"],"summary":"List players","operationId":"listPlayers","description":"Players with their totals, best first. Needs a bound D1 database.","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Part of a name.","example":"pengi"},{"name":"country","in":"query","schema":{"type":"string"},"example":"au"},{"name":"state","in":"query","schema":{"type":"string"},"example":"nsw"},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":200,"default":50}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"The players.","content":{"application/json":{"schema":{"type":"object","required":["ok","count","players"],"properties":{"ok":{"type":"boolean","example":true},"count":{"type":"integer","example":1},"players":{"type":"array","items":{"$ref":"#/components/schemas/PlayerStats"}}}}}}},"401":{"$ref":"#/components/responses/Unauthorised"},"501":{"$ref":"#/components/responses/NoDatabase"}}}},"/players/{key}":{"get":{"tags":["Reading"],"summary":"One player","operationId":"getPlayer","description":"One player: current name, region, totals, every name they have had, and their results. Old names resolve to the same account.","parameters":[{"name":"key","in":"path","required":true,"schema":{"type":"string"},"description":"A Trackmania account id, or any display name the player has had.","example":"PengiTM"}],"responses":{"200":{"description":"The player.","content":{"application/json":{"schema":{"type":"object","required":["ok","player","names","history"],"properties":{"ok":{"type":"boolean","example":true},"player":{"$ref":"#/components/schemas/PlayerStats"},"names":{"type":"array","items":{"type":"object","properties":{"ign":{"type":"string"},"first_seen":{"type":"string","format":"date-time"},"last_seen":{"type":"string","format":"date-time"}}}},"history":{"type":"array","items":{"type":"object","properties":{"competition_id":{"type":"string"},"competition":{"type":"string"},"end_date":{"type":"string","nullable":true},"placement":{"type":"integer"},"written_as":{"type":"string"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorised"},"404":{"description":"No account or name matches."},"501":{"$ref":"#/components/responses/NoDatabase"}}}},"/health":{"get":{"tags":["Meta"],"summary":"Service health","operationId":"health","security":[],"description":"`{ \"ok\": true }`. With `details=1` and the key it also lists which settings and secrets the deployed Worker can see, as yes or no, never their values.","parameters":[{"name":"details","in":"query","schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"The Worker is up.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Health"}}}}}}}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"},"BearerAuth":{"type":"http","scheme":"bearer"}},"responses":{"BadRequest":{"description":"The body is not valid JSON or not a competition.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorised":{"description":"Missing or wrong API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NoDatabase":{"description":"No D1 database is bound to the Worker (binding name: DB).","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Failed":{"description":"Drawing, Discord or the database failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Error":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","example":false},"error":{"type":"string","example":"No competition with id \"nope\""}}},"ResultInput":{"oneOf":[{"type":"string","title":"Solo player name"},{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Team Abyssal"},"members":{"type":"array","items":{"type":"string"}},"logo":{"type":"string","format":"uri","nullable":true},"score":{"type":"integer","description":"Duel sides only.","example":1142}}}]},"CompetitionInput":{"type":"object","required":["comp","id","results"],"properties":{"comp":{"type":"string","description":"Title drawn on the graphic.","example":"SCC Division 5"},"id":{"type":"string","description":"Unique, stable id. Posting the same id again updates that competition.","example":"scc-d5"},"results":{"type":"array","minItems":3,"description":"Finishing order; only the top 3 are drawn, all are saved.","items":{"$ref":"#/components/schemas/ResultInput"}},"tier":{"type":"string","description":"Picks the Discord webhook.","example":"TMFAST"},"type":{"type":"string","enum":["solo","team","duel"],"default":"solo"},"date":{"type":"string","description":"Date on the graphic, exactly as written.","example":"01/10/26"},"start-date":{"type":"string","description":"Stored, never drawn.","example":"26/09/26"},"end-date":{"type":"string","example":"27/09/26"},"description":{"type":"string","example":"Division 5 of the Southern Cross Cup."},"comp-logo":{"type":"string","format":"uri"},"flags":{"type":"string","enum":["off"],"description":"`off` hides player flags."},"stateflags":{"type":"string","enum":["off"],"description":"`off` shows the Australian flag instead of a state flag."},"flag-overrides":{"type":"object","additionalProperties":{"type":"string"},"example":{"Hollist.":"au"}},"scale":{"type":"number","default":0.75,"description":"Smaller values are honoured; larger ones are clamped to 0.75."}},"additionalProperties":true},"EditRequest":{"type":"object","properties":{"body":{"allOf":[{"$ref":"#/components/schemas/CompetitionInput"}],"description":"A competition to draw and save first."},"message":{"type":"string","description":"Discord message id, for graphics posted before the Worker recorded ids."},"fromFile":{"type":"boolean","description":"`true` when `body` came from the competition file, so the answer skips the \"change the file too\" warning."}},"additionalProperties":true},"PlayerReport":{"type":"object","properties":{"name":{"type":"string"},"flag":{"type":"string","nullable":true,"example":"au"},"source":{"type":"string","enum":["logo","flag","placeholder"]},"why":{"type":"string","description":"Present for a placeholder: why no picture was found."}}},"PostResponse":{"type":"object","required":["ok","posted","message"],"properties":{"ok":{"type":"boolean","example":true},"posted":{"type":"boolean","example":true},"stored":{"type":"boolean","description":"Only when a database is bound; `false` means the post went out but saving failed."},"renderer":{"type":"string","example":"cloudflare-worker"},"message":{"type":"string","example":"**Hollist.** won **SCC Division 5**!"},"players":{"type":"array","items":{"$ref":"#/components/schemas/PlayerReport"}}}},"EditResponse":{"type":"object","required":["ok","edited","id","message"],"properties":{"ok":{"type":"boolean","example":true},"edited":{"type":"boolean","example":true},"id":{"type":"string","example":"scc-d5"},"messageId":{"type":"string","example":"1234567890123456789"},"message":{"type":"string"},"imageUrl":{"type":"string","nullable":true,"format":"uri"},"source":{"type":"string","enum":["the database","the body you sent","the competition file"]},"stored":{"type":"boolean"},"warnings":{"type":"array","items":{"type":"string"}},"players":{"type":"array","items":{"$ref":"#/components/schemas/PlayerReport"}}}},"CompetitionSummary":{"type":"object","properties":{"id":{"type":"string","example":"scc-d5"},"name":{"type":"string","example":"SCC Division 5"},"type":{"type":"string","enum":["solo","team","duel"]},"tier":{"type":"string","nullable":true,"example":"TMFAST"},"start_date":{"type":"string","nullable":true,"example":"2026-10-01"},"end_date":{"type":"string","nullable":true,"example":"2026-10-01"},"source":{"type":"string","enum":["repo","worker"]},"posted_at":{"type":"string","nullable":true,"format":"date-time"},"winner":{"type":"string","nullable":true,"example":"Hollist."}}},"CompetitionDetail":{"type":"object","properties":{"id":{"type":"string","example":"scc-d5"},"name":{"type":"string","example":"SCC Division 5"},"description":{"type":"string","nullable":true},"logo_url":{"type":"string","nullable":true},"tier":{"type":"string","nullable":true},"type":{"type":"string","enum":["solo","team","duel"]},"start_date":{"type":"string","nullable":true},"end_date":{"type":"string","nullable":true},"source":{"type":"string","enum":["repo","worker"]},"posted_at":{"type":"string","nullable":true,"format":"date-time"},"discord_message_id":{"type":"string","nullable":true},"raw":{"type":"object","description":"Only with `raw=1`: the request the competition was posted with.","additionalProperties":true}}},"Result":{"type":"object","properties":{"placement":{"type":"integer","example":1},"participant_name":{"type":"string","example":"Hollist."},"team_members":{"type":"array","items":{"type":"string"},"nullable":true},"team_logo_url":{"type":"string","nullable":true},"score":{"type":"integer","nullable":true,"description":"Duel sides only."}}},"PlayerStats":{"type":"object","properties":{"account_id":{"type":"string","example":"b1f0d9b6-7d3f-4b1c-9f27-2b0c1e2c9a44"},"ign":{"type":"string","example":"Hollist."},"region":{"type":"string","nullable":true,"example":"New South Wales, Australia"},"country_code":{"type":"string","nullable":true,"example":"au"},"state":{"type":"string","nullable":true,"example":"nsw"},"competitions":{"type":"integer","example":12},"wins":{"type":"integer","example":3},"podiums":{"type":"integer","example":5},"best_placement":{"type":"integer","nullable":true,"example":1},"first_competition":{"type":"string","nullable":true,"example":"2026-03-01"},"last_competition":{"type":"string","nullable":true,"example":"2026-10-01"}}},"Health":{"type":"object","required":["ok"],"properties":{"ok":{"type":"boolean","example":true},"renderer":{"type":"string","example":"cloudflare-worker"},"configured":{"type":"object","description":"Only with `details=1` and the key. Never contains values, only yes or no.","additionalProperties":true}}}}}}