n01 External Integration API Manual

1. Overview

An HTTP API for reading and updating n01 tournaments, leagues, matches, team orders, and tournament statistics from external systems.

• The data retrieval APIs require no authentication. They only return the same data that is visible on the public pages (non-public items are never returned, and lists exclude private/deleted items). With Basic authentication they also return the administration items of the tournaments and leagues you administer (see 5. Authentication).
• The create, update and delete APIs require Basic authentication, and only work on the tournaments and leagues you administer (see 5. Authentication).
• All responses are JSON. On success the response is {"result":0, ...}, on failure it is {"result":<negative value>, "error":"..."} (see 7. Result codes).
• The base URL is https://push.n01darts.com/api/v1 (e.g. https://push.n01darts.com/api/v1/tournament/list).
• CORS is enabled, so the API can be called directly from JavaScript in a browser.

2. Data retrieval APIs (authentication optional)

The retrieval APIs work without Basic authentication (only autopilot/get, autopilot/list and team/player/list?all=1 need Basic authentication as an administrator). When it is supplied, the tournaments and leagues that the authenticated user administers also include admin_id, admin_name, join_pass and scorer_pass (always in tournament/get / league/get; in the list APIs only when requested explicitly with fields=), and the lists include your own private competitions (see 5. Authentication). Wrong credentials are rejected with result: -40. After repeated failures (20 within 10 minutes for the same address and user name) further attempts are refused for a while, even with the correct password.

GET/api/v1/health

Health check. Returns the server status.

GET/api/v1/tournament/list

Returns the list of tournaments. Private and deleted tournaments are excluded. With Basic authentication the private competitions you administer are included as well (use owner=1 to list only the tournaments you administer). Use the common list parameters for filtering, sorting, and paging.

GET /api/v1/tournament/list?status__in=20,30&sort=createTime&order=desc&count=20

{"result":0, "list":[
  {"tdid":"...", "lgid":"...", "createTime":1700000000, "updateTime":1700000001000,
   "title":"Spring Open", "t_date":1775001600, "status":30, "kind":"darts"},
  ...
]}

GET/api/v1/tournament/get

Returns the full data of a single tournament.

The response's tournament contains the tournament document (including the bracket table and settings). Non-public items are never included. When you fetch a tournament you administer with Basic authentication, admin_id, admin_name, join_pass and scorer_pass are included as well.

