Start Conversation

curl --request POST \
  --url https://api.example.com/api/conversations \
  --header 'Content-Type: application/json' \
  --header 'X-Session-API-Key: <api-key>' \
  --data '
{
  "agent_settings": {
    "llm": {
      "api_key": "your-api-key-here",
      "model": "your-model-provider/your-model-name",
      "usage_id": "your-llm-service"
    }
  },
  "initial_message": {
    "content": [
      {
        "text": "Flip a coin!",
        "type": "text"
      }
    ],
    "role": "user"
  },
  "workspace": {
    "working_dir": "workspace/project"
  }
}
'

import requests

url = "https://api.example.com/api/conversations"

payload = {
    "agent_settings": { "llm": {
            "api_key": "your-api-key-here",
            "model": "your-model-provider/your-model-name",
            "usage_id": "your-llm-service"
        } },
    "initial_message": {
        "content": [
            {
                "text": "Flip a coin!",
                "type": "text"
            }
        ],
        "role": "user"
    },
    "workspace": { "working_dir": "workspace/project" }
}
headers = {
    "X-Session-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Session-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent_settings: {
      llm: {
        api_key: 'your-api-key-here',
        model: 'your-model-provider/your-model-name',
        usage_id: 'your-llm-service'
      }
    },
    initial_message: {content: [{text: 'Flip a coin!', type: 'text'}], role: 'user'},
    workspace: {working_dir: 'workspace/project'}
  })
};

