Getting Started

1. Create an API Key

Go to the API Keys page in your dashboard, or create one via the API:

curl -X POST https://your-api-url/api/v1/sdk/api-keys \
  -H "Authorization: Bearer <your_jwt_token>" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Game - Production"}'

Response:

{
  "id": "a1b2c3d4-...",
  "name": "My Game - Production",
  "key": "pk_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6",
  "key_prefix": "pk_live_",
  "created_at": "2026-03-10T12:00:00Z"
}

2. Authentication

Include your API key in the X-API-Key header on every SDK request:

X-API-Key: pk_live_a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Requests without a valid API key return 401 Unauthorized. Requests to personas you don't own or that aren't published return 403 Forbidden.

3. Discover Your Personas

List your published personas to get their IDs:

curl https://your-api-url/api/v1/sdk/personas \
  -H "X-API-Key: pk_live_..."

Response:

[
  {
    "id": "a1b2c3d4-...",
    "name": "Grumpy Barista",
    "description": "A coffee shop NPC with a bad attitude",
    "created_at": "2026-03-10T12:00:00Z",
    "updated_at": "2026-03-10T12:00:00Z"
  }
]

4. Make Your First Request

Initialize a chat session with one of your published personas:

curl -X POST https://your-api-url/api/v1/sdk/chat/{persona_id}/init-session \
  -H "X-API-Key: pk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "user_session_id": "player-001",
    "player_name": "Alex",
    "player_gender": "non-binary"
  }'

Response:

{
  "session_id": "f7a8b9c0-...",
  "user_session_id": "player-001",
  "persona_name": "Grumpy Barista",
  "persona_description": "A coffee shop NPC with a bad attitude",
  "player_name": "Alex",
  "player_gender": "non-binary",
  "message": "Well, well... another traveler. What brings you here, Alex?",
  "machine_id": "d4e5f6a7-..."
}

5. Managing API Keys

API key management endpoints use JWT authentication (your dashboard login), not API key auth.

Rate Limits

SDK endpoints have separate rate limits, applied per API key:

Access Control

API keys are scoped to the creator's account:

• You can only access personas that you own
• The persona must be published (not a draft)
• Attempting to access another user's persona returns 403