Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.atthene.com/llms.txt

Use this file to discover all available pages before exploring further.

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

1

Get API Key

Generate an API key from the Atthene Agent Studio settings
2

Base URL

All API requests use: https://api-be.atthene.com/api/v1
3

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-be.atthene.com/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 Atthene Agent Studio. Use the agent’s unique key: 
curl -X GET "https://api-be.atthene.com/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-be.atthene.com/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-be.atthene.com/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-be.atthene.com/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-be.atthene.com/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. If you are building an interface where users upload local files, you should upload the image to the Atthene 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-be.atthene.com/api/v1/images/upload/ \
  -H "x-api-key: YOUR_API_KEY" \
  -F "image=@/path/to/your/image.jpg"
Response: 
{
  "url": "https://api-be.atthene.com/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-be.atthene.com/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-be.atthene.com/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-be.atthene.com/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-be.atthene.com/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-be.atthene.com/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 CodeErrorSolution
400Invalid configurationCheck your YAML/JSON syntax and required fields
401UnauthorizedVerify your API key is correct and not expired
404Session not foundCheck the session ID exists and hasn’t been deleted
429Rate limit exceededImplement exponential backoff and retry logic
500Internal server errorCheck 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