Start Conversation

Start a conversation in the local environment.

POST /api/conversations

Start Conversation

cURL

curl --request POST \
  --url https://api.example.com/api/conversations \
  --header 'Content-Type: application/json' \
  --header 'X-Session-API-Key: <api-key>' \
  --data @- <<EOF
{
  "agent": {
    "acp_command": [
      "<string>"
    ],
    "llm": {
      "model": "claude-sonnet-4-20250514",
      "api_key": "<string>",
      "base_url": "<string>",
      "api_version": "<string>",
      "aws_access_key_id": "<string>",
      "aws_secret_access_key": "<string>",
      "aws_region_name": "<string>",
      "openrouter_site_url": "https://docs.all-hands.dev/",
      "openrouter_app_name": "OpenHands",
      "num_retries": 5,
      "retry_multiplier": 8,
      "retry_min_wait": 8,
      "retry_max_wait": 64,
      "timeout": 300,
      "max_message_chars": 30000,
      "temperature": 1,
      "top_p": 0.5,
      "top_k": 1,
      "max_input_tokens": 2,
      "max_output_tokens": 2,
      "model_canonical_name": "<string>",
      "extra_headers": {},
      "input_cost_per_token": 1,
      "output_cost_per_token": 1,
      "ollama_base_url": "<string>",
      "stream": false,
      "drop_params": true,
      "modify_params": true,
      "disable_vision": true,
      "disable_stop_word": false,
      "caching_prompt": true,
      "log_completions": false,
      "log_completions_folder": "logs/completions",
      "custom_tokenizer": "<string>",
      "native_tool_calling": true,
      "force_string_serializer": true,
      "reasoning_effort": "high",
      "reasoning_summary": "auto",
      "enable_encrypted_reasoning": true,
      "prompt_cache_retention": "24h",
      "extended_thinking_budget": 200000,
      "seed": 123,
      "safety_settings": [
        {}
      ],
      "usage_id": "default",
      "litellm_extra_body": {},
      "fallback_strategy": {
        "fallback_llms": [
          "<string>"
        ],
        "profile_store_dir": "<string>"
      }
    },
    "tools": [
      {
        "name": "<string>",
        "params": {}
      }
    ],
    "mcp_config": {},
    "filter_tools_regex": "^(?!repomix)(.*)|^repomix.*pack_codebase.*$",
    "include_default_tools": [
      "<string>"
    ],
    "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!'",
      "user_message_prefix": "The first character of your response should be 'I'"
    },
    "system_prompt_filename": "system_prompt.j2",
    "security_policy_filename": "security_policy.j2",
    "system_prompt_kwargs": {},
    "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/anthropic/claude-sonnet-4-5-20250929"
      },
      "max_size": 80
    },
    "critic": {
      "kind": "AgentFinishedCritic"
    },
    "acp_args": [
      "<string>"
    ],
    "acp_env": {},
    "acp_session_mode": "<string>",
    "acp_prompt_timeout": 1800,
    "acp_model": "<string>",
    "kind": "<string>"
  },
  "workspace": {
    "working_dir": "<string>",
    "kind": "<string>"
  },
  "conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "confirmation_policy": {
    "kind": "NeverConfirm"
  },
  "initial_message": {
    "role": "user",
    "content": [
      {
        "text": "<string>",
        "cache_prompt": false,
        "type": "text"
      }
    ],
    "run": false
  },
  "max_iterations": 500,
  "stuck_detection": true,
  "secrets": {},
  "tool_module_qualnames": {},
  "agent_definitions": [
    {
      "name": "<string>",
      "description": "",
      "model": "inherit",
      "color": "<string>",
      "tools": [
        "<string>"
      ],
      "skills": [
        "<string>"
      ],
      "system_prompt": "",
      "source": "<string>",
      "when_to_use_examples": [
        "<string>"
      ],
      "hooks": {
        "pre_tool_use": [
          {
            "matcher": "*",
            "hooks": [
              {
                "command": "<string>",
                "type": "command",
                "timeout": 60,
                "async": false
              }
            ]
          }
        ],
        "post_tool_use": [
          {
            "matcher": "*",
            "hooks": [
              {
                "command": "<string>",
                "type": "command",
                "timeout": 60,
                "async": false
              }
            ]
          }
        ],
        "user_prompt_submit": [
          {
            "matcher": "*",
            "hooks": [
              {
                "command": "<string>",
                "type": "command",
                "timeout": 60,
                "async": false
              }
            ]
          }
        ],
        "session_start": [
          {
            "matcher": "*",
            "hooks": [
              {
                "command": "<string>",
                "type": "command",
                "timeout": 60,
                "async": false
              }
            ]
          }
        ],
        "session_end": [
          {
            "matcher": "*",
            "hooks": [
              {
                "command": "<string>",
                "type": "command",
                "timeout": 60,
                "async": false
              }
            ]
          }
        ],
        "stop": [
          {
            "matcher": "*",
            "hooks": [
              {
                "command": "<string>",
                "type": "command",
                "timeout": 60,
                "async": false
              }
            ]
          }
        ]
      },
      "permission_mode": "<string>",
      "max_iteration_per_run": 1,
      "mcp_servers": {
        "fetch": {
          "args": [
            "mcp-server-fetch"
          ],
          "command": "uvx"
        }
      },
      "profile_store_dir": "<string>",
      "metadata": {}
    }
  ],
  "plugins": [
    {
      "source": "<string>",
      "ref": "<string>",
      "repo_path": "<string>"
    }
  ],
  "hook_config": {
    "pre_tool_use": [
      {
        "matcher": "*",
        "hooks": [
          {
            "command": "<string>",
            "type": "command",
            "timeout": 60,
            "async": false
          }
        ]
      }
    ],
    "post_tool_use": [
      {
        "matcher": "*",
        "hooks": [
          {
            "command": "<string>",
            "type": "command",
            "timeout": 60,
            "async": false
          }
        ]
      }
    ],
    "user_prompt_submit": [
      {
        "matcher": "*",
        "hooks": [
          {
            "command": "<string>",
            "type": "command",
            "timeout": 60,
            "async": false
          }
        ]
      }
    ],
    "session_start": [
      {
        "matcher": "*",
        "hooks": [
          {
            "command": "<string>",
            "type": "command",
            "timeout": 60,
            "async": false
          }
        ]
      }
    ],
    "session_end": [
      {
        "matcher": "*",
        "hooks": [
          {
            "command": "<string>",
            "type": "command",
            "timeout": 60,
            "async": false
          }
        ]
      }
    ],
    "stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "command": "<string>",
            "type": "command",
            "timeout": 60,
            "async": false
          }
        ]
      }
    ]
  },
  "autotitle": true
}
EOF

