Developer

API

Trulience API reference for token generation and avatar management
For LLMs

Overview

All endpoints use JSON. Authentication is via the x-api-key header.

Generate JWT Token

Generate a JWT token for avatar authentication.

Endpoint: POST /auth/generate-token

Request Headers

x-api-key: tru_live_***
Content-Type: application/json

Request Body

{
  "avatar_id": "4386676996480451678",
  "expire_at": 300
}
FieldTypeRequiredDescription
avatar_idstringYesAvatar ID to generate token for
expire_atintegerNoToken expiry in seconds. Default: 120. Range: 60-3600

Success Response (200 OK)

{
  "jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 300,
  "avatar_id": "4386676996480451678"
}
FieldTypeDescription
jwtstringJWT token for avatar authentication
expires_inintegerToken expiry in seconds
avatar_idstringAvatar ID the token is valid for

Error Responses

400 Bad Request - Invalid expire_at range

{
  "error": {
    "code": 19,
    "message": "expire_at must be between 60 and 3600 seconds"
  }
}

401 Unauthorized - Invalid API Key

{
  "error": {
    "code": 16,
    "message": "Invalid API Key"
  }
}

403 Forbidden - Missing Scope

{
  "error": {
    "code": 34,
    "message": "API key lacks required scope"
  }
}

403 Forbidden - Avatar Not Allowed

{
  "error": {
    "code": 33,
    "message": "API key is not authorized for this avatar"
  }
}

403 Forbidden - Origin Not Allowed

{
  "error": {
    "code": 35,
    "message": "Origin is not allowed for this API key"
  }
}

429 Rate Limited

{
  "error": {
    "code": 36,
    "message": "Too many requests. Please slow down."
  }
}

500 Internal Server Error

{
  "error": {
    "code": 45,
    "message": "Internal server error occurred"
  }
}

Notes

  • Tokens are single-use and cannot be refreshed
  • Generate a new token for each user session
  • Requires API key scope: generate_tokens

List Avatars

Retrieve a paginated list of avatars for your account.

Endpoint: GET /avatars

Request Headers

x-api-key: tru_live_***

Query Parameters

GET /avatars?page=0&size=20
ParameterTypeRequiredDescription
pageintegerNoPage number (0-indexed). Default: 0
sizeintegerNoResults per page. Default: 20. Max: 100

Success Response (200 OK)

{
  "avatars": [
    {
      "id": "4386676996481151678",
      "name": "Amanda"
    },
    {
      "id": "993237220279768598",
      "name": "Amanda - Trulience"
    }
  ],
  "pagination": {
    "page": 0,
    "size": 20,
    "total": 82,
    "total_pages": 5,
    "has_next": true
  }
}
FieldTypeDescription
avatarsarrayArray of avatar objects
avatars[].idstringAvatar unique identifier
avatars[].namestringAvatar display name
pagination.pageintegerCurrent page number (0-indexed)
pagination.sizeintegerResults per page
pagination.totalintegerTotal number of avatars
pagination.total_pagesintegerTotal number of pages
pagination.has_nextbooleanWhether more pages are available

Error Responses

401 Unauthorized - Invalid API Key

{
  "error": {
    "code": 16,
    "message": "Invalid API Key"
  }
}

403 Forbidden - Missing Scope

{
  "error": {
    "code": 34,
    "message": "API key lacks required scope"
  }
}

429 Rate Limited

{
  "error": {
    "code": 36,
    "message": "Too many requests. Please slow down."
  }
}

500 Internal Server Error

{
  "error": {
    "code": 45,
    "message": "Internal server error occurred"
  }
}

Notes

  • Avatars are sorted alphabetically by name
  • Requires API key scope: read_avatars