dwroller/docs/api.md

API Documentation

Base URL

http://localhost:5000/api

Authentication

Most endpoints require authentication via session cookies.

Session Management

# Login (example)
POST /api/auth/login
Content-Type: application/json

{
  "email": "player@example.com",
  "password": "secret"
}

Players Endpoints

Get All Players

GET /api/players

Response:

[
  {
    "id": 1,
    "name": "Player One",
    "xp": 1500,
    "rp": 500,
    "renown": 10,
    "createdAt": "2025-08-16T10:00:00Z"
  }
]

Create Player (GM Only)

POST /api/players
Authorization: Bearer {gm-token}

Request:

{
  "name": "New Player",
  "xp": 0,
  "rp": 100,
  "renown": 0
}

Update Player

PUT /api/players/:id
Authorization: Bearer {gm-token}

Request:

{
  "xp": 1600,
  "rp": 600
}

Delete Player (GM Only)

DELETE /api/players/:id
Authorization: Bearer {gm-token}

Reset Password

POST /api/players/:id/reset-password
Authorization: Bearer {gm-token}

Shop Endpoints

Get Shop Inventory

GET /api/shop

Response:

[
  {
    "id": 1,
    "name": "Blade",
    "type": "weapon",
    "cost": 100,
    "stats": {
      "damage": "1d10",
      "weight": 3
    }
  }
]

Purchase Item

POST /api/shop/purchase

Request:

{
  "itemId": 1,
  "quantity": 1
}

Get Player Inventory

GET /api/inventory

Response:

[
  {
    "itemId": 1,
    "item": {
      "name": "Blade",
      "stats": {...}
    },
    "quantity": 1
  }
]

Bestiary Endpoints

Get All Creatures

GET /api/bestiary

Response:

[
  {
    "id": 1,
    "name": "Ghoul",
    "type": "abomination",
    "hp": 45,
    "armor": 10,
    "weaknesses": ["acid", "piercing"],
    "description": "Corrupted abomination..."
  }
]

Get Creature by ID

GET /api/bestiary/:id

Search Creatures

GET /api/bestiary/search?query=ghoul&type=abomination

Rules Endpoints

Search Rules

GET /api/rules/search?query=damage

Response:

[
  {
    "title": "Damage Mechanics",
    "content": "...",
    "page": "combat_damage"
  }
]

Get Rules Page

GET /api/rules/page/:pageId

Print Rulesheet

GET /api/rules/print/quick-reference

Returns printable HTML for the quick reference.

Sessions Endpoints

Create Session

POST /api/sessions

Request:

{
  "title": "Session 1",
  "date": "2026-04-19",
  "notes": "First session",
  "location": "The Ruins"
}

Get Sessions

GET /api/sessions?date=2026-04-19

Get Session by ID

GET /api/sessions/:id

Update Session

PUT /api/sessions/:id

Request:

{
  "notes": "Updated notes",
  "location": "The Ruins"
}

Delete Session

DELETE /api/sessions/:id

Files Endpoints

Upload File

POST /api/files/upload
Content-Type: multipart/form-data

Form Data:

• file: The file to upload

Get File

GET /api/files/:filename

Delete File

DELETE /api/files/:filename

List Files

GET /api/files

Error Handling

Standard Responses

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error",
    "details": "Additional details"
  }
}

Common Errors

Code	Description
UNAUTHORIZED	Invalid or missing session
FORBIDDEN	Insufficient permissions
NOT_FOUND	Resource doesn't exist
VALIDATION_ERROR	Invalid input data
INTERNAL_ERROR	Server error

Error Examples

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      }
    ]
  }
}

Rate Limiting

API calls are rate limited:

• 100 requests per minute per IP
• Headers include:
  • X-RateLimit-Limit: 100
  • X-RateLimit-Remaining: 99

Webhooks

Webhooks can be configured for events:

• Player created
• Item purchased
• Session created

POST /api/webhooks

Request:

{
  "url": "https://example.com/webhook",
  "events": ["player.created", "item.purchased"],
  "secret": "your-webhook-secret"
}

Testing with curl

Get Players

curl http://localhost:5000/api/players

Get Shop

curl http://localhost:5000/api/shop

Get Bestiary

curl http://localhost:5000/api/bestiary

Search Rules

curl "http://localhost:5000/api/rules/search?query=damage"