From e198d9ac8a6c29b4a75e5b04a7c0f01e2394eaf4 Mon Sep 17 00:00:00 2001 From: Phillip Tarrant Date: Mon, 24 Nov 2025 23:20:27 -0600 Subject: [PATCH] api docs update --- api/docs/API_REFERENCE.md | 157 +++++++++++++++++++++++++++++++++----- 1 file changed, 136 insertions(+), 21 deletions(-) diff --git a/api/docs/API_REFERENCE.md b/api/docs/API_REFERENCE.md index 6221002..11a4ddf 100644 --- a/api/docs/API_REFERENCE.md +++ b/api/docs/API_REFERENCE.md @@ -740,8 +740,75 @@ Set-Cookie: coc_session=; HttpOnly; Secure; SameSite=Lax; Max-Age --- +## Health + +### Health Check + +| | | +|---|---| +| **Endpoint** | `GET /api/v1/health` | +| **Description** | Check API service status and version | +| **Auth Required** | No | + +**Response (200 OK):** +```json +{ + "app": "Code of Conquest", + "version": "0.1.0", + "status": 200, + "timestamp": "2025-11-16T10:30:00Z", + "result": { + "status": "ok", + "service": "Code of Conquest API", + "version": "0.1.0" + }, + "error": null, + "meta": {} +} +``` + +--- + ## Sessions +### List Sessions + +| | | +|---|---| +| **Endpoint** | `GET /api/v1/sessions` | +| **Description** | Get all active sessions for current user | +| **Auth Required** | Yes | + +**Response (200 OK):** +```json +{ + "app": "Code of Conquest", + "version": "0.1.0", + "status": 200, + "timestamp": "2025-11-16T10:30:00Z", + "result": [ + { + "session_id": "sess_789", + "character_id": "char_456", + "turn_number": 5, + "status": "active", + "created_at": "2025-11-16T10:00:00Z", + "last_activity": "2025-11-16T10:25:00Z", + "game_state": { + "current_location": "crossville_village", + "location_type": "town" + } + } + ] +} +``` + +**Error Responses:** +- `401` - Not authenticated +- `500` - Internal server error + +--- + ### Create Session | | | @@ -1066,17 +1133,19 @@ The Travel API enables location-based world exploration. Locations are defined i "timestamp": "2025-11-25T10:30:00Z", "result": { "current_location": "crossville_village", - "available_locations": [ + "destinations": [ { "location_id": "crossville_tavern", "name": "The Rusty Anchor Tavern", "location_type": "tavern", + "region_id": "crossville", "description": "A cozy tavern where travelers share tales..." }, { "location_id": "crossville_forest", "name": "Whispering Woods", "location_type": "wilderness", + "region_id": "crossville", "description": "A dense forest on the outskirts of town..." } ] @@ -1084,6 +1153,11 @@ The Travel API enables location-based world exploration. Locations are defined i } ``` +**Error Responses:** +- `400` - Missing session_id parameter +- `404` - Session or character not found +- `500` - Internal server error + ### Travel to Location | | | @@ -1100,20 +1174,40 @@ The Travel API enables location-based world exploration. Locations are defined i } ``` -**Response (202 Accepted):** +**Response (200 OK):** ```json { "app": "Code of Conquest", "version": "0.1.0", - "status": 202, + "status": 200, "timestamp": "2025-11-25T10:30:00Z", "result": { - "job_id": "ai_travel_abc123", - "status": "queued", - "message": "Traveling to The Rusty Anchor Tavern...", - "destination": { + "location": { "location_id": "crossville_tavern", - "name": "The Rusty Anchor Tavern" + "name": "The Rusty Anchor Tavern", + "location_type": "tavern", + "region_id": "crossville", + "description": "A cozy tavern where travelers share tales...", + "lore": "Founded decades ago by a retired adventurer...", + "ambient_description": "The scent of ale and roasting meat fills the air...", + "available_quests": ["quest_missing_trader"], + "npc_ids": ["npc_grom_ironbeard"], + "discoverable_locations": ["crossville_forest"], + "is_starting_location": false, + "tags": ["tavern", "social", "merchant", "safe"] + }, + "npcs_present": [ + { + "npc_id": "npc_grom_ironbeard", + "name": "Grom Ironbeard", + "role": "bartender", + "appearance": "Stout dwarf with a braided grey beard" + } + ], + "game_state": { + "current_location": "crossville_tavern", + "location_type": "tavern", + "active_quests": [] } } } @@ -1121,7 +1215,9 @@ The Travel API enables location-based world exploration. Locations are defined i **Error Responses:** - `400` - Location not discovered +- `403` - Location not discovered - `404` - Session or location not found +- `500` - Internal server error ### Get Location Details @@ -1139,22 +1235,36 @@ The Travel API enables location-based world exploration. Locations are defined i "status": 200, "timestamp": "2025-11-25T10:30:00Z", "result": { - "location_id": "crossville_village", - "name": "Crossville Village", - "location_type": "town", - "region_id": "crossville", - "description": "A modest farming village built around a central square...", - "lore": "Founded two centuries ago by settlers from the eastern kingdoms...", - "ambient_description": "The village square bustles with activity...", - "available_quests": ["quest_mayors_request"], - "npc_ids": ["npc_mayor_aldric", "npc_blacksmith_hilda"], - "discoverable_locations": ["crossville_tavern", "crossville_forest"], - "is_starting_location": true, - "tags": ["town", "social", "merchant", "safe"] + "location": { + "location_id": "crossville_village", + "name": "Crossville Village", + "location_type": "town", + "region_id": "crossville", + "description": "A modest farming village built around a central square...", + "lore": "Founded two centuries ago by settlers from the eastern kingdoms...", + "ambient_description": "The village square bustles with activity...", + "available_quests": ["quest_mayors_request"], + "npc_ids": ["npc_mayor_aldric", "npc_blacksmith_hilda"], + "discoverable_locations": ["crossville_tavern", "crossville_forest"], + "is_starting_location": true, + "tags": ["town", "social", "merchant", "safe"] + }, + "npcs_present": [ + { + "npc_id": "npc_mayor_aldric", + "name": "Mayor Aldric", + "role": "village mayor", + "appearance": "A portly man in fine robes" + } + ] } } ``` +**Error Responses:** +- `404` - Location not found +- `500` - Internal server error + ### Get Current Location | | | @@ -1304,7 +1414,7 @@ The NPC API enables interaction with persistent NPCs. NPCs have personalities, k "dialogue": "*polishes mug thoughtfully* \"Ah, another adventurer. What'll it be?\"", "tokens_used": 728, "npc_name": "Grom Ironbeard", - "npc_id": "npc_grom_001", + "npc_id": "npc_grom_ironbeard", "character_name": "Thorin", "player_line": "greeting", "conversation_history": [ @@ -1327,6 +1437,11 @@ The NPC API enables interaction with persistent NPCs. NPCs have personalities, k - The AI receives the last 3 exchanges as context for continuity - The job result includes prior `conversation_history` for UI display +**Bidirectional Dialogue:** +- If `player_response` is provided in the request, it overrides `topic` and enables full bidirectional conversation +- The player's response is stored in the conversation history +- The NPC's reply takes into account the full conversation context + **Error Responses:** - `400` - NPC not at current location - `404` - NPC or session not found