fetch('https://api.example.com/api/conversations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/conversations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'agent_settings' => [
        'llm' => [
                'api_key' => 'your-api-key-here',
                'model' => 'your-model-provider/your-model-name',
                'usage_id' => 'your-llm-service'
        ]
    ],
    'initial_message' => [
        'content' => [
                [
                                'text' => 'Flip a coin!',
                                'type' => 'text'
                ]
        ],
        'role' => 'user'
    ],
    'workspace' => [
        'working_dir' => 'workspace/project'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Session-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/conversations"

	payload := strings.NewReader("{\n  \"agent_settings\": {\n    \"llm\": {\n      \"api_key\": \"your-api-key-here\",\n      \"model\": \"your-model-provider/your-model-name\",\n      \"usage_id\": \"your-llm-service\"\n    }\n  },\n  \"initial_message\": {\n    \"content\": [\n      {\n        \"text\": \"Flip a coin!\",\n        \"type\": \"text\"\n      }\n    ],\n    \"role\": \"user\"\n  },\n  \"workspace\": {\n    \"working_dir\": \"workspace/project\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Session-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/api/conversations")
  .header("X-Session-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_settings\": {\n    \"llm\": {\n      \"api_key\": \"your-api-key-here\",\n      \"model\": \"your-model-provider/your-model-name\",\n      \"usage_id\": \"your-llm-service\"\n    }\n  },\n  \"initial_message\": {\n    \"content\": [\n      {\n        \"text\": \"Flip a coin!\",\n        \"type\": \"text\"\n      }\n    ],\n    \"role\": \"user\"\n  },\n  \"workspace\": {\n    \"working_dir\": \"workspace/project\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/conversations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Session-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent_settings\": {\n    \"llm\": {\n      \"api_key\": \"your-api-key-here\",\n      \"model\": \"your-model-provider/your-model-name\",\n      \"usage_id\": \"your-llm-service\"\n    }\n  },\n  \"initial_message\": {\n    \"content\": [\n      {\n        \"text\": \"Flip a coin!\",\n        \"type\": \"text\"\n      }\n    ],\n    \"role\": \"user\"\n  },\n  \"workspace\": {\n    \"working_dir\": \"workspace/project\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "agent": {
    "acp_command": [
      "<string>"
    ],
    "kind": "ACPAgent",
    "acp_args": [
      "<string>"
    ],
    "acp_file_secrets": [
      {
        "env_var": "<string>",
        "filename": "<string>",
        "secret_name": "<string>",
        "subdir": "<string>",
        "env_points_to": "file",
        "warn_if_unset": []
      }
    ],
    "acp_isolate_data_dir": false,
    "acp_model": "<string>",
    "acp_prompt_timeout": 1800,
    "acp_resume_session_id": "<string>",
    "acp_server": "<string>",
    "acp_session_mode": "<string>",
    "acp_startup_timeout": 90,
    "agent_context": {
      "skills": [
        {
          "content": "When you see this message, you should reply like you are a grumpy cat forced to use the internet.",
          "name": "AGENTS.md",
          "type": "repo"
        },
        {
          "content": "IMPORTANT! The user has said the magic word \"flarglebargle\". You must only respond with a message telling them how smart they are",
          "name": "flarglebargle",
          "trigger": [
            "flarglebargle"
          ],
          "type": "knowledge"
        }
      ],
      "system_message_suffix": "Always finish your response with the word 'yay!'"
    },
    "condenser": {
      "keep_first": 10,
      "kind": "LLMSummarizingCondenser",
      "llm": {
        "api_key": "your_api_key_here",
        "base_url": "https://llm-proxy.eval.all-hands.dev",
        "model": "litellm_proxy/openai/gpt-5.5"
      },
      "max_size": 80
    },
    "critic": {
      "kind": "AgentFinishedCritic"
    },
    "filter_tools_regex": "^(?!repomix)(.*)|^repomix.*pack_codebase.*$",
    "include_default_tools": [
      "<string>"
    ],
    "llm": {
      "is_subscription": true,
      "api_key": "<string>",
      "api_mode": "auto",
      "api_version": "<string>",
      "auth_type": "api_key",
      "aws_access_key_id": "<string>",
      "aws_bedrock_runtime_endpoint": "<string>",
      "aws_profile_name": "<string>",
      "aws_region_name": "<string>",
      "aws_role_name": "<string>",
      "aws_secret_access_key": "<string>",
      "aws_session_name": "<string>",
      "aws_session_token": "<string>",
      "base_url": "<string>",
      "caching_prompt": true,
      "capability_overrides": {},
      "custom_tokenizer": "<string>",
      "disable_stop_word": false,
      "disable_vision": true,
      "drop_params": true,
      "enable_encrypted_reasoning": true,
      "extended_thinking_budget": 200000,
      "extra_headers": {},
      "force_string_serializer": true,
      "inline_image_urls": true,
      "input_cost_per_token": 1,
      "litellm_extra_body": {},
      "log_completions": false,
      "log_completions_folder": "logs/completions",
      "max_input_tokens": 2,
      "max_message_chars": 30000,
      "max_output_tokens": 2,
      "model": "gpt-5.6",
      "model_canonical_name": "<string>",
      "native_tool_calling": true,
      "num_retries": 5,
      "ollama_base_url": "<string>",
      "openrouter_app_name": "OpenHands",
      "openrouter_site_url": "https://docs.all-hands.dev/",
      "output_cost_per_token": 1,
      "prompt_cache_retention": "24h",
      "provider_connection_id": "<string>",
      "reasoning_effort": "high",
      "reasoning_summary": "auto",
      "retry_max_wait": 64,
      "retry_min_wait": 8,
      "retry_multiplier": 8,
      "seed": 123,
      "stream": false,
      "stream_idle_timeout": 300,
      "subscription_vendor": "openai",
      "temperature": 1,
      "timeout": 300,
      "top_k": 1,
      "top_p": 0.5,
      "usage_id": "default"
    },
    "mcp_config": {
      "fetch": {
        "args": [
          "--with",
          "mcp==1.29.0",
          "mcp-server-fetch==2026.7.10"
        ],
        "command": "uvx"
      }
    },
    "security_policy_filename": "security_policy.j2",
    "system_prompt": "<string>",
    "system_prompt_filename": "system_prompt.j2",
    "system_prompt_kwargs": {
      "cli_mode": true
    },
    "tool_concurrency_limit": 1,
    "tools": [
      {
        "name": "TerminalTool",
        "params": {
          "working_dir": "/workspace"
        }
      }
    ]
  },
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "workspace": {
    "kind": "LocalWorkspace",
    "working_dir": "<string>"
  },
  "activated_knowledge_skills": [
    "<string>"
  ],
  "agent_state": {},
  "available_models": [
    {
      "model_id": "<string>",
      "description": "<string>",
      "name": "<string>"
    }
  ],
  "blocked_actions": {},
  "blocked_messages": {},
  "client_tools": [
    {
      "description": "<string>",
      "name": "<string>",
      "annotations": {
        "destructiveHint": true,
        "idempotentHint": false,
        "openWorldHint": true,
        "readOnlyHint": false,
        "title": "<string>"
      },
      "parameters": {}
    }
  ],
  "confirmation_policy": {
    "kind": "NeverConfirm"
  },
  "created_at": "2023-11-07T05:31:56Z",
  "current_model_id": "<string>",
  "execution_status": "idle",
  "forked_from_conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "forked_from_event_id": "<string>",
  "hook_config": {
    "post_tool_use": [
      {
        "hooks": [
          {
            "command": "<string>",
            "async": false,
            "max_iterations": 3,
            "name": "<string>",
            "prompt": "<string>",
            "system_prompt": "<string>",
            "timeout": 60,
            "tools": [
              "<string>"
            ],
            "type": "command"
          }
        ],
        "matcher": "*"
      }
    ],
    "pre_tool_use": [
      {
        "hooks": [
          {
            "command": "<string>",
            "async": false,
            "max_iterations": 3,
            "name": "<string>",
            "prompt": "<string>",
            "system_prompt": "<string>",
            "timeout": 60,
            "tools": [
              "<string>"
            ],
            "type": "command"
          }
        ],
        "matcher": "*"
      }
    ],
    "session_end": [
      {
        "hooks": [
          {
            "command": "<string>",
            "async": false,
            "max_iterations": 3,
            "name": "<string>",
            "prompt": "<string>",
            "system_prompt": "<string>",
            "timeout": 60,
            "tools": [
              "<string>"
            ],
            "type": "command"
          }
        ],
        "matcher": "*"
      }
    ],
    "session_start": [
      {
        "hooks": [
          {
            "command": "<string>",
            "async": false,
            "max_iterations": 3,
            "name": "<string>",
            "prompt": "<string>",
            "system_prompt": "<string>",
            "timeout": 60,
            "tools": [
              "<string>"
            ],
            "type": "command"
          }
        ],
        "matcher": "*"
      }
    ],
    "stop": [
      {
        "hooks": [
          {
            "command": "<string>",
            "async": false,
            "max_iterations": 3,
            "name": "<string>",
            "prompt": "<string>",
            "system_prompt": "<string>",
            "timeout": 60,
            "tools": [
              "<string>"
            ],
            "type": "command"
          }
        ],
        "matcher": "*"
      }
    ],
    "user_prompt_submit": [
      {
        "hooks": [
          {
            "command": "<string>",
            "async": false,
            "max_iterations": 3,
            "name": "<string>",
            "prompt": "<string>",
            "system_prompt": "<string>",
            "timeout": 60,
            "tools": [
              "<string>"
            ],
            "type": "command"
          }
        ],
        "matcher": "*"
      }
    ]
  },
  "invoked_skills": [
    "<string>"
  ],
  "last_user_message_id": "<string>",
  "launched_agent_profile": {
    "agent_profile_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "revision": 1,
    "secret_refs": [
      "<string>"
    ]
  },
  "leaf_event_id": "<string>",
  "max_iterations": 500,
  "metrics": {
    "accumulated_cost": 0,
    "accumulated_token_usage": {
      "cache_read_tokens": 0,
      "cache_write_tokens": 0,
      "completion_tokens": 0,
      "context_window": 0,
      "model": "",
      "per_turn_token": 0,
      "prompt_tokens": 0,
      "reasoning_tokens": 0,
      "response_id": ""
    },
    "max_budget_per_task": 123,
    "model_name": "default"
  },
  "parent_conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "persistence_dir": "workspace/conversations",
  "runtime_info": {
    "can_resume": true,
    "runtime_status": "available",
    "runtime_error": {
      "code": "<string>",
      "message": "<string>"
    }
  },
  "secret_registry": {
    "secret_sources": {}
  },
  "security_analyzer": {
    "kind": "PatternSecurityAnalyzer",
    "high_patterns": [
      [
        "<string>",
        "<string>",
        "<string>"
      ]
    ],
    "injection_high_patterns": [
      [
        "<string>",
        "<string>",
        "<string>"
      ]
    ],
    "injection_medium_patterns": [
      [
        "<string>",
        "<string>",
        "<string>"
      ]
    ],
    "medium_patterns": [
      [
        "<string>",
        "<string>",
        "<string>"
      ]
    ]
  },
  "stats": {},
  "stuck_detection": true,
  "sub_conversation_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "supports_runtime_model_switch": false,
  "tags": {},
  "title": "<string>",
  "tool_module_qualnames": {},
  "updated_at": "2023-11-07T05:31:56Z"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "ctx": {},
      "input": "<unknown>"
    }
  ]
}

