api docs update
This commit is contained in:
@@ -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
|
||||
|
||||
### 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
|
||||
|
||||
Reference in New Issue
Block a user