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.

curl -X POST https://api.yocaso.dev/api/v1/llm/gateway/create-thread \
  -H "X-API-Key: sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "My First Thread",
    "conversation_key": "my-first-conversation"
  }'

Response:

{
  "conversationKey": "my-first-conversation",
  "name": "My First Thread",
  "createdAt": "2025-03-01T10:00:00Z"
}

The conversation_key is the unique identifier you'll use for all operations 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": "my-first-conversation",
    "user_message": {
      "role": "user",
      "content": "What can you help me with?"
    }
  }'

Response — confirms the message was accepted and a generation run has started:

{
  "runId": "run_abc123",
  "status": "RUNNING"
}

info

Message generation is asynchronous. The response confirms the request was accepted. The AI response is generated in the background and appended to the conversation history. Use the next step to retrieve it.

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": "my-first-conversation"
  }'

Response — includes the full message history with both user and assistant messages:

{
  "conversationKey": "my-first-conversation",
  "name": "My First Thread",
  "messages": [
    {
      "role": "user",
      "content": "What can you help me with?"
    },
    {
      "role": "assistant",
      "content": "I can help you with a variety of tasks..."
    }
  ],
  "status": "IDLE"
}

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