API Documentation

The Amarsia API allows you to interact with your deployed assistants programmatically. You can send text, images, videos, and audio files for multimodal AI processing.

We offer multiple API types: Standard API for complete responses, Streaming API for real-time word-by-word responses, and Conversation API for multi-turn dialogues with persistent context. You can also retrieve conversation history and filter conversations using custom metadata.

Authentication

All API requests require authentication using an API key. Include your API key in the request header:

x-api-key: YOUR_API_KEY

Get your API key from Settings → API Keys in your dashboard.

Standard API

Recommended

Returns complete responses with token usage information. Perfect for most use cases including automation, integrations, and batch processing.

POST

/v1/runner/{deployment_id}

curl https://api.amarsia.com/v1/runner/YOUR_DEPLOYMENT_ID \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "content": [{
      "type": "text",
      "text": "Your input message here."
    }]
  }'

Response

{
  "content": "Your AI-generated response here...",
  "model": "deepseek-chat",
  "output_tokens": 123,
  "input_tokens": 456
}

Streaming API

Receive responses word-by-word in real-time. Perfect for chat interfaces and interactive applications where you want to display results as they generate.

POST

/v1/runner/{deployment_id}/stream

async function streamResponse(prompt) {
  const response = await fetch(
    'https://api.amarsia.com/v1/runner/YOUR_DEPLOYMENT_ID/stream',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': 'YOUR_API_KEY',
      },
      body: JSON.stringify({
        content: [{ type: 'text', text: prompt }]
      })
    }
  );

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;

    const chunk = decoder.decode(value, { stream: true });
    console.log(chunk); // Display in real-time
  }
}

Key Points

• Response streams as plain text (no JSON parsing needed)
• Spacing and line breaks are already formatted
• Just concatenate chunks as they arrive
• Token counts are not available in streaming mode

Conversation API

New

Create chatbots and virtual assistants that remember context across multiple messages. Perfect for customer support, booking systems, and interactive experiences.

How It Works

1. Start: Send your first message to /conversation. You'll get back a conversation ID and an auto-generated conversation name.

2. Continue: Use /conversation/stream with that ID for all follow-up messages. The AI remembers your chat history automatically.

3. Organize: Add custom metadata (like userId, projectId) to tag and filter conversations later.

Step 1: Start Your Conversation

Send your first message to get a conversation ID that you'll use for the rest of the chat.

POST

/v1/runner/{deployment_id}/conversation

Request Body:

{
  "content": [{
    "type": "text",
    "text": "Hello! I need help with my order."
  }],
  "variables": { "customer_name": "John" },  // Optional
  "meta": {                                   // Optional
    "userId": "user_123",
    "projectId": "proj_456"
  }
}

Response:

{
  "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Order Assistance",
  "content": "Hi John! I'd be happy to help. What can I assist you with?",
  "input_tokens": 45,
  "output_tokens": 23
}

💡 Tip: Save the conversation_id from the response - you'll need it for all follow-up messages.

Step 2: Continue the Conversation

Use the conversation ID from step 1 to send follow-up messages. Responses stream back in real-time.

POST

/v1/runner/{deployment_id}/conversation/stream

Request Body:

{
  "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
  "content": [{
    "type": "text",
    "text": "I want to track order #12345"
  }],
  "history_limit": 5  // Optional: how many previous messages to include
}

Streaming Response

The response streams word-by-word in real-time. See the Streaming API section for code examples on how to handle streaming responses.

Quick Reference

Conversation Flow

1/conversation

Start: Send first message, get conversation_id

2/conversation/stream

Continue: Use conversation_id for all follow-ups

Conversation API Parameters

Parameter	Type	Required	Description
`conversation_id`	UUID string	Conditional	Omit for first message. Required for /conversation/stream (use ID from first response).
`content`	Array	Yes	Message content (same format as standard API)
`history_limit`	Number	No	Number of message pairs to include (default: 5)
`variables`	Object	No	Variables for system prompt (first message only, use with /conversation endpoint)
`meta`	JSON Object	No	Custom metadata for the conversation (e.g., userId, projectId). Can be used to filter conversations later.

Perfect For

💬 Customer Support

Answer questions, track orders, handle returns

🤖 Virtual Assistants

Schedule meetings, manage tasks, provide information

📋 Multi-Step Forms

Guide users through complex processes step by step

