API docs by Redocly

Urchin API (2.0.0)

Download OpenAPI specification:

API for the Urchin blacklist database providing player information, batch lookups, and administrative functions

Batch player lookup

Get tag information for multiple players in a single request

query Parameters
key
required
string

API key for authentication

sources
required
string

Comma-separated list of sources (GAME, PARTY, PARTY_INVITES, CHAT, CHAT_MENTIONS, MANUAL, ME)

Request Body schema: application/json
required
usernames
required
Array of strings

List of Minecraft usernames to look up

Responses

Request samples

Content type
application/json
{
  • "usernames": [
    ]
}

Response samples

Content type
application/json
{
  • "players": {
    },
  • "rate_limit": 0
}

Add player tag (Admin only)

Admin-only endpoint to add a tag to a player

query Parameters
key
required
string

Admin API key for authentication

Request Body schema: application/json
required
uuid
required
string

Player's Minecraft UUID (with or without hyphens)

tag_type
required
string

Type of tag to add

reason
required
string

Reason for adding the tag

hide_username
boolean
Default: false

Whether to hide the username of who added the tag

overwrite
boolean
Default: false

Whether to overwrite existing tag of the same type

Responses

Request samples

Content type
application/json
{
  • "uuid": "string",
  • "tag_type": "string",
  • "reason": "string",
  • "hide_username": false,
  • "overwrite": false
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Starfish Proxy Public Key

Returns the RSA public key for Starfish Proxy signature verification

Responses

Response samples

Content type
application/json
{
  • "publicKey": "string"
}

Player information (Cubelify)

Returns player tags and score information for use with Cubelify overlay

query Parameters
id
required
string

Player Minecraft UUID

key
required
string

API key

name
required
string

Player Minecraft username

sources
required
string

Comma-separated list of sources (GAME, PARTY, PARTY_INVITES, CHAT, CHAT_MENTIONS, MANUAL, ME)

Responses

Response samples

Content type
application/json
{
  • "score": {
    },
  • "tags": [
    ]
}

Player blacklist

Get a player's blacklist tags from our database

path Parameters
username
required
string

Minecraft username or UUID (with or without hyphens)

query Parameters
key
required
string

API key for authentication

sources
required
string

Comma-separated list of sources (GAME, PARTY, PARTY_INVITES, CHAT, CHAT_MENTIONS, MANUAL, ME)

Responses

Response samples

Content type
application/json
{
  • "uuid": "string",
  • "tags": [
    ],
  • "rate_limit": 0
}

Sniper tag feed (WebSocket)

WebSocket endpoint that broadcasts a message whenever a new sniper tag is added.

Authentication: Pass your API key in the X-API-Key header during the WebSocket handshake.

Connection flow:

  1. Connect to wss://urchin.ws/snipers with the X-API-Key header set.
  2. Server responds with {"success": true} on valid key, or {"success": false, "error": "..."} and closes the connection.
  3. Keep the connection open. The server will push messages whenever a new sniper tag is created.

Broadcast message format:

{"type": "sniper", "uuid": "<player_uuid>", "reason": "<tag_reason>"}
header Parameters
X-API-Key
required
string

API key for authentication

Responses

Historical player statistics

Get player-specific Bedwars statistics aggregated over three time periods (daily, weekly, monthly). Requires historical access granted by an administrator.

path Parameters
identifier
required
string

Minecraft username or UUID (with or without hyphens)

query Parameters
key
string

API key for authentication

api_key
string

Alternative API key parameter

Responses

Response samples

Content type
application/json
{
  • "uuid": "string",
  • "username": "string",
  • "daily": {
    },
  • "weekly": {
    },
  • "monthly": {
    }
}