Getting Started

Create an API key and make your first SDK request.

1. Create an API Key

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

curl -X POST https://api.foilengine.io/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"
}

⚠Warning

Save your API key immediately. The full key is only shown once at creation time. If you lose it, revoke it and create a new one.

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. Provide Your LLM API Key

SDK chat endpoints (init-session, message) require you to provide your own LLM API key. Foil Engine uses LiteLLM under the hood, so any supported provider works (OpenAI, Anthropic, Groq, etc.).

Include your LLM key in the X-LLM-API-Key header on chat requests:

X-LLM-API-Key: sk-your-openai-or-anthropic-key
X-LLM-Model: gpt-4o          # optional, overrides default model

ℹNote

Your LLM keys are never stored by Foil Engine. They are passed per-request and used only for that request's LLM calls.

You can also override the model used for specific pipeline steps:

Header	Description
`X-LLM-API-Key`	Your LLM provider API key (required for chat endpoints)
`X-LLM-Model`	Default model for all pipeline steps
`X-LLM-Eval-Model`	Override model for message evaluation
`X-LLM-Response-Model`	Override model for NPC response generation
`X-LLM-Summarization-Model`	Override model for conversation summarization
`X-LLM-Eval-API-Key`	Override API key for evaluation (use a different provider)
`X-LLM-Response-API-Key`	Override API key for NPC response generation
`X-LLM-Summarization-API-Key`	Override API key for conversation summarization

You can validate your LLM key with a test call:

curl -X POST https://api.foilengine.io/api/v1/sdk/validate-llm-key \
  -H "X-API-Key: pk_live_..." \
  -H "X-LLM-API-Key: sk-..." \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o"}'

4. Discover Your Personas

List your published personas to get their IDs:

curl https://api.foilengine.io/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"
  }
]

5. Make Your First Request

Initialize a chat session with one of your published personas:

curl -X POST https://api.foilengine.io/api/v1/sdk/chat/{persona_id}/init-session \
  -H "X-API-Key: pk_live_..." \
  -H "X-LLM-API-Key: sk-..." \
  -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-..."
}

ℹNote

Chat endpoints involve LLM inference and typically take 1–5 seconds to respond, depending on the model and response length. Design your game UI with a loading or typing animation to keep the experience smooth. For faster perceived responses, use the streaming endpoint to display text as it generates.

6. Managing API Keys

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

Endpoint	Method	Description
`/api/v1/sdk/api-keys`	POST	Create a new API key
`/api/v1/sdk/api-keys`	GET	List all your API keys
`/api/v1/sdk/api-keys/{key_id}`	DELETE	Revoke an API key

Rate Limits

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

Category	Limit	Scope
Chat (sending messages)	30 requests / minute	Per API key
General (init, history, reset)	60 requests / minute	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

Previous← SDK Quickstart NextChat Endpoints →