This tutorial walks you through the different ways to use the REST API to create and communicate with AMAS agents. You’ll learn how to load sessions from YAML, from existing agents, execute messages, and pass variables and files to your agents.

Prerequisites

Get API Key

Generate an API key from the Artaios Agent Studio settings

Base URL

All API requests use: https://api.artaios.ai/api/v1

Authentication

Include your API key in the x-api-key header with every request

Never expose your API key in client-side code or public repositories. Use environment variables or secure credential storage.

Creating Sessions

Learn the different ways to create and initialize a session with your agents.

Option 1: Load Session from YAML Configuration

Create a session by providing a complete agent configuration in YAML format (as JSON):

curl -X POST https://api.artaios.ai/api/v1/sessions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support Agent Session",
    "description": "Customer support agent from inline config",
    "save_messages": true,
    "persistent_state": true,
    "agents": [
      {
        "name": "support_agent",
        "agent_type": "llm_agent",
        "description": "Handles customer inquiries",
        "prompt_config": {
          "system_prompt": "You are a helpful customer support agent. Provide accurate and friendly responses."
        },
        "llm_config": {
          "temperature": 0.7
        },
        "streaming_config": {
          "show_output_to_user": true
        }
      }
    ],
    "edges": [
      {
        "from": "__start__",
        "to": "support_agent"
      },
      {
        "from": "support_agent",
        "to": "__end__"
      }
    ],
    "entry_point": "support_agent"
  }'

Response:

{
  "success": true,
  "session_id": "session_abc123def456",
  "config_hash": "object:f1f2510eaad449aebddc23690cb29630cebd83058d09e29c7f57969fb2177c73:u:anon"
}

Option 2: Load Session from Existing Agent

Create a session from an agent already configured in Artaios Agent Studio. Use the agent’s unique key:

curl -X GET "https://api.artaios.ai/api/v1/sessions/from-agent/?agent_key=your-agent-key-here" \
  -H "x-api-key: YOUR_API_KEY"

Response:

{
  "success": true,
  "session_id": "session_runtime123",
  "config_hash": "object:f1f2510eaad449aebddc23690cb29630cebd83058d09e29c7f57969fb2177c73:u:anon",
  "agent_id": "agent_xyz789",
  "agent_name": "My Support Agent"
}

Communicating with a Session

Once you have a session ID, you can execute messages and interact with your agent.

Execute a Simple Message

Send a message to the agent and get a response:

curl -X POST https://api.artaios.ai/api/v1/runtime/session_abc123/execute/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello! I need help with my account."
  }'

Response:

{
  "id": "session_abc123",
  "object": "agent.session",
  "status": "completed",
  "created_at": 1704067200,
  "completed_at": 1704067215,
  "config": {},
  "messages": [
    {
      "id": "msg_def456",
      "role": "assistant",
      "content": "Hello! I'd be happy to help you with your account. What specific issue are you experiencing?",
      "created_at": 1704067210
    }
  ],
  "execution_time": 15,
  "metadata": {
    "correlation_id": null,
    "event_count": 3,
    "execution_id": "exec_789",
    "usage": {
      "input_tokens": 125,
      "output_tokens": 42
    }
  }
}

Continue Conversation

Send follow-up messages. The agent maintains context from previous messages:

curl -X POST https://api.artaios.ai/api/v1/runtime/session_abc123/execute/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I reset my password?"
  }'

The response includes all new messages generated during this execution. The agent has full access to previous messages in the session and provides context-aware responses.

Pass Variables with Your Message

Inject variables into the agent’s context. Variables are substituted into agent prompts and maintain state across executions.

Learn more in the Using Variables in REST API guide.

Session-level variables (persist across requests):

curl -X POST https://api.artaios.ai/api/v1/runtime/session_abc123/execute/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello, I need help",
    "inputs": {
      "user_id": "user_12345",
      "user_email": "john@example.com"
    }
  }'

On subsequent requests, these variables load automatically from the checkpoint. Request-level variables (fresh on every request):

curl -X POST https://api.artaios.ai/api/v1/runtime/session_abc123/execute/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "What is your refund policy?",
    "inputs": {
      "current_query": "What is your refund policy?"
    }
  }'

Request-level variables must be provided on every execution. The inputs field accepts a dictionary of variables that are available to your agents via {{ variables.key }}.

Multimodal Input: Images and Files

You can pass images and files to your agent for analysis. This feature is experimental — if you use it, please provide feedback on your experience.

Experimental Feature: Image and file input handling via REST API is not fully tested. If you encounter issues or limitations, please report them to support with details about your use case.

Send an Image with Your Message

AMAS officially supports three different methods for sending images to an agent.

Method 1: The “Upload First” Method (Highly Recommended)

If you are building an interface where users upload local files, you should upload the image to the Artaios API first. This returns a temporary, secure URL that you then pass to the agent. This method reduces LLM token consumption by ~95% compared to Base64 encoding. Step 1: Upload the Image

curl -X POST https://api.artaios.ai/api/v1/images/upload/ \
  -H "x-api-key: YOUR_API_KEY" \
  -F "image=@/path/to/your/image.jpg"

Response:

