Quickstart

Make your first API call in under a minute.

Prerequisites

• A secret key (sk_*) carrying the users:impersonate scope. See the API Key Integration Guide, or request one from your account admin — ask for that scope explicitly.
• A user id to act as. Any stable identifier from your own system works; the examples below use user_123.

Every call needs a user

A secret key identifies your tenant, not a person. Most endpoints act on a specific user's data, so each request below passes X-On-Behalf-Of. Leave it off and the call fails with 401 authenticated user_id is required — see Acting as a user.

Using a publishable key (pk_*) instead? Drop X-On-Behalf-Of and send Authorization: Bearer <user-jwt> — the user comes from the JWT.

Step 1: List Threads

Check that your API key works by listing your conversation threads.

curl -X POST https://api.travila.ai/api/v1/llm/gateway/list-threads \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{}'

Response — an empty list since this is a fresh account:

{
  "threads": []
}

Step 2: Create a Thread

A thread is a conversation container with its own message history and settings. It belongs to the user named in X-On-Behalf-Of, and only that user's requests can reach it.

curl -X POST https://api.travila.ai/api/v1/llm/gateway/create-thread \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "My First Thread"
  }'

Response:

{
  "thread": {
    "threadId": "b81d5345-c1f9-4fb9-b558-a6327c75b842",
    "title": "My First Thread",
    "createdAt": "2026-04-23T16:34:02.673Z",
    "updatedAt": "2026-04-23T16:34:02.673Z"
  }
}

Use the returned threadId as the conversation_key value in subsequent requests on this thread.

Step 3: Send a Message

Send a message and the platform will generate an AI response asynchronously.

curl -X POST https://api.travila.ai/api/v1/llm/gateway/send-message \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_key": "b81d5345-c1f9-4fb9-b558-a6327c75b842",
    "user_message": {
      "role": "ROLE_USER",
      "content": [
        { "type": "CONTENT_PART_TYPE_TEXT", "content": "What can you help me with?" }
      ]
    }
  }'

Response — returns the runId for the generation run that just started:

{
  "runId": "64403669-5989-4ec3-ad9c-d84223f9679f"
}

Responses are async

send-message returns immediately. The assistant reply is produced in the background (typically 7–11 seconds). Retrieve it by polling conversation-state — see Async Generation for the full recipe.

Step 4: Check Conversation State

Retrieve the full conversation state, including messages, settings, and generation status.

curl -X POST https://api.travila.ai/api/v1/llm/gateway/conversation-state \
  -H "X-API-Key: sk_your_key_here" \
  -H "X-On-Behalf-Of: user_123" \
  -H "Content-Type: application/json" \
  -d '{
    "conversation_key": "b81d5345-c1f9-4fb9-b558-a6327c75b842"
  }'

Response — once generation has settled, activeRunId is empty and the assistant reply has been appended to messageHistory:

{
  "messageHistory": [
    {
      "role": "ROLE_USER",
      "content": [{ "type": "CONTENT_PART_TYPE_TEXT", "content": "What can you help me with?" }],
      "timestamp": "2026-04-23T22:43:44.123Z",
      "messageId": "2a1f33ce-1abc-4a5d-9e22-1c0d1a2b3c4d",
      "sequence": "1"
    },
    {
      "role": "ROLE_ASSISTANT",
      "content": [{ "type": "CONTENT_PART_TYPE_TEXT", "content": "I can assist you with a variety of tasks..." }],
      "timestamp": "2026-04-23T22:43:51.653Z",
      "messageId": "3f2d44de-8db6-4f67-8e51-5c600902491b",
      "sequence": "2",
      "generatedBy": "64403669-5989-4ec3-ad9c-d84223f9679f",
      "usage": {
        "promptTokens": 359,
        "completionTokens": 65,
        "totalTokens": 424
      },
      "model": "google/gemini-3.1-flash-lite"
    }
  ],
  "activeRunId": ""
}

While generation is still in progress, activeRunId equals the runId from the previous step and the assistant message has not yet been appended. Once generation settles, activeRunId is empty (or absent) and the assistant message appears in messageHistory. See Async Generation for the polling recipe.

What's Next?

I want to...	Go to
Understand auth methods, scopes, and key rotation	Authentication & API Keys
Learn how conversations and threads work	Conversations Guide
Use MCP tools in conversations	MCP Tools Guide
Upload and manage files	Storage Guide
Browse all API endpoints	API Reference