ptarrant/Code_of_Conquest
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

api docs update

Browse Source
This commit is contained in:
Phillip Tarrant
2025-11-24 23:20:27 -06:00
parent 8315fa51c9
commit e198d9ac8a
1 changed files with 136 additions and 21 deletions
Download Patch File Download Diff File Expand all files Collapse all files

157
api/docs/API_REFERENCE.md
View File

@@ -740,8 +740,75 @@ Set-Cookie: coc_session=<session_token>; 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 ## 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 ### Create Session
| | | | | |
@@ -1066,17 +1133,19 @@ The Travel API enables location-based world exploration. Locations are defined i
"timestamp": "2025-11-25T10:30:00Z", "timestamp": "2025-11-25T10:30:00Z",
"result": { "result": {
"current_location": "crossville_village", "current_location": "crossville_village",
"available_locations": [ "destinations": [
{ {
"location_id": "crossville_tavern", "location_id": "crossville_tavern",
"name": "The Rusty Anchor Tavern", "name": "The Rusty Anchor Tavern",
"location_type": "tavern", "location_type": "tavern",
"region_id": "crossville",
"description": "A cozy tavern where travelers share tales..." "description": "A cozy tavern where travelers share tales..."
}, },
{ {
"location_id": "crossville_forest", "location_id": "crossville_forest",
"name": "Whispering Woods", "name": "Whispering Woods",
"location_type": "wilderness", "location_type": "wilderness",
"region_id": "crossville",
"description": "A dense forest on the outskirts of town..." "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 ### 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 ```json
{ {
"app": "Code of Conquest", "app": "Code of Conquest",
"version": "0.1.0", "version": "0.1.0",
"status": 202, "status": 200,
"timestamp": "2025-11-25T10:30:00Z", "timestamp": "2025-11-25T10:30:00Z",
"result": { "result": {
"job_id": "ai_travel_abc123", "location": {
"status": "queued",
"message": "Traveling to The Rusty Anchor Tavern...",
"destination": {
"location_id": "crossville_tavern", "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:** **Error Responses:**
- `400` - Location not discovered - `400` - Location not discovered
- `403` - Location not discovered
- `404` - Session or location not found - `404` - Session or location not found
- `500` - Internal server error
### Get Location Details ### Get Location Details
@@ -1139,22 +1235,36 @@ The Travel API enables location-based world exploration. Locations are defined i
"status": 200, "status": 200,
"timestamp": "2025-11-25T10:30:00Z", "timestamp": "2025-11-25T10:30:00Z",
"result": { "result": {
"location_id": "crossville_village", "location": {
"name": "Crossville Village", "location_id": "crossville_village",
"location_type": "town", "name": "Crossville Village",
"region_id": "crossville", "location_type": "town",
"description": "A modest farming village built around a central square...", "region_id": "crossville",
"lore": "Founded two centuries ago by settlers from the eastern kingdoms...", "description": "A modest farming village built around a central square...",
"ambient_description": "The village square bustles with activity...", "lore": "Founded two centuries ago by settlers from the eastern kingdoms...",
"available_quests": ["quest_mayors_request"], "ambient_description": "The village square bustles with activity...",
"npc_ids": ["npc_mayor_aldric", "npc_blacksmith_hilda"], "available_quests": ["quest_mayors_request"],
"discoverable_locations": ["crossville_tavern", "crossville_forest"], "npc_ids": ["npc_mayor_aldric", "npc_blacksmith_hilda"],
"is_starting_location": true, "discoverable_locations": ["crossville_tavern", "crossville_forest"],
"tags": ["town", "social", "merchant", "safe"] "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 ### 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?\"", "dialogue": "*polishes mug thoughtfully* \"Ah, another adventurer. What'll it be?\"",
"tokens_used": 728, "tokens_used": 728,
"npc_name": "Grom Ironbeard", "npc_name": "Grom Ironbeard",
"npc_id": "npc_grom_001", "npc_id": "npc_grom_ironbeard",
"character_name": "Thorin", "character_name": "Thorin",
"player_line": "greeting", "player_line": "greeting",
"conversation_history": [ "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 AI receives the last 3 exchanges as context for continuity
- The job result includes prior `conversation_history` for UI display - 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:** **Error Responses:**
- `400` - NPC not at current location - `400` - NPC not at current location
- `404` - NPC or session not found - `404` - NPC or session not found