Skip to main content
POST
/
api
/
v1
/
webhooks
/
conversations
On Conversation Update
curl --request POST \
  --url https://app.all-hands.dev/api/v1/webhooks/conversations \
  --header 'Content-Type: application/json' \
  --header 'X-Access-Token: <api-key>' \
  --data @- <<EOF
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "workspace": {
    "working_dir": "<string>",
    "kind": "<string>"
  },
  "agent": {
    "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_session_token": "<string>",
      "aws_region_name": "<string>",
      "aws_profile_name": "<string>",
      "aws_role_name": "<string>",
      "aws_session_name": "<string>",
      "aws_bedrock_runtime_endpoint": "<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"
    },
    "tool_concurrency_limit": 1,
    "kind": "<string>"
  },
  "persistence_dir": "workspace/conversations",
  "max_iterations": 500,
  "stuck_detection": true,
  "execution_status": "idle",
  "confirmation_policy": {
    "kind": "NeverConfirm"
  },
  "security_analyzer": {
    "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>",
    "kind": "<string>"
  },
  "activated_knowledge_skills": [
    "<string>"
  ],
  "blocked_actions": {},
  "blocked_messages": {},
  "last_user_message_id": "<string>",
  "stats": {
    "usage_to_metrics": {}
  },
  "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",
  "tags": {}
}
EOF
{
  "success": true
}

Documentation Index

Fetch the complete documentation index at: https://allhandsai-add-v1-api-reference.mintlify.app/llms.txt

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

Authorizations

X-Access-Token
string
header
required

Body

application/json

Information about a conversation running locally without a Runtime sandbox.

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

agent
Agent · object
required

The legacy v1 agent configuration. This endpoint remains pinned to the standard Agent contract.

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
security_analyzer
GraySwanAnalyzer · object

Optional security analyzer to evaluate action risks.

activated_knowledge_skills
string[]

List of activated knowledge skills name

blocked_actions
Blocked Actions · object

Actions blocked by PreToolUse hooks, keyed by action ID

blocked_messages
Blocked Messages · object

Messages blocked by UserPromptSubmit hooks, keyed by message ID

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
ConversationStats · object

Conversation statistics for tracking LLM metrics

secret_registry
SecretRegistry · object

Registry for handling secrets and sensitive data

agent_state
Agent State · object

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

hook_config
HookConfig · object

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

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.

created_at
string<date-time>
updated_at
string<date-time>
tags
Tags · object

Key-value tags for the conversation. Keys must be lowercase alphanumeric. Values are arbitrary strings up to 256 characters.

Response

Successful Response

success
boolean
default:true