Organizers

AI reviews for every game in your event

Run a league or a tournament? Your site sends each finished game to Kifubara and gets back a review link that players can open right away. No account needed to view the result.

POST https://kifubara.app/api/integrations/analyze

You need a key to send games. Write to us and we'll send you an invite link. It sets up your integration and gives you its key. After that, your key and a ready-to-run example are always under Account settings > Integrations.

What players see

1. They open the link, and the game opens on Kifubara. Your event's name, season, group or round are shown above the board, with an optional link back to the game's page on your website.
2. The whole review is there: the win rate graph, the game's turning points and biggest mistakes, and the AI's suggestions for every move. Nobody has to sign in to view it.
3. Signed-in players can comment on moves and try their own variations. They can't change the review itself, so everyone sees the same analysis. To keep their own notes, they can make a copy.

The game is unlisted: it doesn't appear in Kifubara's public games list, and only people with the link can open it.

Send a game

curl -X POST https://kifubara.app/api/integrations/analyze \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sgf": "(;GM[1]FF[4]SZ[19]KM[6.5];B[pd];W[dp])",
    "match_id": "s46-gA-black-white",
    "season": "46",
    "group": "A",
    "round": "2"
  }'

The response comes back right away, before the analysis has run:

{
  "game_id": "8fe45241-…",
  "share_url": "https://kifubara.app/share/p580zq7I",
  "state_url": "https://kifubara.app/api/integrations/games/8fe45241-…/state",
  "match_id": "s46-gA-black-white",
  "deduped": false
}

share_url is the link to give players. It works right away: the page shows the game, and the analysis appears on its own a few minutes later, so you don't need to wait for it.

Fields

Only sgf is required. The rest of the fields are optional. You can use them to customize what players see.

You can also upload the SGF as a multipart file (field sgf or file) and send the other fields as form fields.

Sending the same game twice

That's fine. Sending the same match_id, or the same SGF, returns the same game and the same link ("deduped": true, status 200). Any fields you include update what players see, and fields you leave out stay as they were. You can also send games from earlier in the season.

Check on games

This is optional. To see how a game's analysis is going:

GET https://kifubara.app/api/integrations/games/<game_id>/state

{
  "game_id": "8fe45241-…",
  "state": "analyzing",
  "pct": 42,
  "share_url": "https://kifubara.app/share/p580zq7I",
  "match_id": "s46-gA-black-white",
  "failure_message": null,
  "retryable": null
}

state moves from queued to analyzing (with progress in pct) to done. If something goes wrong, it's error, with a failure_message. retryable: false means the problem is in the SGF itself (e.g. an illegal move): fix it, delete the game, and send it again.

GET https://kifubara.app/api/integrations/games

Lists every game you've sent, newest first, in the same format (items, count, total, limit, offset). Optional filters: state (queued, analyzing, done, error or pending), match_id, season, group, round, limit (up to 500) and offset.

DELETE https://kifubara.app/api/integrations/games/<game_id>

Deletes the game, its review and its link. Useful for test games.

GET requests also accept the key as ?token=YOUR_KEY, so you can check things quickly in a browser. From your server, use the header.

How deep the analysis goes

Every integration starts with a quick analysis of every move (100 visits per move). For a deeper analysis (2,500 visits per move), write to us. The depth is set for the whole integration, so every game in your event gets the same analysis. There's no per-game setting.

Errors

Your key

Keep your key on your server: anyone who has it can send games as your event. If it leaks, make a new one on your integration's page. The old one will stop working.

Example

import requests

KEY = "YOUR_KEY"
r = requests.post(
    "https://kifubara.app/api/integrations/analyze",
    headers={"Authorization": f"Bearer {KEY}"},
    json={
        "sgf": open("game.sgf").read(),
        "match_id": "s46-gA-black-white",
        "season": "46",
        "group": "A",
        "round": "2",
        "external_url": "https://example.com/games/123",
    },
)
r.raise_for_status()
print(r.json()["share_url"])  # the link to give players