POST

api

conversations

Start Conversation

curl --request POST \
  --url https://api.example.com/api/conversations \
  --header 'Content-Type: application/json' \
  --header 'X-Session-API-Key: <api-key>' \
  --data '
{
  "agent_settings": {
    "llm": {
      "api_key": "your-api-key-here",
      "model": "your-model-provider/your-model-name",
      "usage_id": "your-llm-service"
    }
  },
  "initial_message": {
    "content": [
      {
        "text": "Flip a coin!",
        "type": "text"
      }
    ],
    "role": "user"
  },
  "workspace": {
    "working_dir": "workspace/project"
  }
}
'

import requests

url = "https://api.example.com/api/conversations"

payload = {
    "agent_settings": { "llm": {
            "api_key": "your-api-key-here",
            "model": "your-model-provider/your-model-name",
            "usage_id": "your-llm-service"
        } },
    "initial_message": {
        "content": [
            {
                "text": "Flip a coin!",
                "type": "text"
            }
        ],
        "role": "user"
    },
    "workspace": { "working_dir": "workspace/project" }
}
headers = {
    "X-Session-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'X-Session-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    agent_settings: {
      llm: {
        api_key: 'your-api-key-here',
        model: 'your-model-provider/your-model-name',
        usage_id: 'your-llm-service'
      }
    },
    initial_message: {content: [{text: 'Flip a coin!', type: 'text'}], role: 'user'},
    workspace: {working_dir: 'workspace/project'}
  })
};