🎯 Sales & Booking

Help customers find products, make reservations

Get Conversation Messages

Retrieve paginated messages from a specific conversation. Messages are returned in LIFO order (newest first).

GET

/v1/runner/conversation/{conversation_id}/messages

curl "https://api.amarsia.com/v1/runner/conversation/550e8400-e29b-41d4-a716-446655440000/messages?page=1&page_size=20" \
  -H "x-api-key: YOUR_API_KEY"

Query Parameters

Parameter	Type	Required	Description
`page`	Number	No	Page number (default: 1)
`page_size`	Number	No	Number of messages per page (default: 20)

Response

{
  "messages": [
    {
      "id": "msg_789",
      "role": "assistant",
      "content": "I can help you with that order.",
      "created_at": "2026-02-06T10:30:00Z"
    },
    {
      "id": "msg_456",
      "role": "user",
      "content": "I want to track order #12345",
      "created_at": "2026-02-06T10:29:45Z"
    },
    {
      "id": "msg_123",
      "role": "assistant",
      "content": "Hi! I'd be happy to help.",
      "created_at": "2026-02-06T10:29:30Z"
    }
  ],
  "total": 3,
  "page": 1,
  "page_size": 20
}

Response Fields

• id: Unique message identifier
• role: Either "user" or "assistant"
• content: The message text
• created_at: ISO 8601 timestamp
• Messages are sorted newest first (LIFO order)

List All Conversations

Retrieve all conversations for the authenticated user. Supports dynamic filtering using custom metadata fields.

GET

/v1/runner/conversations

# Get all conversations
curl "https://api.amarsia.com/v1/runner/conversations?page=1&page_size=20" \
  -H "x-api-key: YOUR_API_KEY"

# Filter by metadata
curl "https://api.amarsia.com/v1/runner/conversations?userId=user_123&projectId=proj_456" \
  -H "x-api-key: YOUR_API_KEY"

Query Parameters

Parameter	Type	Required	Description
`page`	Number	No	Page number (default: 1)
`page_size`	Number	No	Number of conversations per page (default: 20)
`[any_key]`	String	No	Any parameter (except page/page_size) filters conversations by matching meta field. Example: ?userId=abc filters where meta.userId="abc"

Response

{
  "conversations": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Order Assistance",
      "created_at": "2026-02-06T10:29:30Z",
      "updated_at": "2026-02-06T10:30:00Z",
      "meta": {
        "userId": "user_123",
        "projectId": "proj_456"
      }
    },
    {
      "id": "660f9511-f30c-52e5-b827-557766551111",
      "name": "Product Inquiry",
      "created_at": "2026-02-05T14:15:00Z",
      "updated_at": "2026-02-05T14:20:00Z",
      "meta": {
        "userId": "user_123",
        "projectId": "proj_789"
      }
    }
  ],
  "total": 2,
  "page": 1,
  "page_size": 20
}

Dynamic Filtering

How it works: Any query parameter (except page and page_size) filters conversations by matching the corresponding field in the conversation's meta object.

Example: ?userId=abc&projectId=xyz returns only conversations where meta.userId="abc" AND meta.projectId="xyz"

Use case: Perfect for organizing conversations by user, project, session, or any custom categorization you need.

Multimodal Requests

Send multiple types of content in a single request. All APIs (standard, streaming, and conversation) support multimodal input.

{
  "content": [
    {
      "type": "text",
      "text": "Analyze this image and video."
    },
    {
      "type": "image",
      "mime_type": "image/jpeg",
      "file_uri": "https://example.com/image.jpg"
    },
    {
      "type": "video",
      "mime_type": "video/mp4",
      "file_uri": "https://example.com/video.mp4"
    }
  ]
}

Content Types

Supported content types for multimodal processing.

Text

{
  "type": "text",
  "text": "Your text content here"
}

Image

{
  "type": "image",
  "mime_type": "image/jpeg",
  "file_uri": "https://example.com/image.jpg"
}

Video

{
  "type": "video",
  "mime_type": "video/mp4",
  "file_uri": "https://example.com/video.mp4"
}

Audio

{
  "type": "audio",
  "mime_type": "audio/mp3",
  "file_uri": "https://example.com/audio.mp3"
}

PDF / Documents

{
  "type": "url",
  "mime_type": "application/pdf",
  "file_uri": "https://example.com/document.pdf"
}