API Documentation

The Amarsia API allows you to interact with your deployed workflows 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.

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.

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

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
}

Response:

{
  "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
  "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)

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

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"
}