> ## Documentation Index
> Fetch the complete documentation index at: https://docs.artaios.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API

> Complete guide to integrating AMAS agents into your applications via REST API

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

<Steps>
  <Step title="Get API Key">
    Generate an API key from the <a href="/documentation/studio/settings#settings-sections">Artaios Agent Studio settings</a>
  </Step>

  <Step title="Base URL">
    All API requests use: `https://api.artaios.ai/api/v1`
  </Step>

  <Step title="Authentication">
    Include your API key in the `x-api-key` header with every request
  </Step>
</Steps>

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

# 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):

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
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.

<Info>
  Learn more in the [Using Variables in REST API](/documentation/integration/variables-in-rest-api) guide.
</Info>

**Session-level variables** (persist across requests):

```bash theme={null}
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):

```bash theme={null}
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.

<Warning>
  **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](mailto:lorenz.stirnweis@arttacsolutions.de) with details about your use case.
</Warning>

## 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**

```bash theme={null}
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:

```json theme={null}
{
  "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**

```bash theme={null}
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.

```bash theme={null}
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.

```bash theme={null}
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:

```json theme={null}
{
  "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:

<Callout type="caution">
  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.
</Callout>

```bash theme={null}
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):

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Variables Guide" icon="code" href="/documentation/integration/variables-in-rest-api">
    Master passing variables to your agents
  </Card>

  <Card title="API Reference" icon="book" href="/api-reference/introduction">
    Complete endpoint documentation
  </Card>

  <Card title="YAML Configuration" icon="file-code" href="/documentation/yaml-configuration">
    Learn agent configuration syntax
  </Card>

  <Card title="Chatbot Integration" icon="comments" href="/documentation/integration/chatbot-integration">
    Build real-time chat interfaces
  </Card>
</CardGroup>