Skip to main content

​
Overview

The Chat API enables you to send messages to AI providers, manage conversations, and stream responses in real-time.

​
Send Message

curl -X POST https://api.asta.app/api/chat \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "What is machine learning?",
    "provider": "claude",
    "conversation_id": "user-123:web:conv-456"
  }'

{
  "reply": "Machine learning is a subset of artificial intelligence...",
  "conversation_id": "user-123:web:conv-456",
  "provider": "claude"
}

​
POST /api/chat

Send a message to an AI provider and receive a complete response.

​
Request Body

​
text
string
required
The message text to send to the AI
​
provider
string
default:"default"
AI provider to use. Options: ollama, groq, google, claude, openai, openrouter, or default (uses user’s default provider)
​
conversation_id
string
Conversation ID to continue an existing conversation. If not provided, a new conversation will be created.
​
mood
string
Conversation mood/tone. Options: serious, friendly, or normal
​
web
boolean
default:false
If true, prefer web search and web fetch tools for the response
​
image_base64
string
Base64-encoded image data for vision-capable models
​
image_mime
string
MIME type of the image (e.g., image/png, image/jpeg)

​
Response

​
reply
string
The AI’s response text
​
conversation_id
string
The conversation ID (newly created or the one provided in the request)
​
provider
string
The actual provider used for the response

​
Stream Message

curl -N -X POST https://api.asta.app/api/chat \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Explain quantum computing",
    "provider": "claude"
  }'

event: meta
data: {"type":"meta","conversation_id":"user-123:web:conv-789","provider":"claude"}

event: assistant
data: {"type":"assistant","delta":"Quantum"}

event: assistant
data: {"type":"assistant","delta":" computing"}

event: assistant
data: {"type":"assistant","delta":" is..."}

event: done
data: {"type":"done","reply":"Quantum computing is...","conversation_id":"user-123:web:conv-789","provider":"claude"}

​
POST /api/chat

Stream AI responses in real-time using Server-Sent Events (SSE). This endpoint provides token-by-token streaming of the AI’s response.

​
Request Body

Accepts the same parameters as /api/chat.
​
text
string
required
The message text to send to the AI
​
provider
string
default:"default"
AI provider to use
​
conversation_id
string
Conversation ID to continue an existing conversation
​
mood
string
Conversation mood: serious, friendly, or normal
​
web
boolean
default:false
Enable web search/fetch tools
​
image_base64
string
Base64-encoded image data
​
image_mime
string
Image MIME type

​
Response Events

The endpoint returns Server-Sent Events with the following event types:
​
meta
event
Initial metadata event containing conversation ID and provider
{
  "type": "meta",
  "conversation_id": "user-123:web:conv-789",
  "provider": "claude"
}
​
assistant
event
Text delta events containing chunks of the AI’s response
{
  "type": "assistant",
  "delta": "text chunk"
}
​
reasoning
event
Reasoning/thinking events for models that support extended thinking
{
  "type": "reasoning",
  "delta": "reasoning text"
}
​
status
event
Status updates (e.g., tool execution, web search)
{
  "type": "status",
  "message": "Searching the web..."
}
​
done
event
Final event with complete response
{
  "type": "done",
  "reply": "Complete response text",
  "conversation_id": "user-123:web:conv-789",
  "provider": "claude"
}
​
error
event
Error event if something goes wrong
{
  "type": "error",
  "error": "Error message",
  "conversation_id": "user-123:web:conv-789",
  "provider": "claude"
}

​
List Conversations

curl "https://api.asta.app/api/chat/conversations?channel=web&limit=20" \
  -H "Authorization: Bearer <your-jwt-token>"

{
  "conversations": [
    {
      "id": "user-123:web:conv-456",
      "user_id": "user-123",
      "channel": "web",
      "created_at": "2026-03-06T10:30:00Z",
      "updated_at": "2026-03-06T11:45:00Z",
      "folder_id": null
    }
  ]
}

​
GET /api/chat/conversations

Retrieve a list of conversations for the authenticated user.

​
Query Parameters

​
channel
string
default:"web"
Filter conversations by channel
​
limit
integer
default:50
Maximum number of conversations to return (1-100)

​
Response

​
conversations
array
Array of conversation objects

​
Get Conversation Messages

curl "https://api.asta.app/api/chat/messages?conversation_id=user-123:web:conv-456&limit=50" \
  -H "Authorization: Bearer <your-jwt-token>"

{
  "conversation_id": "user-123:web:conv-456",
  "messages": [
    {
      "id": "msg-1",
      "role": "user",
      "content": "What is machine learning?",
      "created_at": "2026-03-06T10:30:00Z"
    },
    {
      "id": "msg-2",
      "role": "assistant",
      "content": "Machine learning is...",
      "created_at": "2026-03-06T10:30:15Z"
    }
  ]
}

​
GET /api/chat/messages

Retrieve messages from a specific conversation.

​
Query Parameters

​
conversation_id
string
required
The conversation ID to retrieve messages from
​
limit
integer
default:50
Maximum number of messages to return (1-100)

​
Response

​
conversation_id
string
The conversation ID
​
messages
array
Array of message objects ordered by creation time

​
Delete Conversation

curl -X DELETE https://api.asta.app/api/chat/conversations/user-123:web:conv-456 \
  -H "Authorization: Bearer <your-jwt-token>"

{
  "ok": true
}

​
DELETE /api/chat/conversations/

Delete a conversation and all its messages.
​
conversation_id
string
required
The ID of the conversation to delete

​
Error Responses

  • 403 Forbidden: Conversation does not belong to the authenticated user

​
Truncate Conversation

curl -X POST https://api.asta.app/api/chat/conversations/user-123:web:conv-456/truncate \
  -H "Authorization: Bearer <your-jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "keep_count": 10
  }'

{
  "ok": true,
  "conversation_id": "user-123:web:conv-456",
  "keep_count": 10,
  "deleted": 25
}

​
POST /api/chat/conversations//truncate

Remove old messages from a conversation, keeping only the most recent messages.
​
conversation_id
string
required
The ID of the conversation to truncate
​
keep_count
integer
default:0
Number of recent messages to keep. Set to 0 to delete all messages.

​
Response

​
ok
boolean
Success status
​
conversation_id
string
The conversation ID
​
keep_count
integer
Number of messages kept
​
deleted
integer
Number of messages deleted

​
Error Responses

  • 403 Forbidden: Conversation does not belong to the authenticated user

Build docs developers (and LLMs) love

Get started for freeTalk to us