Device / Character Block Management

The Device/Character Block feature allows partners to manage block statuses for their devices and characters via API. Blocked devices or characters will be rejected when calling init_npc.

Base URL:

Route Prefix: /api

Data Format: JSON

Encoding: UTF-8

Authentication

All management APIs authenticate via HTTP Headers:

Header	Type	Required	Description
`api_key`	string	Yes	32-character API key
`org_id`	string	Yes	6-character Organization ID

Failed authentication returns 401:

{
  "message": "Invalid API KEY or ORG ID"
}

API Summary

Method	Path	Description
POST	`/api/device/block`	Block a device or character
POST	`/api/device/unblock`	Unblock a device or character
GET	`/api/device/blocklist`	Query block list
GET	`/api/device/block/check`	Check individual block status

Block Device / Character

Add a block record. Blocked devices or characters will be rejected during init_npc.

POST /api/device/block

Request Body

{
  "type": "device",
  "identifier": "ABC123",
  "reason": "Policy violation"
}

Parameter	Type	Required	Description
type	string	Yes	`"device"` or `"npc"`
identifier	string	Yes	Device ID or character ID (npcid)
reason	string	No	Block reason

When type is "npc", the identifier must belong to the current organization (i.e., the first 6 characters of identifier must match org_id), otherwise 403 is returned.

Success Response (200)

{
  "ok": true,
  "block_key": "device:ABC123"
}

Error Responses

400 - Invalid Parameters

{
  "ok": false,
  "error": "Missing required field: type"
}

403 - Forbidden

{
  "ok": false,
  "error": "Cannot block NPC belonging to another org"
}

cURL Example

Unblock Device / Character

Remove a block record. Only unblocks records created by the current organization.

POST /api/device/unblock

Request Body

{
  "type": "device",
  "identifier": "ABC123"
}

Parameter	Type	Required	Description
type	string	Yes	`"device"` or `"npc"`
identifier	string	Yes	Device ID or character ID

Success Response (200)

{
  "ok": true
}

Error Responses

404 - Record Not Found

{
  "ok": false,
  "error": "Block record not found"
}

403 - Forbidden

{
  "ok": false,
  "error": "Cannot unblock record owned by another org"
}

cURL Example

Query Block List

Query all block records for the current organization, with optional type filtering.

GET /api/device/blocklist

Query Parameters

Parameter	Type	Required	Description
type	string	No	Filter by type: `"device"` or `"npc"`. If omitted, returns all records

Success Response (200)

{
  "ok": true,
  "items": [
    {
      "block_key": "device:ABC123",
      "type": "device",
      "identifier": "ABC123",
      "created_at": "2026-04-10T15:30:00Z",
      "created_by": "WOQSOC",
      "reason": "Policy violation"
    },
    {
      "block_key": "npc:WOQSOC7a8b9c1d2e3f4a5b6c7d8e9f0a1b2c3d",
      "type": "npc",
      "identifier": "WOQSOC7a8b9c1d2e3f4a5b6c7d8e9f0a1b2c3d",
      "created_at": "2026-04-10T16:00:00Z",
      "created_by": "WOQSOC",
      "reason": "Character deactivated"
    }
  ]
}

cURL Examples

Check Individual Block Status

Check whether a specified device or character is blocked.

GET /api/device/block/check

Query Parameters

Parameter	Type	Required	Description
type	string	Yes	`"device"` or `"npc"`
identifier	string	Yes	Device ID or character ID

Blocked Response (200)

{
  "ok": true,
  "blocked": true,
  "detail": {
    "reason": "Policy violation",
    "created_at": "2026-04-10T15:30:00Z",
    "created_by": "WOQSOC"
  }
}

Not Blocked Response (200)

{
  "ok": true,
  "blocked": false
}

cURL Example

init_npc Behavior Changes

The init_npc API has a new optional parameter device_id and now performs a block check before initialization.

New Request Parameters

Parameter	Type	Required	Description
npcid	string	Yes	Character ID
lang	string	No	Language setting
device_id	string	No	Device ID (newly added; when omitted, device-level block check is skipped)

Block Check Order

If device_id is provided, check whether the device is blocked

Check whether npcid is blocked

Proceed with original initialization logic only if both checks pass

Blocked Response

When a device or character is blocked, init_npc returns (HTTP 200):

{
  "status": "blocked",
  "reason": "Device has been blocked"
}

The TCP side determines connection rejection by checking if the status field value is "blocked".

Normal initialization response remains unchanged:

{
  "message": "NPC xxx initialized successfully",
  "status": "success",
  "code": 200
}

Error Codes Summary

HTTP Status Code	Description
200	Request successful
400	Invalid parameters (missing type or identifier, invalid type value)
401	Invalid api_key or org_id
403	Forbidden (attempting to operate on NPC of another organization)
404	Not found (block record does not exist during unblock)
500	Server error

Authentication#

API Summary#

Block Device / Character#

Request Body#

Success Response (200)#

Error Responses#

cURL Example#

Unblock Device / Character#

Request Body#

Success Response (200)#

Error Responses#

cURL Example#

Query Block List#

Query Parameters#

Success Response (200)#

cURL Examples#

Check Individual Block Status#

Query Parameters#

Blocked Response (200)#

Not Blocked Response (200)#

cURL Example#

init_npc Behavior Changes#

New Request Parameters#

Block Check Order#

Blocked Response#

Error Codes Summary#

Authentication

API Summary

Block Device / Character

Request Body

Success Response (200)

Error Responses

cURL Example

Unblock Device / Character

Request Body

Success Response (200)

Error Responses

cURL Example

Query Block List

Query Parameters

Success Response (200)

cURL Examples

Check Individual Block Status

Query Parameters

Blocked Response (200)

Not Blocked Response (200)

cURL Example

init_npc Behavior Changes

New Request Parameters

Block Check Order

Blocked Response

Error Codes Summary