{
  "url": "https://api.artaios.ai/media/uploaded_images/temp_xyz.jpg",
  "media_type": "image/jpeg",
  "size": 102400
}

Step 2: Send the URL to the Agent

curl -X POST https://api.artaios.ai/api/v1/runtime/session_abc123/execute/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": [
      {
        "type": "text",
        "text": "What is shown in this image?"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://api.artaios.ai/media/uploaded_images/temp_xyz.jpg"
        }
      }
    ]
  }'

Method 2: Direct Public URL

If your image is already hosted publicly on the internet (e.g., a product image on your website), you can pass that URL directly. This is also highly efficient for token usage.

curl -X POST https://api.artaios.ai/api/v1/runtime/session_abc123/execute/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": [
      {
        "type": "text",
        "text": "What is shown in this image?"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "https://example.com/public-image.jpg"
        }
      }
    ]
  }'

Method 3: Direct Base64 String

You can encode the image directly into the JSON payload. This is easy for prototyping but incurs high token costs and inflates your request size significantly. It is not recommended for large files in production.

curl -X POST https://api.artaios.ai/api/v1/runtime/session_abc123/execute/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": [
      {
        "type": "text",
        "text": "Analyze this screenshot"
      },
      {
        "type": "image_url",
        "image_url": {
          "url": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQEA..."
        }
      }
    ]
  }'

Response from the agent:

{
  "id": "session_abc123",
  "object": "agent.session",
  "status": "completed",
  "messages": [
    {
      "id": "msg_ghi789",
      "role": "assistant",
      "content": "The image shows a dashboard with several metrics displayed. The main chart shows...",
      "created_at": 1704067220
    }
  ],
  "metadata": {
    "execution_id": "exec_ghi",
    "usage": {
      "input_tokens": 2048,
      "output_tokens": 156
    }
  }
}

Send a File for Processing

Pass files (PDFs, documents, etc.) to the agent:

File upload via REST execute endpoint is not fully tested. Known limitations:

File size limits may apply
Some file types may not be supported
Error handling may be incomplete

If you encounter issues, please report them with details about file type, size, and error message.

curl -X POST https://api.artaios.ai/api/v1/runtime/session_abc123/execute/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "content": [
      {
        "type": "text",
        "text": "Please analyze this PDF document"
      },
      {
        "type": "file",
        "file_url": "https://example.com/document.pdf"
      }
    ]
  }'

Expected response (if supported):

{
  "id": "session_abc123",
  "object": "agent.session",
  "status": "completed",
  "messages": [
    {
      "id": "msg_jkl012",
      "role": "assistant",
      "content": "I've analyzed the document. Here are the key points...",
      "created_at": 1704067230
    }
  ],
  "metadata": {
    "execution_id": "exec_jkl",
    "usage": {
      "input_tokens": 3456,
      "output_tokens": 289
    }
  }
}

Error Handling

Common errors and how to handle them:

Status Code	Error	Solution
`400`	Invalid configuration	Check your YAML/JSON syntax and required fields
`401`	Unauthorized	Verify your API key is correct and not expired
`404`	Session not found	Check the session ID exists and hasn’t been deleted
`429`	Rate limit exceeded	Implement exponential backoff and retry logic
`500`	Internal server error	Check request format; contact support if the issue persists

Next Steps

Variables Guide

Master passing variables to your agents

API Reference

Complete endpoint documentation

YAML Configuration

Learn agent configuration syntax

Chatbot Integration

Build real-time chat interfaces

Getting started

Agent Configuration

Multi Agent Systems

Advanced Features

Artaios Agents Studio

Platform

Integration

REST API

Prerequisites

Creating Sessions

Option 1: Load Session from YAML Configuration

Option 2: Load Session from Existing Agent

Communicating with a Session

Execute a Simple Message

Continue Conversation

Pass Variables with Your Message

Multimodal Input: Images and Files

Send an Image with Your Message

Method 1: The “Upload First” Method (Highly Recommended)

Method 2: Direct Public URL

Method 3: Direct Base64 String

Send a File for Processing

Error Handling

Next Steps

Variables Guide

API Reference

YAML Configuration

Chatbot Integration

​Prerequisites

​Creating Sessions

​Option 1: Load Session from YAML Configuration

​Option 2: Load Session from Existing Agent

​Communicating with a Session

​Execute a Simple Message

​Continue Conversation

​Pass Variables with Your Message

​Multimodal Input: Images and Files

​Send an Image with Your Message

​Method 1: The “Upload First” Method (Highly Recommended)

​Method 2: Direct Public URL

​Method 3: Direct Base64 String

​Send a File for Processing

​Error Handling

​Next Steps

Variables Guide

API Reference

YAML Configuration

Chatbot Integration

Prerequisites

Creating Sessions

Option 1: Load Session from YAML Configuration

Option 2: Load Session from Existing Agent

Communicating with a Session

Execute a Simple Message

Continue Conversation

Pass Variables with Your Message

Multimodal Input: Images and Files

Send an Image with Your Message

Method 1: The “Upload First” Method (Highly Recommended)

Method 2: Direct Public URL

Method 3: Direct Base64 String

Send a File for Processing

Error Handling

Next Steps