HTTP Endpoints

Pre-v1 paths continue to work during the deprecation window and include Deprecation: true, Link, and Sunset response headers. New integrations should use /v1.

See Custom Characters for dashboard setup and SDK examples.

POST /v1/chat (API Key)

Headers

• Authorization: Bearer <API_KEY>
• Content-Type: application/json

Body

• message (required)
• context, characterDescription, playerDescription (optional)
• external_id, identifier_type, player_data (optional player data fields)

Errors

• 400 invalid_body
• 400 unexpected_characterId
• 401 invalid/missing api key
• 402 insufficient_credits
• 429 rate_limited / too_many_concurrent_requests
• 500/502 upstream errors

Example

curl -X POST https://api.journale.ai/v1/chat \
  -H "Authorization: Bearer $JOURNALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Can I enter the city?",
    "characterDescription": "A suspicious gate guard.",
    "playerDescription": "A traveler carrying a sealed letter.",
    "context": "The player is outside the north gate."
  }'

POST /v1/chat/player (Player JWT)

Headers

• Authorization: Bearer <player JWT>
• x-nonce, x-ts, x-signature
• Content-Type: application/json

Body

• message (required)
• context, characterDescription, playerDescription (optional)

Errors

• 400 invalid_body / unexpected_characterId
• 401 invalid_claims / project_not_found / signature_invalid
• 402 insufficient_credits
• 429 rate_limited / too_many_concurrent_requests
• 500/502 upstream errors

POST /v1/chat/character (API Key)

Resolves a dashboard-managed character by characterId slug in the API key's project.

Headers

• Authorization: Bearer <API_KEY>
• Content-Type: application/json

Body

• characterId (required, slug)
• message (required)
• context, playerDescription, playerId (optional)
• external_id, identifier_type, player_data (optional player data fields)

Do not send characterDescription to this endpoint. The API uses the character's dashboard personality and physical description.

Errors

• 400 invalid_body / unexpected_characterDescription / player_identity_conflict
• 404 character_not_found
• 402 insufficient_credits
• 429 rate_limited / too_many_concurrent_requests
• 500/502 upstream errors

Example

curl -X POST https://api.journale.ai/v1/chat/character \
  -H "Authorization: Bearer $JOURNALE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "characterId": "silas_merchant",
    "message": "What do you have for sale today?",
    "context": "The player is at a rainy market stall.",
    "external_id": "roblox_123456",
    "identifier_type": "roblox",
    "player_data": {
      "level": 7,
      "faction": "Knights of Dawn"
    }
  }'

Response

{
  "reply": "For a rainy day? Lantern oil, dry tinder, and a map that still knows where the roads used to be.",
  "character": {
    "characterId": "silas_merchant"
  },
  "usage": {
    "prompt_tokens": 143,
    "completion_tokens": 31,
    "total_tokens": 174
  }
}

POST /v1/chat/player/character (Player JWT)

Resolves a dashboard-managed character by characterId slug in the player's session project.

Headers

• Authorization: Bearer <player JWT>
• x-nonce, x-ts, x-signature
• Content-Type: application/json

Body

• characterId (required, slug)
• message (required)
• context, playerDescription (optional)

Do not send characterDescription or playerId. Player identity comes from the signed player session.

Errors

• 400 invalid_body / unexpected_characterDescription / unexpected_playerId
• 401 invalid_claims / project_not_found / signature_invalid
• 404 character_not_found
• 402 insufficient_credits
• 429 rate_limited / too_many_concurrent_requests
• 500/502 upstream errors

Example body signed by an SDK

{
  "characterId": "silas_merchant",
  "message": "Have you seen any bandits nearby?",
  "context": "The player just entered the town market.",
  "playerDescription": "A cautious ranger with a damaged lantern."
}

POST /v1/sessions

Headers

• Content-Type: application/json

Body

• projectId, platform, platformUserId, deviceId, isGuest, steamAuthTicket, refreshTtlDays (optional)

Errors

• 500 session_create_failed
• 500 missing_SESSION_CREATE_URL
• Forwarded upstream errors

GET /v1/healthz

Returns { "ok": true, "ts": "..." }.

Pre-v1 deprecation headers

The old paths still serve responses during the migration window:

• POST /chat
• POST /chat/player
• POST /chat/character
• POST /session/create
• GET /healthz

Responses include:

Deprecation: true
Link: </v1/...>; rel="successor-version"
Sunset: Sat, 18 Apr 2027 00:00:00 GMT