200

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent": {
    "acp_command": [
      "<string>"
    ],
    "kind": "<string>",
    "llm": {
      "model": "claude-sonnet-4-20250514",
      "api_key": "<string>",
      "base_url": "<string>",
      "api_version": "<string>",
      "aws_access_key_id": "<string>",
      "aws_secret_access_key": "<string>",
      "aws_region_name": "<string>",
      "openrouter_site_url": "https://docs.all-hands.dev/",
      "openrouter_app_name": "OpenHands",
      "num_retries": 5,
      "retry_multiplier": 8,
      "retry_min_wait": 8,
      "retry_max_wait": 64,
      "timeout": 300,
      "max_message_chars": 30000,
      "temperature": 1,
      "top_p": 0.5,
      "top_k": 1,
      "max_input_tokens": 2,
      "max_output_tokens": 2,
      "model_canonical_name": "<string>",
      "extra_headers": {},
      "input_cost_per_token": 1,
      "output_cost_per_token": 1,
      "ollama_base_url": "<string>",
      "stream": false,
      "drop_params": true,
      "modify_params": true,
      "disable_vision": true,
      "disable_stop_word": false,
      "caching_prompt": true,
      "log_completions": false,
      "log_completions_folder": "logs/completions",
      "custom_tokenizer": "<string>",
      "native_tool_calling": true,
      "force_string_serializer": true,
      "reasoning_effort": "high",
      "reasoning_summary": "auto",
      "enable_encrypted_reasoning": true,
      "prompt_cache_retention": "24h",
      "extended_thinking_budget": 200000,
      "seed": 123,
      "safety_settings": [
        {}
      ],
      "usage_id": "default",
      "litellm_extra_body": {}
    },
    "tools": [
      {
        "name": "<string>",
        "params": {}
      }
    ],
    "mcp_config": {},
    "filter_tools_regex": "^(?!repomix)(.*)|^repomix.*pack_codebase.*$",
    "include_default_tools": [
      "<string>"
    ],
    "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!'",
      "user_message_prefix": "The first character of your response should be 'I'"
    },
    "system_prompt_filename": "system_prompt.j2",
    "security_policy_filename": "security_policy.j2",
    "system_prompt_kwargs": {},
    "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/anthropic/claude-sonnet-4-5-20250929"
      },
      "max_size": 80
    },
    "critic": {
      "kind": "AgentFinishedCritic"
    },
    "acp_args": [
      "<string>"
    ],
    "acp_env": {},
    "acp_session_mode": "<string>",
    "acp_prompt_timeout": 1800,
    "acp_model": "<string>"
  },
  "workspace": {
    "working_dir": "<string>",
    "kind": "<string>"
  },
  "persistence_dir": "workspace/conversations",
  "max_iterations": 500,
  "stuck_detection": true,
  "execution_status": "idle",
  "confirmation_policy": {
    "kind": "NeverConfirm"
  },
  "security_analyzer": {
    "kind": "<string>",
    "history_limit": 20,
    "max_message_chars": 30000,
    "timeout": 30,
    "low_threshold": 0.3,
    "medium_threshold": 0.7,
    "api_url": "https://api.grayswan.ai/cygnal/monitor",
    "api_key": "<string>",
    "policy_id": "<string>"
  },
  "activated_knowledge_skills": [
    "<string>"
  ],
  "blocked_actions": {},
  "blocked_messages": {},
  "last_user_message_id": "<string>",
  "stats": {},
  "secret_registry": {
    "secret_sources": {}
  },
  "agent_state": {},
  "hook_config": {
    "pre_tool_use": [
      {
        "matcher": "*",
        "hooks": [
          {
            "command": "<string>",
            "type": "command",
            "timeout": 60,
            "async": false
          }
        ]
      }
    ],
    "post_tool_use": [
      {
        "matcher": "*",
        "hooks": [
          {
            "command": "<string>",
            "type": "command",
            "timeout": 60,
            "async": false
          }
        ]
      }
    ],
    "user_prompt_submit": [
      {
        "matcher": "*",
        "hooks": [
          {
            "command": "<string>",
            "type": "command",
            "timeout": 60,
            "async": false
          }
        ]
      }
    ],
    "session_start": [
      {
        "matcher": "*",
        "hooks": [
          {
            "command": "<string>",
            "type": "command",
            "timeout": 60,
            "async": false
          }
        ]
      }
    ],
    "session_end": [
      {
        "matcher": "*",
        "hooks": [
          {
            "command": "<string>",
            "type": "command",
            "timeout": 60,
            "async": false
          }
        ]
      }
    ],
    "stop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "command": "<string>",
            "type": "command",
            "timeout": 60,
            "async": false
          }
        ]
      }
    ]
  },
  "title": "<string>",
  "metrics": {
    "model_name": "default",
    "accumulated_cost": 0,
    "max_budget_per_task": 123,
    "accumulated_token_usage": {
      "model": "",
      "prompt_tokens": 0,
      "completion_tokens": 0,
      "cache_read_tokens": 0,
      "cache_write_tokens": 0,
      "reasoning_tokens": 0,
      "context_window": 0,
      "per_turn_token": 0,
      "response_id": ""
    }
  },
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