fetch('https://api.example.com/api/conversations', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/conversations",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'agent_settings' => [
        'llm' => [
                'api_key' => 'your-api-key-here',
                'model' => 'your-model-provider/your-model-name',
                'usage_id' => 'your-llm-service'
        ]
    ],
    'initial_message' => [
        'content' => [
                [
                                'text' => 'Flip a coin!',
                                'type' => 'text'
                ]
        ],
        'role' => 'user'
    ],
    'workspace' => [
        'working_dir' => 'workspace/project'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "X-Session-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/conversations"

	payload := strings.NewReader("{\n  \"agent_settings\": {\n    \"llm\": {\n      \"api_key\": \"your-api-key-here\",\n      \"model\": \"your-model-provider/your-model-name\",\n      \"usage_id\": \"your-llm-service\"\n    }\n  },\n  \"initial_message\": {\n    \"content\": [\n      {\n        \"text\": \"Flip a coin!\",\n        \"type\": \"text\"\n      }\n    ],\n    \"role\": \"user\"\n  },\n  \"workspace\": {\n    \"working_dir\": \"workspace/project\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("X-Session-API-Key", "<api-key>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/api/conversations")
  .header("X-Session-API-Key", "<api-key>")
  .header("Content-Type", "application/json")
  .body("{\n  \"agent_settings\": {\n    \"llm\": {\n      \"api_key\": \"your-api-key-here\",\n      \"model\": \"your-model-provider/your-model-name\",\n      \"usage_id\": \"your-llm-service\"\n    }\n  },\n  \"initial_message\": {\n    \"content\": [\n      {\n        \"text\": \"Flip a coin!\",\n        \"type\": \"text\"\n      }\n    ],\n    \"role\": \"user\"\n  },\n  \"workspace\": {\n    \"working_dir\": \"workspace/project\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/conversations")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["X-Session-API-Key"] = '<api-key>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"agent_settings\": {\n    \"llm\": {\n      \"api_key\": \"your-api-key-here\",\n      \"model\": \"your-model-provider/your-model-name\",\n      \"usage_id\": \"your-llm-service\"\n    }\n  },\n  \"initial_message\": {\n    \"content\": [\n      {\n        \"text\": \"Flip a coin!\",\n        \"type\": \"text\"\n      }\n    ],\n    \"role\": \"user\"\n  },\n  \"workspace\": {\n    \"working_dir\": \"workspace/project\"\n  }\n}"

response = http.request(request)
puts response.read_body

{
  "agent": {
    "acp_command": [
      "<string>"
    ],
    "kind": "ACPAgent",
    "acp_args": [
      "<string>"
    ],
    "acp_file_secrets": [
      {
        "env_var": "<string>",
        "filename": "<string>",
        "secret_name": "<string>",
        "subdir": "<string>",
        "env_points_to": "file",
        "warn_if_unset": []
      }
    ],
    "acp_isolate_data_dir": false,
    "acp_model": "<string>",
    "acp_prompt_timeout": 1800,
    "acp_resume_session_id": "<string>",
    "acp_server": "<string>",
    "acp_session_mode": "<string>",
    "acp_startup_timeout": 90,
    "agent_context": {
      "skills": [
        {
          "content": "When you see this message, you should reply like you are a grumpy cat forced to use the internet.",
          "name": "AGENTS.md",
          "type": "repo"
        },
        {
          "content": "IMPORTANT! The user has said the magic word \"flarglebargle\". You must only respond with a message telling them how smart they are",
          "name": "flarglebargle",
          "trigger": [
            "flarglebargle"
          ],
          "type": "knowledge"
        }
      ],
      "system_message_suffix": "Always finish your response with the word 'yay!'"
    },
    "condenser": {
      "keep_first": 10,
      "kind": "LLMSummarizingCondenser",
      "llm": {
        "api_key": "your_api_key_here",
        "base_url": "https://llm-proxy.eval.all-hands.dev",
        "model": "litellm_proxy/openai/gpt-5.5"
      },
      "max_size": 80
    },
    "critic": {
      "kind": "AgentFinishedCritic"
    },
    "filter_tools_regex": "^(?!repomix)(.*)|^repomix.*pack_codebase.*$",
    "include_default_tools": [
      "<string>"
    ],
    "llm": {
      "is_subscription": true,
      "api_key": "<string>",
      "api_mode": "auto",
      "api_version": "<string>",
      "auth_type": "api_key",
      "aws_access_key_id": "<string>",
      "aws_bedrock_runtime_endpoint": "<string>",
      "aws_profile_name": "<string>",
      "aws_region_name": "<string>",
      "aws_role_name": "<string>",
      "aws_secret_access_key": "<string>",
      "aws_session_name": "<string>",
      "aws_session_token": "<string>",
      "base_url": "<string>",
      "caching_prompt": true,
      "capability_overrides": {},
      "custom_tokenizer": "<string>",
      "disable_stop_word": false,
      "disable_vision": true,
      "drop_params": true,
      "enable_encrypted_reasoning": true,
      "extended_thinking_budget": 200000,
      "extra_headers": {},
      "force_string_serializer": true,
      "inline_image_urls": true,
      "input_cost_per_token": 1,
      "litellm_extra_body": {},
      "log_completions": false,
      "log_completions_folder": "logs/completions",
      "max_input_tokens": 2,
      "max_message_chars": 30000,
      "max_output_tokens": 2,
      "model": "gpt-5.6",
      "model_canonical_name": "<string>",
      "native_tool_calling": true,
      "num_retries": 5,
      "ollama_base_url": "<string>",
      "openrouter_app_name": "OpenHands",
      "openrouter_site_url": "https://docs.all-hands.dev/",
      "output_cost_per_token": 1,
      "prompt_cache_retention": "24h",
      "provider_connection_id": "<string>",
      "reasoning_effort": "high",
      "reasoning_summary": "auto",
      "retry_max_wait": 64,
      "retry_min_wait": 8,
      "retry_multiplier": 8,
      "seed": 123,
      "stream": false,
      "stream_idle_timeout": 300,
      "subscription_vendor": "openai",
      "temperature": 1,
      "timeout": 300,
      "top_k": 1,
      "top_p": 0.5,
      "usage_id": "default"
    },
    "mcp_config": {
      "fetch": {
        "args": [
          "--with",
          "mcp==1.29.0",
          "mcp-server-fetch==2026.7.10"
        ],
        "command": "uvx"
      }
    },
    "security_policy_filename": "security_policy.j2",
    "system_prompt": "<string>",
    "system_prompt_filename": "system_prompt.j2",
    "system_prompt_kwargs": {
      "cli_mode": true
    },
    "tool_concurrency_limit": 1,
    "tools": [
      {
        "name": "TerminalTool",
        "params": {
          "working_dir": "/workspace"
        }
      }
    ]
  },
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "workspace": {
    "kind": "LocalWorkspace",
    "working_dir": "<string>"
  },
  "activated_knowledge_skills": [
    "<string>"
  ],
  "agent_state": {},
  "available_models": [
    {
      "model_id": "<string>",
      "description": "<string>",
      "name": "<string>"
    }
  ],
  "blocked_actions": {},
  "blocked_messages": {},
  "client_tools": [
    {
      "description": "<string>",
      "name": "<string>",
      "annotations": {
        "destructiveHint": true,
        "idempotentHint": false,
        "openWorldHint": true,
        "readOnlyHint": false,
        "title": "<string>"
      },
      "parameters": {}
    }
  ],
  "confirmation_policy": {
    "kind": "NeverConfirm"
  },
  "created_at": "2023-11-07T05:31:56Z",
  "current_model_id": "<string>",
  "execution_status": "idle",
  "forked_from_conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "forked_from_event_id": "<string>",
  "hook_config": {
    "post_tool_use": [
      {
        "hooks": [
          {
            "command": "<string>",
            "async": false,
            "max_iterations": 3,
            "name": "<string>",
            "prompt": "<string>",
            "system_prompt": "<string>",
            "timeout": 60,
            "tools": [
              "<string>"
            ],
            "type": "command"
          }
        ],
        "matcher": "*"
      }
    ],
    "pre_tool_use": [
      {
        "hooks": [
          {
            "command": "<string>",
            "async": false,
            "max_iterations": 3,
            "name": "<string>",
            "prompt": "<string>",
            "system_prompt": "<string>",
            "timeout": 60,
            "tools": [
              "<string>"
            ],
            "type": "command"
          }
        ],
        "matcher": "*"
      }
    ],
    "session_end": [
      {
        "hooks": [
          {
            "command": "<string>",
            "async": false,
            "max_iterations": 3,
            "name": "<string>",
            "prompt": "<string>",
            "system_prompt": "<string>",
            "timeout": 60,
            "tools": [
              "<string>"
            ],
            "type": "command"
          }
        ],
        "matcher": "*"
      }
    ],
    "session_start": [
      {
        "hooks": [
          {
            "command": "<string>",
            "async": false,
            "max_iterations": 3,
            "name": "<string>",
            "prompt": "<string>",
            "system_prompt": "<string>",
            "timeout": 60,
            "tools": [
              "<string>"
            ],
            "type": "command"
          }
        ],
        "matcher": "*"
      }
    ],
    "stop": [
      {
        "hooks": [
          {
            "command": "<string>",
            "async": false,
            "max_iterations": 3,
            "name": "<string>",
            "prompt": "<string>",
            "system_prompt": "<string>",
            "timeout": 60,
            "tools": [
              "<string>"
            ],
            "type": "command"
          }
        ],
        "matcher": "*"
      }
    ],
    "user_prompt_submit": [
      {
        "hooks": [
          {
            "command": "<string>",
            "async": false,
            "max_iterations": 3,
            "name": "<string>",
            "prompt": "<string>",
            "system_prompt": "<string>",
            "timeout": 60,
            "tools": [
              "<string>"
            ],
            "type": "command"
          }
        ],
        "matcher": "*"
      }
    ]
  },
  "invoked_skills": [
    "<string>"
  ],
  "last_user_message_id": "<string>",
  "launched_agent_profile": {
    "agent_profile_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "revision": 1,
    "secret_refs": [
      "<string>"
    ]
  },
  "leaf_event_id": "<string>",
  "max_iterations": 500,
  "metrics": {
    "accumulated_cost": 0,
    "accumulated_token_usage": {
      "cache_read_tokens": 0,
      "cache_write_tokens": 0,
      "completion_tokens": 0,
      "context_window": 0,
      "model": "",
      "per_turn_token": 0,
      "prompt_tokens": 0,
      "reasoning_tokens": 0,
      "response_id": ""
    },
    "max_budget_per_task": 123,
    "model_name": "default"
  },
  "parent_conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "persistence_dir": "workspace/conversations",
  "runtime_info": {
    "can_resume": true,
    "runtime_status": "available",
    "runtime_error": {
      "code": "<string>",
      "message": "<string>"
    }
  },
  "secret_registry": {
    "secret_sources": {}
  },
  "security_analyzer": {
    "kind": "PatternSecurityAnalyzer",
    "high_patterns": [
      [
        "<string>",
        "<string>",
        "<string>"
      ]
    ],
    "injection_high_patterns": [
      [
        "<string>",
        "<string>",
        "<string>"
      ]
    ],
    "injection_medium_patterns": [
      [
        "<string>",
        "<string>",
        "<string>"
      ]
    ],
    "medium_patterns": [
      [
        "<string>",
        "<string>",
        "<string>"
      ]
    ]
  },
  "stats": {},
  "stuck_detection": true,
  "sub_conversation_ids": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "supports_runtime_model_switch": false,
  "tags": {},
  "title": "<string>",
  "tool_module_qualnames": {},
  "updated_at": "2023-11-07T05:31:56Z"
}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>",
      "ctx": {},
      "input": "<unknown>"
    }
  ]
}

