NPCs

NPCs are non-player characters in Local Universe. They can be vendors with shop listings, quest givers, or event characters.

The NPC model

Properties

Name
id
Type
string
Description
Unique identifier for the NPC.
Name
name
Type
string
Description
The name of the NPC.
Name
description
Type
string?
Description
A description of the NPC.
Name
avatar
Type
string?
Description
Avatar image URL.
Name
type
Type
integer
Description
The NPC type.
Name
properties
Type
object?
Description
Additional NPC-specific properties.
Name
created_at
Type
string
Description
When the NPC was created.
Name
updated_at
Type
string
Description
When the NPC was last updated.

NPC types

Value	Name	Description
1	VENDOR	A merchant NPC with shop listings
2	QUEST_GIVER	An NPC that gives quests
3	EVENT	An NPC tied to a specific event

The shop listing model

Shop listings represent items available for purchase from a vendor NPC.

Name
id
Type
string
Description
Unique identifier for the listing.
Name
npc_id
Type
string
Description
The NPC this listing belongs to.
Name
item_id
Type
string
Description
The ID of the item being sold.
Name
buy_price
Type
number?
Description
The price to buy this item.
Name
currency
Type
string
Description
The currency type (e.g. bytes).
Name
properties
Type
object?
Description
Additional listing properties.
Name
created_at
Type
string
Description
When the listing was created.
Name
updated_at
Type
string
Description
When the listing was last updated.
Name
item_name
Type
string
Description
The name of the listed item (joined).
Name
item_icon
Type
string
Description
The icon URL of the listed item (joined).
Name
item_rarity
Type
integer
Description
The rarity of the listed item (joined).
Name
item_type
Type
integer
Description
The type of the listed item (joined).

GET/v1/npcs

List NPCs

Returns all NPCs. Optionally filter by type.

Query parameters

Name
type
Type
integer
Description
Filter by NPC type (1-3).
Name
limit
Type
integer
Description
Maximum number of NPCs to return (1-100). Default: 50.
Name
offset
Type
integer
Description
Number of entries to skip. Default: 0.

Request

GET

/v1/npcs

curl https://api.localuniverse.io/v1/npcs \
  -H "Authorization: Bearer {token}"

Response

[
  {
    "id": "1344387816333352652",
    "name": "Bait Bob",
    "description": "Your friendly neighborhood bait shop owner",
    "avatar": "https://cdn.localuniverse.io/npcs/bait-bob.png",
    "type": 1,
    "properties": null,
    "created_at": "2025-02-26T19:17:12.848375Z",
    "updated_at": "2025-02-26T19:17:12.848375Z"
  }
]

POST/v1/npcs

Create an NPC

Create a new NPC. Requires service auth.

Required attributes

Name
name
Type
string
Description
Name of the NPC (1-100 characters).
Name
type
Type
integer
Description
NPC type (1-3).

Optional attributes

Name
description
Type
string
Description
Description of the NPC (0-500 characters).
Name
avatar
Type
string
Description
Avatar URL.
Name
properties
Type
object
Description
Additional NPC properties.

Request

POST

/v1/npcs

curl -X POST https://api.localuniverse.io/v1/npcs \
  -H "Authorization: Service {api_key}:{api_secret}" \
  -H "Content-Type: application/json" \
  -d '{"name": "Bait Bob", "type": 1, "description": "Your friendly neighborhood bait shop owner"}'

GET/v1/npcs/:npcId

Get an NPC

Retrieve a single NPC by its ID.

Request

GET

/v1/npcs/1344387816333352652

curl https://api.localuniverse.io/v1/npcs/1344387816333352652 \
  -H "Authorization: Bearer {token}"

PATCH/v1/npcs/:npcId

Update an NPC

Update an existing NPC. Requires service auth.

Optional attributes

Name
name
Type
string
Description
New name.
Name
description
Type
string
Description
New description.
Name
avatar
Type
string
Description
New avatar URL.
Name
type
Type
integer
Description
New NPC type.
Name
properties
Type
object
Description
Updated properties.

Request

PATCH

/v1/npcs/1344387816333352652

curl -X PATCH https://api.localuniverse.io/v1/npcs/1344387816333352652 \
  -H "Authorization: Service {api_key}:{api_secret}" \
  -H "Content-Type: application/json" \
  -d '{"description": "Updated description"}'