Authorizations

X-Session-API-Key · string · header · required

Body

application/json

Payload to create a new conversation.

Contains an Agent configuration along with conversation-specific options.

agent · ACPAgent · object · required

Agent that delegates to an ACP-compatible subprocess server.

ACPAgent

Agent

Show child attributes

workspace · LocalWorkspace · object · required

Working directory for agent operations and tool execution

Show child attributes

conversation_id · string<uuid> | null

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

confirmation_policy · AlwaysConfirm · object

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

AlwaysConfirm

ConfirmRisky

NeverConfirm

Show child attributes

initial_message · SendMessageRequest · object

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

stuck_detection · boolean · default: true

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

secrets · Secrets · object

Secrets available in the conversation

Show child attributes

tool_module_qualnames · Tool Module Qualnames · object

Mapping of tool names to their module qualnames from the client's registry. These modules will be dynamically imported on the server to register the tools for this conversation.

Show child attributes

agent_definitions · AgentDefinition · object[]

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

Show child attributes

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

hook_config · HookConfig · object

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

autotitle · boolean · default: true

If true, automatically generate a title for the conversation from the first user message using the conversation's LLM.

Response

200

application/json

Successful Response

Information about a conversation running locally without a Runtime sandbox.

id · string<uuid> · required

Unique conversation ID

agent · ACPAgent · object · required

The agent running in the conversation. This is persisted to allow resuming conversations and check agent configuration to handle e.g., tool changes, LLM changes, etc.

ACPAgent

Agent

Show child attributes

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

persistence_dir · string | null · default: workspace/conversations

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

max_iterations · integer · default: 500

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

stuck_detection · boolean · default: true

Whether to enable stuck detection for the agent.

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

confirmation_policy · AlwaysConfirm · object

AlwaysConfirm

ConfirmRisky

NeverConfirm

Show child attributes

security_analyzer · GraySwanAnalyzer · object

Optional security analyzer to evaluate action risks.

GraySwanAnalyzer

LLMSecurityAnalyzer

Show child attributes

activated_knowledge_skills · string[]

List of activated knowledge skills name

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

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).

stats · object

Conversation statistics for tracking LLM metrics

secret_registry · SecretRegistry · object

Registry for handling secrets and sensitive data

Show child attributes

agent_state · Agent State · object

Dictionary for agent-specific runtime state that persists across iterations. Agents can store feature-specific state using string keys. To trigger autosave, always reassign: state.agent_state = {**state.agent_state, key: value}. See https://docs.openhands.dev/sdk/guides/convo-persistence#how-state-persistence-works

hook_config · HookConfig · object

Hook configuration for this conversation. Includes definitions for PreToolUse, PostToolUse, UserPromptSubmit, SessionStart, SessionEnd, and Stop hooks. When set, these hooks are executed at the appropriate points during conversation execution.

Show child attributes

title · string | null

User-defined title for the conversation

metrics · MetricsSnapshot · object

A snapshot of metrics at a point in time.

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

Show child attributes

created_at · string<date-time>

updated_at · string<date-time>