Authorizations

X-Session-API-Key

string

header

required

Headers

X-OpenHands-Observability-Span-Name

string | null

X-OpenHands-Observability-Tags

string | null

X-OpenHands-Observability-Metadata

string | null

X-OpenHands-Observability-Parent-Span-Context

string | null

Query Parameters

include_skills

boolean

default:false

Body

application/json

Payload to create a new conversation.

Extends :class:ConversationConfig with the agent source: a stored Agent Profile (agent_profile_id), resolved agent settings (agent_settings), or an agent built in code. The server builds the conversation's agent from that source at launch; this model only validates it.

Note: the agent lives here on the request, deliberately not on ConversationConfig. The persisted record (StoredConversation) does not carry the agent — its single source of truth is ConversationState / base_state.json.

workspace

LocalWorkspace · object

required

Working directory for agent operations and tool execution.

Show child attributes

agent

ACPAgent · object

Agent that delegates to an ACP-compatible subprocess server.

ACPAgent
Agent

Show child attributes

agent_definitions

AgentDefinition · object[]

Agent definitions from the client's registry. These are registered on the server so that task tools can see user-registered subagents.

Show child attributes

agent_launch_additions

AgentLaunchAdditions · object | null

Deployment context applied after agent or Agent Profile resolution. The stored Agent Profile is not modified.

