OrionSlps

API Documentation

Chat with a Character

POST /api/v1/chat
Content-Type: application/json
Authorization: Bearer your_key_here

{
    "character_id": 1,
    "player_id": "player_xyz",
    "message": "Hello there",
    "meta": {
        "is_raining": true,
        "time_of_day_night": true,
        "player_health_low": false
    }
}

Response:
{
    "reply": "Arr matey!",
    "character_name": "Captain Byte",
    "should_speak": false,
    "new_goal": ""
}

Meta Tags (Game State Context)

The meta field is an optional dict of boolean flags representing live game world state. These flags let your NPC react to the game environment without the player having to describe it.

Critical concept: only true flags are visible to the NPC. Tags set to false are completely invisible — the NPC has no awareness of them. This means you must design your tags as positive states.

Example — wrong approach:

{"is_happy": true}

Setting is_happy to false later will NOT make the NPC sad. It will simply stop knowing about happiness. The NPC has no instruction to feel any other way.

Example — correct approach:

{"you_are_happy": true, "you_are_sad": false, "you_are_angry": false}

When you want the NPC to be sad, flip the flags:

{"you_are_happy": false, "you_are_sad": true, "you_are_angry": false}

Now the NPC sees "You are sad" in its world state and responds naturally.

Tag naming best practices:

• Name tags as complete thoughts the NPC should understand
• Use the NPC's perspective: you_hear_a_gunshot not gunshot_fired
• For environment: it_is_nighttime, the_tavern_is_crowded
• For NPC state: you_are_injured, you_are_tired, you_feel_threatened
• For game events: you_hear_an_explosion_nearby, someone_just_entered_the_room

Character description matters: Your character's description should mention that the character is aware of and reacts to their surroundings. Example: "A cautious guard who is always alert to changes in the environment around them and reacts naturally to what they observe."

Constraints:

- Values must be booleans only (true/false)
- Tag names: lowercase snake_case only, max 50 characters
- Max 20 tags per character, max 20 tags per request
- Only tags matching the character's configured meta_schema are used; others ignored
- Define accepted tags on the character create/edit page

Example full request:

{
    "character_id": 5,
    "message": "How's it going?",
    "player_id": "hero_1",
    "meta": {
        "it_is_raining": true,
        "it_is_nighttime": true,
        "you_feel_uneasy": true,
        "you_are_injured": false,
        "nearby_enemies": false
    }
}

The NPC will see: "It is raining", "It is nighttime", "You feel uneasy" — and react to those three conditions. It will have no awareness of injury or enemies.

List Characters

GET /api/v1/characters
Authorization: Bearer your_key_here

Health Check

GET /health

Python Example

import requests
import json

API_URL = "https://orionslps.com/api/v1/chat"  # <-- change this
API_KEY = "npc_your_api_key"

character_id = #your character number here
player_id = "your_player_id"

# Default meta state (you can tweak these live if you want)
meta = {
    "is_raining": True,
    "time_of_day_night": True,
    "player_health_low": False
}

headers = {
    "Content-Type": "application/json",
    "Authorization": f"Bearer {API_KEY}"
}

print("=== NPC Chat Interface ===")
print("Type 'exit' to quit\n")

while True:
    user_input = input("You: ")

    if user_input.lower() in ["exit", "quit"]:
        print("Exiting.")
        break

    payload = {
        "character_id": character_id,
        "player_id": player_id,
        "message": user_input,
        "meta": {
            "gun_shots_went_off": True,
        }
    }

    try:
        response = requests.post(API_URL, headers=headers, json=payload)

        if response.status_code != 200:
            print(f"[ERROR] Status {response.status_code}: {response.text}")
            continue

        data = response.json()

        reply = data.get("reply", "")
        character_name = data.get("character_name", "NPC")
        should_speak = data.get("should_speak", False)
        new_goal = data.get("new_goal", "")

        print(f"\n{character_name}: {reply}")

        if should_speak:
            print("[NPC wants to speak aloud]")

        if new_goal:
            print(f"[NEW GOAL]: {new_goal}")

        print()

    except Exception as e:
        print(f"[EXCEPTION] {str(e)}")

Limits

Max message:     1000 characters
Max characters:  10 per account
Messages stored: 1000 per character