DELETE/v1/npcs/:npcId

Delete an NPC

Permanently delete an NPC. Requires service auth.

Request

DELETE

/v1/npcs/1344387816333352652

curl -X DELETE https://api.localuniverse.io/v1/npcs/1344387816333352652 \
  -H "Authorization: Service {api_key}:{api_secret}"

GET/v1/npcs/:npcId/listings

Get shop listings

Returns all shop listings for an NPC.

Request

GET

/v1/npcs/1344387816333352652/listings

curl https://api.localuniverse.io/v1/npcs/1344387816333352652/listings \
  -H "Authorization: Bearer {token}"

Response

[
  {
    "id": "1344387816333355555",
    "npc_id": "1344387816333352652",
    "item_id": "1344387816333356666",
    "buy_price": 100,
    "currency": "bytes",
    "properties": null,
    "created_at": "2025-02-26T19:17:12.848375Z",
    "updated_at": "2025-02-26T19:17:12.848375Z",
    "item_name": "Fishing Rod",
    "item_icon": "https://cdn.localuniverse.io/items/fishing-rod.png",
    "item_rarity": 1,
    "item_type": 2
  }
]

POST/v1/npcs/:npcId/listings

Add a shop listing

Add an item listing to an NPC's shop. Requires service auth.

Required attributes

Name
item_id
Type
string
Description
The ID of the item to list.

Optional attributes

Name
buy_price
Type
number
Description
The price to buy this item (minimum 0).
Name
currency
Type
string
Description
The currency type. Defaults to bytes.
Name
properties
Type
object
Description
Additional listing properties.

Request

POST

/v1/npcs/1344387816333352652/listings

curl -X POST https://api.localuniverse.io/v1/npcs/1344387816333352652/listings \
  -H "Authorization: Service {api_key}:{api_secret}" \
  -H "Content-Type: application/json" \
  -d '{"item_id": "1344387816333356666", "buy_price": 100}'

PATCH/v1/npcs/:npcId/listings/:listingId

Update a shop listing

Update a shop listing. Requires service auth.

Optional attributes

Name
buy_price
Type
number
Description
New buy price.
Name
currency
Type
string
Description
New currency type.
Name
properties
Type
object
Description
Updated properties.

Request

PATCH

/v1/npcs/1344387816333352652/listings/1344387816333355555

curl -X PATCH https://api.localuniverse.io/v1/npcs/1344387816333352652/listings/1344387816333355555 \
  -H "Authorization: Service {api_key}:{api_secret}" \
  -H "Content-Type: application/json" \
  -d '{"buy_price": 150}'

DELETE/v1/npcs/:npcId/listings/:listingId

Delete a shop listing

Remove a listing from an NPC's shop. Requires service auth.

Request

DELETE

/v1/npcs/1344387816333352652/listings/1344387816333355555

curl -X DELETE https://api.localuniverse.io/v1/npcs/1344387816333352652/listings/1344387816333355555 \
  -H "Authorization: Service {api_key}:{api_secret}"

POST/v1/npcs/:npcId/transactions

Process a transaction

Buy an item from or sell items to an NPC. Requires bearer auth.

Buy

Name
action
Type
string
Description
Must be buy.
Name
listing_id
Type
string
Description
The ID of the shop listing to purchase.

Sell

Name
action
Type
string
Description
Must be sell.
Name
instance_ids
Type
string[]
Description
Array of item instance IDs to sell.

Request

POST

/v1/npcs/1344387816333352652/transactions

curl -X POST https://api.localuniverse.io/v1/npcs/1344387816333352652/transactions \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{"action": "buy", "listing_id": "1344387816333355555"}'

Buy Response

{
  "action": "buy",
  "item": {
    "id": "1344387816333356666",
    "name": "Fishing Rod",
    "description": "A basic fishing rod",
    "type": 2,
    "rarity": 1,
    "bind": 1,
    "icon": "https://cdn.localuniverse.io/items/fishing-rod.png",
    "flags": 0,
    "properties": null,
    "created_at": "2025-02-26T19:17:12.848375Z",
    "instance_id": "1344387816333359999"
  }
}

Sell Response

{
  "action": "sell",
  "sold": 1,
  "total_value": 50
}