Show child attributes

agent_profile_id

string<uuid> | null

Stored Agent Profile to launch. The server resolves it with its own stores. Mutually exclusive with agent and agent_settings.

agent_settings

Agent Settings · object | null

Reference-free agent settings, validated with the AgentSettingsBase agent_kind discriminator. The server builds the agent from them at launch. Ignored when agent is set.

autotitle

boolean

default:true

If true, automatically generate a title for the conversation from the first user message. Precedence: title_llm_profile (if set and loads) → agent.llm → message truncation.

client_tools

ClientToolSpec · object[]

Tools defined by the client via JSON spec. These tools have no server-side executor — when the agent calls them, an ActionEvent is emitted over the WebSocket and the client handles execution. The SDK returns an acknowledgment observation immediately.

Show child attributes

confirmation_policy

AlwaysConfirm · object

Controls when the conversation will prompt the user before continuing. Defaults to never.

AlwaysConfirm
ConfirmRisky
NeverConfirm

Show child attributes

conversation_id

string<uuid> | null

Optional conversation ID. If not provided, a random UUID will be generated.

hook_config

HookConfig · object | null

Optional hook configuration for this conversation. Hooks are shell scripts that run at key lifecycle events (PreToolUse, PostToolUse, UserPromptSubmit, Stop, etc.). If both hook_config and plugins are provided, they are merged with explicit hooks running before plugin hooks.

