Skip to main content
POST
/
api
/
v1
/
app-conversations
Start a Conversation
curl --request POST \
  --url https://app.all-hands.dev/api/v1/app-conversations \
  --header 'Content-Type: application/json' \
  --header 'X-Access-Token: <api-key>' \
  --data '
{
  "sandbox_id": "<string>",
  "conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "initial_message": {
    "role": "user",
    "content": [
      {
        "text": "<string>",
        "cache_prompt": false,
        "type": "text"
      }
    ],
    "run": false
  },
  "system_message_suffix": "<string>",
  "processors": [
    {
      "github_view_data": {},
      "should_request_summary": true,
      "inline_pr_comment": false,
      "kind": "<string>"
    }
  ],
  "llm_model": "<string>",
  "selected_repository": "<string>",
  "selected_branch": "<string>",
  "git_provider": "github",
  "suggested_task": {
    "git_provider": "github",
    "task_type": "MERGE_CONFLICTS",
    "repo": "<string>",
    "issue_number": 123,
    "title": "<string>"
  },
  "title": "<string>",
  "trigger": "resolver",
  "pr_number": [
    123
  ],
  "parent_conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent_type": "default",
  "public": true,
  "plugins": [
    {
      "source": "<string>",
      "ref": "<string>",
      "repo_path": "<string>",
      "parameters": {}
    }
  ]
}
'
{
  "created_by_user_id": "<string>",
  "request": {
    "sandbox_id": "<string>",
    "conversation_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "initial_message": {
      "role": "user",
      "content": [
        {
          "text": "<string>",
          "cache_prompt": false,
          "type": "text"
        }
      ],
      "run": false
    },
    "system_message_suffix": "<string>",
    "processors": [
      {
        "kind": "<string>",
        "github_view_data": {},
        "should_request_summary": true,
        "inline_pr_comment": false
      }
    ],
    "llm_model": "<string>",
    "selected_repository": "<string>",
    "selected_branch": "<string>",
    "git_provider": "github",
    "suggested_task": {
      "git_provider": "github",
      "task_type": "MERGE_CONFLICTS",
      "repo": "<string>",
      "issue_number": 123,
      "title": "<string>"
    },
    "title": "<string>",
    "trigger": "resolver",
    "pr_number": [
      123
    ],
    "parent_conversation_id": "<string>",
    "agent_type": "default",
    "public": true,
    "plugins": [
      {
        "source": "<string>",
        "ref": "<string>",
        "repo_path": "<string>",
        "parameters": {}
      }
    ]
  },
  "id": "<string>",
  "status": "WORKING",
  "detail": "<string>",
  "app_conversation_id": "<string>",
  "sandbox_id": "<string>",
  "agent_server_url": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

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

Start conversation request object.

Although a user can go directly to the sandbox and start conversations, they would need to manually supply required startup parameters such as LLM key. Starting from the app server copies these from the user info.

​
sandbox_id
string | null
​
conversation_id
string<uuid> | null
​
initial_message
SendMessageRequest · object

Payload to send a message to the agent.

This is a simplified version of openhands.sdk.Message.

​
system_message_suffix
string | null
​
processors
(GithubV1CallbackProcessor · object | SlackV1CallbackProcessor · object | LoggingCallbackProcessor · object | SetTitleCallbackProcessor · object)[] | null

Callback processor for GitHub V1 integrations.

​
llm_model
string | null
​
selected_repository
string | null
​
selected_branch
string | null
​
git_provider
enum<string> | null
Available options:
github,
gitlab,
bitbucket,
bitbucket_data_center,
forgejo,
azure_devops,
enterprise_sso
​
suggested_task
SuggestedTask · object
​
title
string | null
​
trigger
enum<string> | null
Available options:
resolver,
gui,
suggested_task,
openhands_api,
slack,
microagent_management,
jira,
jira_dc,
linear,
bitbucket,
automation
​
pr_number
integer[]
​
parent_conversation_id
string<uuid> | null
​
agent_type
enum<string>
default:default

Agent type for conversation.

Available options:
default,
plan
​
public
boolean | null
​
plugins
PluginSpec · object[] | null

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

Response

Successful Response

Object describing the start process for an app conversation.

Because starting an app conversation can be slow (And can involve starting a sandbox), we kick off a background task for it. Once the conversation is started, the app_conversation_id is populated.

​
created_by_user_id
string | null
required
​
request
AppConversationStartRequest · object
required

Start conversation request object.

Although a user can go directly to the sandbox and start conversations, they would need to manually supply required startup parameters such as LLM key. Starting from the app server copies these from the user info.

​
id
string
​
status
enum<string>
default:WORKING
Available options:
WORKING,
WAITING_FOR_SANDBOX,
PREPARING_REPOSITORY,
RUNNING_SETUP_SCRIPT,
SETTING_UP_GIT_HOOKS,
SETTING_UP_SKILLS,
STARTING_CONVERSATION,
READY,
ERROR
​
detail
string | null
​
app_conversation_id
string | null

The id of the app_conversation, if READY

​
sandbox_id
string | null

The id of the sandbox, if READY

​
agent_server_url
string | null

The agent server url, if READY

​
created_at
string<date-time>
​
updated_at
string<date-time>