Quickstart

Make your first API call in under a minute.

Prerequisites

An API key (sk_* or sk_*). See the API Key Integration Guide or request one from your account admin.

Step 1: List Threads

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

curl -X POST https://api.yocaso.dev/api/v1/llm/gateway/list-threads \
  -H "X-API-Key: sk_your_key_here" \
  -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.

X-On-Behalf-Of is required

create-thread must run with an authenticated user context. When using a backend secret key (sk_*), pass X-On-Behalf-Of: <your-user-id> to identify the user the thread belongs to. Omitting it returns 401 authenticated user_id is required.

curl -X POST https://api.yocaso.dev/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.yocaso.dev/api/v1/llm/gateway/send-message \
  -H "X-API-Key: sk_your_key_here" \
  -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.yocaso.dev/api/v1/llm/gateway/conversation-state \
  -H "X-API-Key: sk_your_key_here" \
  -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 (JWT, API keys, publishable keys)	Authentication
Set up API keys with scopes and rate limits	API Key Integration Guide
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

Prerequisites​

Step 1: List Threads​

Step 2: Create a Thread​

Step 3: Send a Message​

Step 4: Check Conversation State​

What's Next?​