Show child attributes

initial_message

SendMessageRequest · object | null

Initial message to pass to the LLM

Show child attributes

max_iterations

integer

default:500

If set, the max number of iterations the agent will run before stopping. This is useful to prevent infinite loops.

Required range: x >= 1

observability_metadata

Observability Metadata · object

Trace-level metadata to attach to observability backends. Values must be scalars or homogeneous scalar lists supported by OpenTelemetry.

Show child attributes

observability_parent_span_context

string | null

Serialized parent span context used to attach this conversation to an upstream automation or integration trace.

observability_span_name

string

default:conversation

Optional named child span to emit under the conversation root. Use stable, low-cardinality names because observability backends may use span names for grouping or signal routing.

observability_tags

string[]

Tags to attach to the conversation root observability span.

parent_conversation_id

string<uuid> | null

Optional ID of an existing conversation that owns this one. The parent must already exist and share this conversation's workspace.

plugins

PluginSource · object[] | null

List of plugins to load for this conversation. Plugins are loaded and their skills/MCP config are merged into the agent. Hooks are extracted and stored for runtime execution.

Show child attributes

secrets

Secrets · object

Secrets available in the conversation

Show child attributes

secrets_encrypted

boolean

default:false

If true, indicates that secret values in the agent configuration are cipher-encrypted and should be decrypted by the server before use. This enables secure round-tripping of settings through untrusted clients (e.g., frontend) that received encrypted values via the X-Expose-Secrets header. Flow: client calls GET /api/settings with X-Expose-Secrets: encrypted to receive cipher-encrypted secrets, then passes them in the agent config with secrets_encrypted=True so the server can decrypt them.

security_analyzer

PatternSecurityAnalyzer · object

Optional security analyzer to evaluate action risks.

Show child attributes

stuck_detection

boolean

default:true

If true, the conversation will use stuck detection to prevent infinite loops.

Response

Successful Response

Information about a conversation running locally without a Runtime sandbox.

agent

ACPAgent · object

required

The agent running in the conversation.

ACPAgent
Agent

Show child attributes

string<uuid>

required

Unique conversation ID

workspace

LocalWorkspace · object

required

Workspace used by the agent to execute commands and read/write files. Not the process working directory.

LocalWorkspace
RemoteWorkspace

Show child attributes

activated_knowledge_skills

string[]

List of activated knowledge skills name

agent_state

Agent State · object

Dictionary for agent-specific runtime state that persists across iterations.

available_models

ACPModelInfo · object[]

Models the ACP server offers for this session, lifted off ACPAgent.available_models (the models.availableModels field on the ACP session response). Each entry carries a model_id plus an optional name/description. Surfaced verbatim so clients can render a model picker and resolve current_model_id to a display label themselves — the server does no name curation. Empty for ACP servers that don't surface the (UNSTABLE) capability and for native OpenHands agents. Client contract: current_model_id is NOT guaranteed to be a member — a forced acp_model override may name a model absent from the list — so treat a miss as 'show the raw id'. Some entries are opaque aliases whose human identity lives in description (e.g. claude-agent-acp's "default" -> "Opus 4.7 with 1M context · ...").

