Developer API

JiETNG exposes two API groups:

• Developer API: called with developer tokens for user management, binding links, permissions, and image generation.
• User Import API: called with a user Import Token to upload processed score JSON.

Default endpoint:

https://jietng-endpoint.matsuk1.com

Authentication

Developer API:

Authorization: Bearer <developer_token>

Import API:

Authorization: Bearer <import_token>

Developer tokens and Import Tokens are different credentials. Developer tokens are for integrations. Import Tokens belong to one user and only upload that user's records.

Developer Tokens

Manage tokens in LINE:

devtoken create <note>
devtoken list
devtoken revoke <token_id>
devtoken info <token_id>

The plaintext token is shown only once.

Permissions

A developer token can access a user when:

• the token created that user and is the owner, or
• the user accepted a permission request from that token.

Permission endpoints:

POST /api/v2/users/<user_id>/permissions
PATCH /api/v2/users/<user_id>/permissions/requests/<request_id>
DELETE /api/v2/users/<user_id>/permissions/<token_id>
DELETE /api/v2/users/<user_id>/permissions/self

Users can also handle requests in LINE:

accept-perm-request <request_id>
reject-perm-request <request_id>

User Endpoints

POST /api/v2/users
POST /api/v2/users/<user_id>/bind
PUT /api/v2/users/<user_id>/bind
GET /api/v2/users/<user_id>/bind-url
GET /api/v2/users/<user_id>/rebind-url
GET /api/v2/users/<user_id>/settings-url
POST /api/v2/users/<user_id>/sync/stream

/sync/stream returns application/x-ndjson: the first line is accepted, then the final line is completed or failed. Sync requires a full SEGA binding. Import Token users should upload processed records instead.

Score Image

GET /api/v2/users/<user_id>/image?command=b50
GET /api/v2/users/<user_id>/songs/<song_id>/image
GET /api/v2/users/<user_id>/plate?title=真神
GET /api/v2/users/<user_id>/achievement?level=14%2B&rank=sss
GET /api/v2/songs/<song_id>/image
GET /api/v2/users/<user_id>/export?fmt=json
GET /api/v2/dxdata?ver=jp

/songs/search chooses the version in this order: explicit ver, then the version stored on user_id, then jp.

command accepts the same B-series words users can type:

command	Meaning
b50 / best50	Best 50
b40 / best40	Best 40
b35 / best35	Best 35
b15 / best15	Best 15
ab35 / allb35	All Best 35
ab50 / allb50	All Best 50
apb50 / ap50	AP Best 50
fdxb50 / fdx50	FDX Best 50
rct50 / r50	Recent 50
idealb50 / idlb50	Ideal Best 50
unknown	Songs with unknown version

Filters can be included in the command string, for example b50 -lv 14.7.

Bookmarklet Image Endpoint

POST /api/web/session-image
Content-Type: application/json

Receives bookmarklet JSON and returns image/png. It does not require a developer token, but CORS is intended for official maimai mobile pages.

Core body:

{
  "ver": "jp",
  "command": "b50",
  "params": "-lv 14",
  "timezone": 9,
  "profile": {},
  "records": []
}

This endpoint generates an image only. Use Import API to save records.

Import Records

Users create Import Tokens from the settings page. Plaintext is shown only once.

POST /api/v2/import/records
Authorization: Bearer <import_token>
Content-Type: application/json

Example:

{
  "version": "jp",
  "profile": {
    "name": "Player",
    "rating": 15392,
    "trophy": "真皆伝",
    "trophy_content": "真皆伝",
    "trophy_url": "https://...",
    "icon_url": "https://...",
    "nameplate_url": "https://...",
    "class_rank_url": "https://...",
    "course_rank_url": "https://..."
  },
  "best": [
    {
      "song_id": "123456",
      "title": "Song Title",
      "type": "DX",
      "difficulty": "MASTER",
      "level": "14+",
      "level_index": 3,
      "achievement": 100.5,
      "dx_score": 1234,
      "dx_rating": 312,
      "fc": "AP+",
      "sync": "FDX+"
    }
  ],
  "recent": []
}

rating_block_path does not need to be uploaded; the server derives it from rating.

Replacement rules:

• "best": [] clears Best.
• "recent": [] clears Recent.
• Omitting a section keeps existing server data.

Success:

{
  "success": true,
  "user_id": "U...",
  "best_count": 1200,
  "recent_count": 50,
  "version": "jp",
  "message": "Records imported successfully."
}

CORS

Bookmarklet endpoints are designed for:

• https://maimaidx.jp
• https://maimaidx-eng.com

Error Codes

Status	Typical reason
400	Invalid parameters or payload
401	Invalid token or SEGA credentials
403	Missing permission
404	User, token, request, or task not found
409	Binding conflict
503	Official maintenance or full sync queue

Safety

• Do not ship developer tokens or Import Tokens in public frontend code.
• Import Tokens are for the user's own browser or trusted tools.
• Third-party applications should use developer token plus user permission flow.
• When unlinking, call DELETE /api/v2/users/<user_id>/permissions/self.