The response also has url, the page that participants and spectators open (https://n01darts.com/n01/tournament/comp.php?id=<tdid>, or https://n01darts.com/n01/league/season.php?id=<tdid> for an event of a league).

{"result":0, "tournament":{...}, "url":"https://n01darts.com/n01/tournament/comp.php?id=t_Ab1c_2345"}

GET/api/v1/tournament/entry/list

Returns the entry list. tdid is required.

Each entry has tpid and name, plus sns_type join startScore c (country) index when set. Non-public items are never returned. With the Basic authentication of an administrator of the tournament each entry also carries pass_set (0 / 1), whether an individual password is set (the password itself is never returned; the entry_list of /api/v1/tournament/get behaves the same).

GET/api/v1/tournament/stats

Returns the tournament statistics. tdid is required.

The statistics are identical to the ones shown on the stats pages. The data is returned in the response's stats.

GET/api/v1/league/list

Returns the list of leagues. Private and deleted leagues are excluded. With Basic authentication the private leagues you administer are included as well (use owner=1 to list only the leagues you administer).

GET/api/v1/league/get

Returns the full data of a single league. lgid is required. As with tournaments, non-public items are never included. The response also has url, the league portal page (https://n01darts.com/n01/league/portal.php?lgid=<lgid>).

{"result":0, "league":{...}, "url":"https://n01darts.com/n01/league/portal.php?lgid=lg_Ab1c_2345"}

GET/api/v1/league/entry/list

Returns the league entry list. lgid is required. Each entry has lpid and name, plus c and sns_type when set.

GET/api/v1/league/tournament/list

Returns the list of events (tournaments) that belong to a league. lgid is required. The parameters are the same as /api/v1/tournament/list, except owner and admin_id, which do not apply here (they are ignored). Like the league portal, private events of the league are included (deleted ones are excluded).

GET/api/v1/match/list

Returns the list of matches. Private and deleted matches are excluded. By default the archive is searched (all matches, including ones in progress, are kept in sync there).

match_type is "01" or "cricket". Matches without it are 01 matches.

GET/api/v1/match/get

Returns the full data of a single match, including per-leg scores. mid is required. The archive is searched first; when the match is not there, the matches in progress are searched. Deleted matches are not returned. A private match (private = 1) is returned only to the administrator of the tournament it belongs to (Basic authentication); otherwise -1 is returned.

Non-public items are never included. SNS-related IDs inside statsData are masked to "1" (presence only).

GET/api/v1/team/order/list

Returns the team orders of a team event.

Each element has tmid tpid schid and fix (whether the order is fixed). When an order has been submitted it also has order (the lineup; oid opid oname are complemented from the team player list), and res when a result has been entered.

GET/api/v1/team/player/list

Returns the team players. tdid is required, tpid is optional (all teams when omitted). Deleted players are excluded. Each player has tpid oid opid oname, plus index when it is set (players without an index come last).

With all=1 the deleted players are returned as well, each with delete (this needs Basic authentication as an administrator of the tournament).

GET/api/v1/tournament/standings

Returns the standings of the league (lg) and round robin (rr) groups. tdid is required. The ranks are computed with the same rules as the pages (points, Buchholz, win/loss difference, leg difference and head-to-head). A tournament with neither a league nor a round robin format returns result: -51.

{"result":0, "tdid":"...", "groups":[
  {"kind":"lg", "index":0, "title":"Division 1", "players":[
    {"tpid":"aaaa", "name":"Player One", "rank":1, "p":3, "w":3, "d":0, "l":0, "diff":6, "diff_l":0, "pts":6, "bh":4, "byes":0},
    ...
  ]}
]}

players is ordered by rank. Players who have not played yet have rank 0 and come last. p played / w d l won, drawn, lost / diff leg difference (set difference in a set format) / diff_l leg difference of a set format / pts points / bh Buchholz (swiss, when enabled) / byes number of byes. The points include the manual bonus points of the management screen (lg_pts, rr_pts for a round robin with the point system), the bonus points of a result (add) and the points per game of a team event (pt), like the standings of the pages. A round robin without the point system is ranked by win lose leg_win leg_lose and has no pts.

GET/api/v1/tournament/end_group

Returns whether every match of each round robin block (rr_<index>) and league division (lg_<index>) has finished (1 = finished, 0 = not yet). Use it before assigning the qualifiers to the final bracket.

{"result":0, "tdid":"...", "groups":{"rr_0":1, "rr_1":0}}

GET/api/v1/league/schedule/get

Returns the fixtures (match cards) of the league format. tdid is required, div (division index) is optional (without it one array per division is returned).

{"result":0, "tdid":"...", "swiss":0, "schedule":[
  [{"p":["aaaa","bbbb"], "lsid":"ab3f", "t":""}, {"p":["cccc","dddd"], "lsid":"k9x2", "t":"", "r":1}],
  []
]}

For a swiss league swiss is 1 and rounds carries, per division, the current round (round), the total number of rounds (total), the unassigned slots of the current round (blank) and the player count (members).

GET/api/v1/league/stats

Returns the statistics of a league (all its events). lgid is required. kind is stats_list (default), player_stats_list, rank_list or t_list; the same JSON as the league statistics page is returned in stats.

GET/api/v1/autopilot/get

Returns the autopilot (automatic board assignment) settings and the status written by the autopilot server. tdid is required and the Basic authentication of an administrator of the tournament is needed.

{"result":0, "tdid":"...",
 "config":{"tdid":"...", "lgid":"...", "group":"...", "name_control":0, "name_mode":"auto", "priority":0, "hold_robin":0,
           "types":{"t":{"badge_number":"1-10", "break_time":0, "round":0, "enable":1}, "s2":{...}, "dw":{...}, "dl":{...}},
           "remove_old_badge":1, "set_referee":0, "referee_type":"same_board", "updateTime":1700000000000},
 "status":{"time":1700000000000, "error":"", "held":{...}}}

config is null when nothing has been set. status.held lists the matches the server did not assign a board to (with the reason: opponent undecided, waiting for a board, player busy or on a break), the same list as the settings page.

GET/api/v1/autopilot/list

Returns the autopilot settings and status of every event of a league. lgid is required and the Basic authentication of an administrator of the league is needed. Each item has tdid title status (tournament state) and config / status as above.

3. Common list parameters

The list APIs (.../list) accept the following query parameters so that many conditions can be combined freely.

4. Data structures

The JSON returned by the API mirrors n01's internal data. This chapter describes the main fields (fields that are not listed are used internally by the system). The update APIs take the same structures.

4.1 Identifiers

4.2 Competition types (ttype)

A tournament can hold several competition formats at the same time, each with its own settings, bracket and results. The format is identified by its type, which forms the {ttype}_ prefix of those fields.

4.3 Tournament state (status)

4.4 Tournament (tournament)

The main fields of the document returned by /api/v1/tournament/get.

4.5 Brackets and results

Each format keeps its bracket and results in its own fields. Only the formats whose {ttype}_setting is enabled (lg_setting.league, rr_setting.round_robin, t_setting.tournament, m_setting.matchs and so on set to 1) are used.

A result ({ttype}_result[round][tpid][vsTpid]) has the following shape.

4.6 Entries

The shape of /api/v1/tournament/entry/list and of entry_list in tournament/get.

4.7 League (league)

A league groups several tournaments (events). Its events are listed with /api/v1/league/tournament/list.

A league entry (/api/v1/league/entry/list) has lpid, name, c and sns_type.

4.8 Match (match)

A match is the game data of one set. Matches in progress live in match and every match including the finished ones in match_archive; /api/v1/match/get looks in the archive first and falls back to the matches in progress (it has no live parameter; live=1 exists on /api/v1/match/list only).

Each element of legData (for 01) has the following shape.

"playerData": [
  [ {"score":0,"left":501}, {"score":180,"left":321}, {"score":180,"left":141}, {"score":-3,"left":0} ],
  [ {"score":0,"left":501}, {"score":100,"left":401} ]
]

Each element of statsData has the following shape.

For Cricket (match_type is "cricket") each leg holds turns (one entry per turn) instead of playerData. A turn is {"p": player, "r": round, "h": [[number index, marks], ...]}, where the number index is the position in [20, 19, 18, 17, 16, 15, BULL]. statsData holds allMarks (total marks) instead of allScore.

4.9 Team members and orders

In a team battle (team_games is 1) an entry (tpid) is a team, and its members and the order they play in each fixture are kept separately.

An order (/api/v1/team/order/list) is one entry per (tmid, tpid, schid), and order holds the members playing that game in their playing order (on retrieval oid, opid and oname are filled in; a member that no longer exists comes back as empty strings). fix tells whether the order is confirmed (1), and res is the result of that game.

4.10 Doubles

Doubles can be set up in two ways. Normally the first one (one entry carrying the names of both players) is enough. When you want statistics per player (average, high finish, etc.), the second one, building the pairs as teams with a schedule, is the effective way.

Settings for the second way:

• Set team_games of the tournament to 1 (team battle).
• Give the format setting ({ttype}_setting) limit 3 (schedule), a schedule with a single game whose num_part is 2, setOrder 1 (use team orders) and autoOrder 1 (fill the orders automatically). autoOrder only works when setOrder is 1.
• Register the two players of each entry (team) with /api/v1/team/player/update. Their index (1, 2) becomes the initial throwing order (registration order when there is no index). Naming the entry Smith / Jones as in the first way keeps the brackets easy to read.

{
  "team_games": 1,
  "name_sep": "/",
  "t_setting": {
    "tournament": 1, "t_player_count": 16,
    "limit": 3, "setOrder": 1, "autoOrder": 1, "exitResult": 1,
    "schedule": [
      {"subTitle": "Doubles", "startScore": 501, "match_type": "01", "roundLimit": 1, "maxRound": 15, "overkill": 0,
       "limit_leg_count": 2, "drawMode": 0, "num_part": 2, "group": 0, "pt": 0, "ignore_avg": 0}
    ]
  }
}

(The other fields of t_setting are omitted. {ttype}_setting is replaced as a whole, so send every field it needs.)

• No orders need to be registered. When a game starts and the order is not set, the server fills it with the first two members of the team in index order. The participants are not asked to submit orders either. An order registered with /api/v1/team/order/update is used as it is.
• The throwing order can be changed on the n01 Live game screen. Before each leg starts, tapping the team name (the player names) in the header swaps the throwing order of that leg, and the next legs keep it. The n01 Live header shows the two players instead of the team name and highlights the one to throw next. The game screen of online matches (n01 Online) has no way to swap them.
• Statistics per player are returned by /api/v1/tournament/stats with kind=player_stats_list.
• A fixture whose schedule has a single game is shown and counted by legs (2-1 etc.), not by games (1-0), in the brackets and standings.

5. Authentication

The API uses HTTP Basic authentication. The user and the password are issued automatically when you subscribe to the API (see Subscribing to the API).

Authorization: Basic <Base64 of user:pass>

On authentication failure the API returns HTTP 401 with result: -40.

Every API user has an admin_id (an n01 administrator id). You can create, update and delete only the tournaments and leagues that are administered by that id, and the data below them. Otherwise the API returns HTTP 403 with result: -41.

The APIs that use Basic authentication (creating, updating and deleting data, and authenticated retrieval) require an API subscription. Without a subscription, or once it has expired, the API returns HTTP 402 with result: -42. The retrieval APIs without authentication (public data) can be used without a subscription (so can the password change /api/v1/user/password).

What an API user can do depends on its admin_id:

Subscribing to the API

You subscribe from the payment page of a tournament.

1. Open the administration screen (Setting) of a tournament.
2. Follow the "About pricing." link to the payment page.
3. Select the "API" tab and buy the monthly or the yearly plan with PayPal.

You can subscribe the same way from a league ("About pricing." → "API" tab). Either way there is one subscription per n01 administrator id, not one per competition. It is separate from the subscription that raises the number of players and from the pay per event payment, and the API plans do not raise the number of players of a competition.

One API user is issued automatically per administrator when you subscribe, and the user name and the expiry date are shown on the same "API" tab. The password is shown only once right after it is issued, so keep a copy of it. If you lose it, you can issue a new one with "Reissue password" on the same page (the previous password stops working).

You cancel from the "Subscription list page" on the payment page. Even if you cancel, you can continue to use the API until the expiry date, after which it stops working.

OAuth 2.1 (for MCP clients)

For MCP clients that only offer OAuth or no authentication, such as the custom connectors of claude.ai, the API server is also an OAuth 2.1 authorization server. It supports the standard flow from client registration to token issuance (dynamic client registration, authorization code with PKCE, refresh tokens), so an MCP client discovers it automatically once you register https://push.n01darts.com/api/v1/mcp.

• During the authorization the n01 login page opens. Log in with the Google / Facebook / X account you use to administer your competitions and allow the access; the client then uses the API as that administrator (the same rights as an API user of that administrator).
• If the administrator has no API user yet, one is issued automatically when you allow the access. The subscription is handled exactly like Basic authentication: without it every authenticated call (reads included) returns result: -42 (the consent page shows whether you have a subscription and where to subscribe).
• The access token can be used with the REST API as well, as Authorization: Bearer <token>. It is valid for 24 hours and is renewed with the refresh token (90 days). An invalid token gets HTTP 401 with WWW-Authenticate: Bearer.

POST/api/v1/user/password

Changes your own password. Authenticate with the current password, then send the current and the new password as JSON. The new password must be 8 to 100 characters and different from the current one.

{"password": "current password", "new_password": "new password"}

There is a page for it as well: Change password. Control characters are not allowed in the new password (result: -3).

6. Create / update / delete APIs (Basic authentication)

POST a JSON body (Content-Type: application/json). All public fields returned by the retrieval APIs can be updated, including nested structures (brackets, settings, etc.). Non-public items, IDs, the delete flag and createTime / updateTime cannot be updated. If the request contains even one field that cannot be updated, or an invalid value, the whole request is rejected with result: -3 and nothing is updated.

POST/api/v1/tournament/create

Creates a tournament and returns the newly assigned tdid together with url, the page participants and spectators open. Show url to the user; it is the address to share. set accepts the same fields as /api/v1/tournament/update (omitted items get their default value), and entry_list registers the entries at the same time. title (tournament name) and join_pass (join password) are required; a request without them or with an empty value is refused with result: -3. On creation the title is trimmed and, when it is longer than 60 characters, stored cut to 60 characters followed by ... (the same rule as the administration screen; tournament/update accepts the full 200 characters).

{
  "set": {
    "title": "Autumn Open",
    "status": 20,
    "t_date": 1800000000,
    "join_pass": "pass1234",
    "rr_setting": {"round_robin": 1, "robin_count": 1, "robin_player_count": 8}
  },
  "entry_list": [
    {"name": "Player One", "c": "JP", "index": 1},
    {"name": "Player Two", "c": "JP", "index": 2}
  ]
}

{"result":0, "tdid":"t_Ab1c_2345", "added":[{"tpid":"Xy3f", "name":"Player One"}, ...],
 "url":"https://n01darts.com/n01/tournament/comp.php?id=t_Ab1c_2345"}

admin_name (the organizer name shown on the pages) is copied from the most recent tournament or league of the same administrator; when there is none, the API user name is used. Change it afterwards with tournament/update if needed. Administrators the site operator has exempted from payment get the tournament without max_user (no player limit), and administrators exempted from advertisements get ad 0, exactly as in the administration screen. Creating with status 30 (in progress) is subject to the player limit described under /api/v1/tournament/update; when it is exceeded the created data is removed again and result: -5 is returned (result: -6 when the limit could not be checked). A tournament cannot be created with status 30 while the bracket of an enabled format is empty (result: -3). The format exclusions (league and round robin, double and single elimination cannot be enabled together) and the automatic third place table are the same as for /api/v1/tournament/update.

With lgid the tournament is created as an event of that league (you must administer the league). The administrator information is inherited from the league and league becomes 1. An event of a league opens on the league area's page, so url becomes https://n01darts.com/n01/league/season.php?id=<tdid>. Only the enabled ones of lg_setting / rr_setting / t_setting / s2_setting / d_setting / m_setting are stored, together with their empty brackets.

The response also carries the updateTime of the created document, so that it can be passed as expect_update_time to a following tournament/update (league/create behaves the same).

POST/api/v1/tournament/update

Updates a tournament. All public fields returned by /api/v1/tournament/get can be specified, including the bracket (table) and the various settings. tdid and entry_list cannot be updated (use /api/v1/tournament/entry/update for entries). The administrator information (admin_id), max_user, the delete flag and the items only the site operator can change (ranking and special progression options) cannot be updated either. An empty set is refused with result: -3. The advertisement flag (ad) is decided by the payment state, so it cannot be given on creation nor on update.

Setting status to 30 (in progress) is subject to the same player limit as the administration screen: when the entries of the tournament (together with the organizer's other tournaments in progress) exceed the free players plus the purchased players, the request is refused with result: -5 (HTTP 402) and nothing is written (the check is skipped when the tournament is already in progress, or when it has no player limit because the organizer is exempt from payment; result: -6 when the payment server could not be reached). The organizer can buy players or a subscription on the pricing page of the administration screen. Other status changes are not affected. To move the tournament into another league by changing lgid, you must administer that league. When join_pass / scorer_pass are updated, the server recalculates the pass_hash / scorer_pass_hash used to check them. title and join_pass are required items, so an update that empties them is refused with result: -3.

An update through this API invalidates the administration screens that are open for the tournament, just like saving it from another screen does: their next save fails with "The data has been updated" and the screen has to be reloaded. Conversely, to avoid overwriting a change made from the administration screen (or by another API client) between your read and your update, send the updateTime returned by /api/v1/tournament/get as expect_update_time (UNIX milliseconds). When the tournament has been updated since, the request is refused with result: -7 (HTTP 409) and nothing is written; read the tournament again and retry (a non-integer expect_update_time is refused with result: -51).

{
  "tdid": "tournament ID",
  "expect_update_time": 1767225600000,
  "set": {
    "title": "Spring Open 2026",
    "status": 30,
    "theme": "dark"
  }
}

The values of the following fields are validated.

Settings and brackets: what to take care of (things that affect the progress of the tournament)

The administration screen prevents the following inconsistencies in its UI; the API does not check them. Getting them wrong shows up as matches that cannot be started or finished, or as a tournament that never completes.

• {ttype}_setting is replaced as a whole. Sending only {"tournament":1,"t_player_count":16} drops the stored limit / limit_leg_count / limit_set_count / schedule / game_setting / drawMode and so on. Without a leg count the matches never finish, and limit 3 (schedule) without schedule makes the result registration fail with a server error. Read the whole setting with the retrieval API, change it and send it back. An enabled setting needs at least limit (0=no limit / 1=legs / 2=sets / 3=schedule) with the matching limit_leg_count / limit_set_count and limit_set_leg_count / schedule (an array), and drawMode (0 / 1; 0 when the leg count is 1). The league format and round robin also need the points point_w / point_d / point_l (win / draw / loss); without them the standings cannot compute the points. low_win (lower score wins) only has a meaning with limit 0.
• Each row of schedule (limit 3, schedule mode / team matches) defines one game. A row has subTitle (label), startScore (start score of 01; 0 lets the players choose), match_type ("01" or "cricket"; 01 when omitted), limit_leg_count (legs of that game), drawMode, roundLimit / maxRound (round limit on/off and count), overkill, num_part (players per team in that game; 1=singles / 2=doubles), group / pt / ignore_avg (grouping, points and average exclusion for the statistics) and schid (game id). schid can be omitted because the server assigns it, but never change the schid of an existing game (orders and match data are tied to it; a changed id is a different game). The safe way is to reuse the rows read with the retrieval API. For team matches the format setting also takes setOrder (1: use team orders) and autoOrder (1: fill the orders automatically) (4.10 Doubles).
• Write results with /api/v1/tournament/result/update. Writing {ttype}_result directly with tournament/update is not refused, but then none of the progression happens: no winner is moved to the next round, no loser to the Losers bracket, no completion check, no badge update (the result is displayed but the tournament does not advance). Use the direct write only for corrections result/update cannot do (removing a wrong result, for example).
• Do not set game_type to 0. The bit flags of the participation methods (1=n01 Live / 2=n01 Online / 4=submit results) at 0 leave the participant pages without any way to start a match. Use a value from 1 to 7 (the administration screen can save 0 too, so check existing tournaments as well).
• Give the entries of an event under a league their lpid (league entry id). The league statistics (standings, stats) identify a league player through the lpid of the entries of each event. An entry added with /api/v1/tournament/entry/update without lpid is left out of the league statistics for that event, and a wrong lpid credits another player. Use the lpid from /api/v1/league/entry/list (the progress of the tournament itself is not affected).
• The round values of game_setting (per-round overrides). Single elimination: 1 and above is that round, -1=final, -2=semi-final, -3=third place match. Double elimination: 1 and above is that Winners round, -1=grand final reset, -2=grand final, -3=Winners final, -4=Winners semi-final, -5=Losers final, -6=Losers semi-final, -11 and below is that Losers round (-11=round 1, -12=round 2, ...). Round robin / league format: the block (division) number starting at 0. A wrong round applies its leg count to other matches.
• Byes have to be advanced to the next round by you. A first round slot with a player on one side only is advanced automatically by the administration screen when the bracket page is opened; nothing does this when the bracket is written through the API. Put the tpid into the matching slot of t_table[1] (round 2) and, when empty slots chain, further up. Otherwise the player does not appear in round 2 until an administrator opens the bracket page.
• The league format does not accept results without match cards. Matches of the league format are played per match card (fixture; what /api/v1/league/schedule/get returns), which is stored separately from lg_table (the players of each division). Setting lg_setting.league to 1 and filling lg_table does not create the cards (the administration screen creates them when the bracket page is opened; the API does not). Create them for every division that has players with /api/v1/league/schedule/generate (or update) before the tournament goes in progress. An update to status 30 only checks that the bracket (lg_table) exists; it is not refused when the cards are missing. In a division without cards the participant pages show the division and the names only, without a button to start a match, results are refused and the tournament never completes. Creating the cards while the tournament is in progress (generate or update) recovers from that state (no data is damaged). The safe way is to confirm with /api/v1/league/schedule/get that every division with players has cards before going to 30. When you change robin_count, adjust the number of divisions of the cards too (a robin_count above the number of divisions is a server error). The results of Swiss byes are recorded by the server when the cards are saved and when status becomes 30 (as on the administration screen).
• Removing an entry does not remove it from the brackets. remove of /api/v1/tournament/entry/update does not look at the tpid left in {ttype}_table. A tpid that does not exist shows as an empty slot and nobody can start that match. Remove it from the tables too.
• When you replace rr_table, adjust the related fields. The administration screen always saves rr_table together with rr_seq (match order; each pair sorted by tpid) / rr_order / rr_board / rr_disable. Changing rr_table alone leaves them pointing at the old placement and the match order and progress counts go wrong. Rebuild them from the new rr_table or clear them with the table.
• Keep the player count of assign_setting (assignment to the final bracket) within the bracket size. A total of advancing players above the t_player_count of the final bracket is not refused; the surplus players are silently dropped on assignment.
• Send s_date with the same value when you change t_date (the date used for sorting the lists does not follow automatically).

Give the brackets of an enabled format the same shape the administration screen creates: t_table / s2_table have log2(t_player_count) + 1 rows whose length halves each round, dw_table has log2(t_player_count) + 3 rows, dl_table has 2 × (log2(t_player_count) − 1) rows, m_table has match_count rows of [left, right], rr_table / lg_table have robin_count rows of robin_player_count slots. A different shape shows up as winners that are not written into the next round, Losers players that disappear, or a tournament that never completes (the API does not check the shape).

POST/api/v1/tournament/delete

Deletes a tournament (a soft delete that sets the delete flag and removes the link to its league). After that it is no longer visible from the retrieval APIs.

{"tdid": "tournament ID"}

POST/api/v1/tournament/entry/update

Adds, updates, and removes tournament entries. add / update / remove are all optional; specify only what you need (result: -51 when all three are empty). remove deletes the entries for good (unlike the remove of team players it cannot be undone; the state before the change is kept in the backup).

{
  "tdid": "tournament ID",
  "add": [
    {"name": "New Player", "c": "JP", "index": 10}
  ],
  "update": [
    {"tpid": "aaaa", "name": "Renamed Player", "join": 1}
  ],
  "remove": ["bbbb"]
}

All public entry fields can be specified (tdid, tpid, and SNS-related identification cannot be updated). The values of the following fields are validated.

Added entries get a newly assigned tpid, returned in the response's added. update targets an entry by its tpid. The response's updated / removed are the numbers of entries actually processed.

{"result":0, "added":[{"tpid":"Xy3f", "name":"New Player"}], "updated":1, "removed":1}

POST/api/v1/league/create

Creates a league and returns the newly assigned lgid together with url, the league portal page. set accepts the same fields as /api/v1/league/update, and entry_list registers the entries at the same time. title (league name) is required; a request without it or with an empty value is refused with result: -3.

{
  "set": {"title": "Winter League", "details": "season 3"},
  "entry_list": [{"name": "League Player", "c": "JP"}]
}

{"result":0, "lgid":"lg_Ab1c_2345", "added":[{"lpid":"Xy3f", "name":"League Player"}],
 "url":"https://n01darts.com/n01/league/portal.php?lgid=lg_Ab1c_2345"}

admin_name is copied from the most recent tournament or league of the same administrator; when there is none, the API user name is used.

POST/api/v1/league/update

Updates a league. All public fields returned by /api/v1/league/get can be specified (lgid, entry_list, createTime, updateTime, the administrator information (admin_id), the advertisement flag (ad) and the items only the site operator can change cannot be updated). title is a required item, so an update that empties it is refused with result: -3. Like /api/v1/tournament/update, the update invalidates the open administration screens of the league, and expect_update_time (the updateTime returned by /api/v1/league/get) refuses the update with result: -7 when the league has been updated in between.

{
  "lgid": "league ID",
  "expect_update_time": 1767225600000,
  "set": {"title": "Main League 2026"}
}

The values of the following fields are validated.

POST/api/v1/league/entry/update

Adds, updates, and removes league entries. add / update / remove are all optional. It works like the tournament entry update, but entries are addressed by lpid.

{
  "lgid": "league ID",
  "add": [{"name": "New Player", "c": "JP"}],
  "update": [{"lpid": "aaaa", "name": "Renamed Player"}],
  "remove": ["bbbb"]
}

All public entry fields can be specified (lgid, lpid, and SNS-related identification cannot be updated). The validated fields are name (required when adding), c, sname and index.

{"result":0, "added":[{"lpid":"Xy3f", "name":"New Player"}], "updated":1, "removed":1}

POST/api/v1/league/delete

Deletes a league (a soft delete). When the league still has events (tournaments), the request is rejected with result: -3; delete those events or unlink them from the league first.

{"lgid": "league ID"}

POST/api/v1/match/create

Creates the match data (the per-leg scores) of a finished match, e.g. to import matches scored outside n01 or old records. The match is stored in the archive (shown in the history and counted in the statistics) and can be read with /api/v1/match/get / /api/v1/match/list. Only the administrator of the tournament (tdid) can create matches.

set takes the fields that /api/v1/match/get returns. statsData (2 players, each with the tpid of an entry) and legData (the array of legs, same structure as the retrieval API) are required; ttype / round / t_no (the position in the bracket; tmid is derived from ttype, round and the two tpid when omitted), startTime (UNIX seconds, default now), match_type (01 / cricket), startScore, limitLeg / limitSet, scid / currentSet (in the set format one set is one match document, grouped by the same scid) and title are optional. In statsData, name defaults to the entry name and winLegs / allScore / allDarts are computed from legData (01) when omitted (the SNS link fields are left empty).

{
  "tdid": "tournament ID",
  "set": {
    "ttype": "rr", "round": 0, "startTime": 1105335600,
    "startScore": 501, "limitLeg": 2,
    "statsData": [{"tpid": "aaaa"}, {"tpid": "bbbb"}],
    "legData": [
      {"first": 0, "winner": 1, "currentRound": 5, "currentPlayer": 1, "endFlag": 1,
       "playerData": [
         [{"score": 0, "left": 501}, {"score": 100, "left": 401}, {"score": 60, "left": 341}, {"score": 85, "left": 256}, {"score": 100, "left": 156}, {"score": 60, "left": 96}],
         [{"score": 0, "left": 501}, {"score": 140, "left": 361}, {"score": 100, "left": 261}, {"score": 81, "left": 180}, {"score": 140, "left": 40}, {"score": 60, "left": -20}, {"score": -2, "left": 0}]
       ]}
    ]
  }
}

{"result":0, "mid":"Ab3kR9xz_1700000000000", "tmid":"t_xxxx_rr_0_aaaa_bbbb", "startTime":1105335600, "updateTime":1700000000000}

POST/api/v1/match/update

Updates a match. The archive copy is the primary target; when the match also exists among the matches in progress, both are updated at the same time to keep them in sync. All public fields returned by /api/v1/match/get can be specified, including statsData (mid, the delete flag, internal fields and the identification of the tournament and bracket the match belongs to (tdid lgid tmid schid scid ttype round gs_round) cannot be updated). When statsData is updated, the items that the retrieval API masks keep their server-side values. Only the administrator of the tournament the match belongs to (tdid) can update it (a match without a tdid cannot be updated).

{
  "mid": "match ID",
  "set": {"title": "Grand Final", "private": 1}
}

The values of the following fields are validated.

POST/api/v1/match/delete

Deletes a match (a soft delete that sets the delete flag). When the match exists both in the archive and among the matches in progress, both are flagged. As with the update, only the administrator of the tournament the match belongs to (tdid) can do this (a match without a tdid cannot be deleted).

{"mid": "match ID"}

POST/api/v1/team/player/update

Adds, updates, and removes the members of a team (tpid). add / update / remove are all optional; specify only what you need.

{
  "tdid": "tournament ID",
  "add": [{"tpid": "aaaa", "oname": "Team Member", "opid": "P-01", "index": 1}],
  "update": [{"tpid": "aaaa", "oid": "Xy3f", "oname": "Renamed Member"}],
  "remove": [{"tpid": "aaaa", "oid": "Ab1c"}]
}

The values of the following fields are validated.

add requires tpid and oname, update / remove require tpid and oid (otherwise result: -3; result: -51 when all three are empty). Added members get a newly assigned oid, returned in the response's added (lgid is inherited from the tournament). update and remove address a member by tpid and oid.

{"result":0, "added":[{"tpid":"aaaa", "oid":"Xy3f", "oname":"Team Member"}], "updated":1, "removed":1}

POST/api/v1/team/order/update

Registers, updates and removes team orders. update stores the order for a (tmid, tpid, schid) combination and adds it when it does not exist yet (the number of added orders is returned in added).

{
  "tdid": "tournament ID",
  "update": [
    {"tmid": "...", "tpid": "aaaa", "schid": "...", "order": [{"oid": "Xy3f"}, {"oid": "Ab1c"}]}
  ],
  "remove": [{"tmid": "...", "tpid": "aaaa", "schid": "..."}]
}

{"result":0, "added":1, "updated":0, "removed":1}

POST/api/v1/tournament/result/update

Enters (or clears) the result of one match with the same processing as the result input of the management screen. The server writes both sides of <ttype>_result, advances the winner to the next round (and the loser of a double elimination to the losers bracket), fills the third place match and finishes the tournament (status 40) when auto_complete is on and every match is over. Writing *_result directly with /api/v1/tournament/update does none of this, so use this API to enter results.

{
  "tdid": "tournament ID",
  "ttype": "t",
  "round": 0,
  "t_no": 1,
  "tpid": "aaaa",
  "vsTpid": "bbbb",
  "result": 3,
  "vsResult": 1,
  "detail": {"a": 65.2, "t": 4, "t4": 1, "t8": 0, "h": 80, "b": 15},
  "vsDetail": {"a": 58.0}
}

tpid and vsTpid must differ, and result / vsResult must both be numbers or both null. Invalid parameters (ttype, round, t_no, ...) are refused with result: -51; when the management backend does not accept the request, result: -3 is returned.

POST/api/v1/league/schedule/update

Replaces the fixtures (match cards) of one division of the league format as a whole, with the same processing as saving the cards on the management screen. The results of swiss byes (p is [tpid, "empty"]) are recorded by the server.

{
  "tdid": "tournament ID",
  "div": 0,
  "schedule": [
    {"p": ["aaaa", "bbbb"], "lsid": "ab3f", "t": ""},
    {"p": ["cccc", "dddd"]}
  ],
  "expect": 2
}

The response carries the stored schedule including the assigned lsid, and div. Both update and generate require the league format (lg_setting.league = 1) and refuse anything else with result: -51.

POST/api/v1/league/schedule/generate

Generates the fixtures from lg_table (the players of each division) and saves them, with the same rules as the automatic pairing and the swiss buttons of the management screen. Without div every division is processed. swiss_* on a normal league, robin on a swiss league, and a missing robin_count are refused with result: -51.

{"tdid": "tournament ID", "div": 0, "mode": "auto"}

{"result":0, "swiss":1, "divisions":[
  {"div":0, "before":3, "action":"swiss_next", "round":2, "total":3, "blank":0, "rematch":0, "after":6, "schedule":[...]}
]}

Divisions that were not processed carry the reason in skipped (not enough players, every round created, empty slots left, ...). Each division is saved with its current card count as expect, so a concurrent change on another device gives result: -7.

POST/api/v1/league/tournament/link

Makes a tournament an event of a league (same as linking a season on the management screen). lgid and tdid are required and you must administer both. lgid and the private flag of the league are set on the tournament and its matches.

{"lgid": "league ID", "tdid": "tournament ID"}

POST/api/v1/league/tournament/unlink

Detaches an event from its league (same as unlinking on the management screen). lgid is removed from the tournament, its entries, its team members and its matches. lgid and tdid are required and you must administer both; when the tournament does not belong to that league the request is refused with result: -51.

{"lgid": "league ID", "tdid": "tournament ID"}

POST/api/v1/team/order/fix

Fixes (fix 1) or releases (fix 0) the order of a team, as the administrator does on the order page. Once both teams have fixed, each can see the order of the other.

{"tdid": "tournament ID", "tmid": "match card ID", "tpid": "aaaa", "vsTpid": "bbbb", "fix": 1}

POST/api/v1/team/order/result

Enters the result of one game (schid) of a team match card by hand (same as the result input of the card on the management screen). The server counts the games won, writes the card result into <ttype>_result and advances the bracket.

{
  "tdid": "tournament ID",
  "tmid": "match card ID",
  "schid": "a1b2",
  "ttype": "t",
  "round": 0,
  "t_no": 1,
  "tpid": "aaaa",
  "vsTpid": "bbbb",
  "p1res": {"r": 3, "a": 70.5},
  "p2res": {"r": 1, "a": 61.0}
}

POST/api/v1/tournament/badge/update

Sets the badge (board number) of matches, like the badge management of the management screen. Pass one badge in the body or several in list. Participants see the change immediately through the update notification.

{"tdid": "tournament ID", "ttype": "t", "round": 0, "index": 2, "str": "5", "st": 1}
{"tdid": "tournament ID", "list": [{"ttype": "t", "round": 0, "index": 2, "str": ""}, {"ttype": "rr", "round": 1, "index": 0, "str": "A-3", "st": 2}]}

{"result":0, "updated":2}

POST/api/v1/tournament/memo/update

Sets the memo shown under each round robin block (ttype rr) or league division (lg). memo is an array of strings, one per block / division (at most 1024 items, each cut at 200 characters); an empty array clears them.

{"tdid": "tournament ID", "ttype": "rr", "memo": ["Board 36", "Board 37"]}

POST/api/v1/tournament/t_memo/update

Sets the memo shown at a match of a bracket (up to 40 characters, e.g. the referee). key is "<ttype>-<round>-<index>" with the even slot index of the match (the same key as a badge); str "" clears it. Pass one in the body or several (1-200) in list. The response carries updated (the count).

{"tdid": "tournament ID", "key": "t-0-2", "str": "Referee: Taro"}

POST/api/v1/tournament/announce/update

Sets the announcement shown to the participants (up to 200 characters). "" clears it. announceTime (UNIX milliseconds) defaults to the current time, or to 0 when the announcement is cleared. The response returns the stored announce / announceTime.

{"tdid": "tournament ID", "announce": "The final starts at 18:00"}

POST/api/v1/tournament/assign/update

Saves how the qualifiers of the round robin / league groups are assigned to the final brackets (assign_setting). The values are sanitized with the same rules as the assignment settings of the management screen and the stored assign_setting is returned. assign replaces the stored settings as a whole (it is not a partial update): omitted items get their defaults (t_type=top / s2_type=low / count=2 / every flag false / referee_type=lowest) and out-of-range values are replaced by the default instead of being rejected. The current values are in assign_setting of tournament/get.

{"tdid": "tournament ID", "assign": {"t_type": "top", "t_count": 2, "t_complete": true, "s2_type": "low", "s2_count": 2}}

POST/api/v1/tournament/copy

Copies a tournament (same as the copy of the management screen: status 10, same settings, same league) and returns the new tdid and url.

{"tdid": "tournament ID", "title": "Autumn Open 2027", "date": 0, "entry": 1, "result": 0}

{"result":0, "tdid":"t_Ab1c_2345", "url":"https://n01darts.com/n01/tournament/comp.php?id=t_Ab1c_2345"}

POST/api/v1/tournament/match/release

Releases the game lock (same as "Release game lock" in the match menu of the management screen). When n01 Live refuses to start a match card (tmid, optionally one game schid of a team event) because the players are "locked, playing elsewhere", this clears the in-game state of both players so that they can start again. The match data, the bracket and the results are not touched.

{"tdid": "tournament ID", "tmid": "match card ID"}

POST/api/v1/autopilot/update

Updates the autopilot settings. Only the fields given in config replace the stored ones (types is merged per type), the values are sanitized with the same rules as the settings page and the autopilot server is notified immediately. The stored settings are returned.

{"tdid": "tournament ID", "config": {"types": {"t": {"badge_number": "1-10,12", "break_time": 5, "round": 2.5, "enable": 1}}, "remove_old_badge": 1}}

7. Result codes

8. Examples (curl)

# Tournaments in progress
curl "https://push.n01darts.com/api/v1/tournament/list?status=30&count=20"

# A single tournament (with entries)
curl "https://push.n01darts.com/api/v1/tournament/get?tdid=XXXX"

# Tournament statistics
curl "https://push.n01darts.com/api/v1/tournament/stats?tdid=XXXX&kind=stats_list"

# Finished matches of a tournament, ordered by start time
curl "https://push.n01darts.com/api/v1/match/list?tdid=XXXX&endMatch=1&sort=startTime&order=asc"

# Team orders
curl "https://push.n01darts.com/api/v1/team/order/list?tdid=XXXX&tmid=YYYY"

# Update a tournament title
curl -u apiuser:apipass -H "Content-Type: application/json" \
     -d '{"tdid":"XXXX","set":{"title":"Spring Open 2026"}}' \
     "https://push.n01darts.com/api/v1/tournament/update"

# Add an entry
curl -u apiuser:apipass -H "Content-Type: application/json" \
     -d '{"tdid":"XXXX","add":[{"name":"New Player","c":"JP"}]}' \
     "https://push.n01darts.com/api/v1/tournament/entry/update"

# Tournaments you administer (including the private ones)
curl -u apiuser:apipass "https://push.n01darts.com/api/v1/tournament/list?owner=1"

# Create a tournament (with entries)
curl -u apiuser:apipass -H "Content-Type: application/json" \
     -d '{"set":{"title":"Autumn Open","status":20,"join_pass":"pass1234"},
          "entry_list":[{"name":"Player One","c":"JP"}]}' \
     "https://push.n01darts.com/api/v1/tournament/create"

# Create a league
curl -u apiuser:apipass -H "Content-Type: application/json" \
     -d '{"set":{"title":"Winter League"}}' \
     "https://push.n01darts.com/api/v1/league/create"

# Delete a tournament
curl -u apiuser:apipass -H "Content-Type: application/json" \
     -d '{"tdid":"XXXX"}' \
     "https://push.n01darts.com/api/v1/tournament/delete"

# Enter the result of the first match of round 1 (the winner advances)
curl -u apiuser:apipass -H "Content-Type: application/json" \
     -d '{"tdid":"XXXX","ttype":"t","round":0,"t_no":1,"tpid":"aaaa","vsTpid":"bbbb","result":3,"vsResult":1}' \
     "https://push.n01darts.com/api/v1/tournament/result/update"

# Generate the league fixtures (the next round of a swiss league)
curl -u apiuser:apipass -H "Content-Type: application/json" \
     -d '{"tdid":"XXXX"}' \
     "https://push.n01darts.com/api/v1/league/schedule/generate"

# Standings
curl "https://push.n01darts.com/api/v1/tournament/standings?tdid=XXXX"

9. Live samples

This manual is served by the API server itself, so the links below call the actual API on the same server. Clicking a URL opens the resulting JSON in a new tab. Clicking "Run" shows the formatted result at the bottom of this page.

Using the tdid / lgid / mid values found in the list results, you can try tournament/get?tdid=... and match/get?mid=... in the browser address bar the same way.

10. MCP server

The API server also works as an MCP (Model Context Protocol) server, so AI agents such as Claude Code can call this API directly as tools. The transport is Streamable HTTP with a single endpoint.

POST /api/v1/mcp

• Authentication is the same Basic authentication as the REST API, or OAuth 2.1. Without credentials only the data retrieval tools are exposed and they return the same data as the public pages. When authenticated, the administration items of the competitions administered by the authenticated user are included, and the create / update / delete tools become available (an API user without admin_id does not get the write tools; 5. Authentication). Wrong credentials are rejected with HTTP 401.
• Calls that use Basic authentication require an API subscription, exactly like the REST API. Without one, or once it has expired, the tool result carries result: -42 (the connection itself stays open).
• Every tool returns the same JSON as the corresponding REST API. The arguments use the same names as the query parameters / request body of the REST API (list filters take the common list parameters as they are, e.g. status__in: "20,30"). A result other than 0 is reported as a tool error (isError).
• Every tool carries annotations (readOnlyHint / destructiveHint / idempotentHint / openWorldHint). The data retrieval tools are read only, the create tools only add data, and the update / delete tools are reported as destructive because they replace or remove existing data.
• The server is stateless (no Mcp-Session-Id is issued). Responses are always JSON and no server-initiated stream (SSE) is used. The supported protocol versions are 2025-06-18 and 2025-03-26.

Tools

Data retrieval (authentication optional)

Create / update / delete (Basic authentication or OAuth; not listed on unauthenticated connections)

Connecting from Claude Code

# read only (no authentication)
claude mcp add --transport http n01 https://push.n01darts.com/api/v1/mcp

# with updates (Basic authentication)
claude mcp add --transport http n01 https://push.n01darts.com/api/v1/mcp \
    --header "Authorization: Basic $(printf '%s' 'apiuser:apipass' | base64)"

To share the configuration in a project, put it in .mcp.json (pass the credentials through an environment variable).

{
  "mcpServers": {
    "n01": {
      "type": "http",
      "url": "https://push.n01darts.com/api/v1/mcp",
      "headers": {"Authorization": "Basic ${N01_API_BASIC}"}
    }
  }
}

Connecting from claude.ai

In claude.ai open Settings → Connectors → "Add custom connector" and register the URL https://push.n01darts.com/api/v1/mcp. Choose OAuth as the authentication: the n01 login page opens, and after you log in with the account you administer your competitions with and allow the access, the create / update / delete tools are available as that administrator (OAuth 2.1). Registered without authentication, only the data retrieval tools are available.