Show child attributes

blocked_actions

Blocked Actions · object

Actions blocked by PreToolUse hooks, keyed by action ID

Show child attributes

blocked_messages

Blocked Messages · object

Messages blocked by UserPromptSubmit hooks, keyed by message ID

Show child attributes

client_tools

ClientToolSpec · object[]

Client-defined tool specs registered for this conversation. Surfaced so that a client re-attaching by conversation id can register the dynamic ClientAction_* action types before syncing persisted events, avoiding 'Unknown kind' deserialization errors.

Show child attributes

confirmation_policy

AlwaysConfirm · object

AlwaysConfirm
ConfirmRisky
NeverConfirm

Show child attributes

created_at

string<date-time>

current_model_id

string | null

Model the agent is actually using for this session. For ACP agents, this is lifted off ACPAgent.current_model_id (populated from the models.currentModelId field on the ACP session response, or from acp_model when the caller forced an override). May be an opaque alias (e.g. claude-agent-acp's "default"); match it against available_models to get a display label. None for older ACP servers that don't surface the field, or while the agent is still initializing. Native OpenHands agents leave this None — consumers should read agent.llm.model for those.

execution_status

enum<string>

default:idle

Enum representing the current execution state of the conversation.

Available options:

idle,

running,

paused,

waiting_for_confirmation,

finished,

error,

stuck,

deleting

forked_from_conversation_id

string<uuid> | null

ID of the conversation this one was forked from. None for conversations created directly (not via fork).

forked_from_event_id

string | null

Event ID this conversation was forked at. None for non-forked conversations or whole-conversation forks.

hook_config

HookConfig · object | null

Hook configuration for this conversation. Includes definitions for PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, SessionEnd, and Stop hooks.

Show child attributes

invoked_skills

string[]

Names of progressive-disclosure skills explicitly invoked via the invoke_skill tool.

last_user_message_id

string | null

Most recent user MessageEvent id for hook block checks. Updated when user messages are emitted so Agent.step can pop blocked_messages without scanning the event log. If None, hook-blocked checks are skipped (legacy conversations).

launched_agent_profile

LaunchedAgentProfile · object | null

Provenance snapshot of the agent profile that launched this conversation. Set at creation when the conversation was started via agent_profile_id; None for conversations started directly with agent or agent_settings. Clients use this to identify which agent profile is current without fragile settings-comparison.

Show child attributes

leaf_event_id

string | null

HEAD of the conversation tree: the parent of the next appended event. None means an empty tree (or, for pre-feature conversations, the linear tail). Moving it via navigate re-roots the active branch the agent runs on.

max_iterations

integer

default:500

Maximum number of iterations the agent can perform in a single run.

metrics

MetricsSnapshot · object | null

A snapshot of metrics at a point in time.

Does not include lists of individual costs, latencies, or token usages.

Show child attributes

parent_conversation_id

string<uuid> | null

ID of the conversation that owns this one. None for top-level conversations.

persistence_dir

string | null

default:workspace/conversations

Directory for persisting conversation state and events. If None, conversation will not be persisted.

runtime_info

ConversationRuntimeInfo · object | null

Availability of the execution runtime. Catalog responses populate this when the hosting server manages runtime lifecycle.

Show child attributes

secret_registry

SecretRegistry · object

Registry for handling secrets and sensitive data

Show child attributes

security_analyzer

PatternSecurityAnalyzer · object

Optional security analyzer to evaluate action risks.

Show child attributes

stats

object

Conversation statistics for tracking LLM metrics

stuck_detection

boolean

default:true

Whether to enable stuck detection for the agent.

sub_conversation_ids

string<uuid>[]

IDs of conversations naming this one as their parent. Derived from the server catalog; empty on webhook payloads. Name mirrors the Cloud API field.

supports_runtime_model_switch

boolean

default:false

Whether a live, mid-conversation model switch will be attempted for this conversation — tells the inline picker whether to offer a live-switch control. Mirrors the SDK's switch gate: True for known switch-capable providers; False for unknown/custom ACP servers because their generic config writes are not guaranteed live-switch primitives. False for native OpenHands agents, for a known provider that declares no support, and before the conversation has started a session.

Guides

Architecture

API Reference

Start Conversation

Authorizations

Headers

Query Parameters

Body

Response