# Droid Execute API

Start a headless Droid turn in one call: on a fresh computer from an Environment, an existing computer, or an existing session.

## Execute a Droid turn

`POST /api/v0/droid/execute`

Starts a headless Droid turn and returns once it is accepted. Target an `environment` to provision a fresh computer from its active build and start a new session, a `computer` you own to start a new session on it, or a `session` you own to send a follow-up message. `model` and `reasoningEffort` apply only to new sessions. The session status can still show the previous turn as `idle` right after this call, so do not treat the first `idle` as completion. The accepted turn is complete when `GET /api/v0/sessions/{sessionId}` reports `idle` and `GET /api/v0/sessions/{sessionId}/messages` contains an assistant message after the user message whose `id` is the returned `messageId`.

```bash
curl -X POST 'https://api.factory.ai/api/v0/droid/execute' \
  -H 'Authorization: Bearer $FACTORY_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ ... }'
```

**Request body** (optional)

```json
{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "minLength": 1
    },
    "target": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "environment"
              ]
            },
            "environmentId": {
              "type": "string",
              "minLength": 1
            },
            "templateId": {
              "not": {}
            },
            "executionTemplateId": {
              "not": {}
            },
            "computerId": {
              "not": {}
            },
            "sourceComputerId": {
              "not": {}
            },
            "sessionId": {
              "not": {}
            }
          },
          "required": [
            "kind",
            "environmentId"
          ],
          "additionalProperties": true
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "template"
              ]
            },
            "templateId": {
              "type": "string",
              "minLength": 1
            },
            "environmentId": {
              "not": {}
            },
            "executionTemplateId": {
              "not": {}
            },
            "computerId": {
              "not": {}
            },
            "sourceComputerId": {
              "not": {}
            },
            "sessionId": {
              "not": {}
            }
          },
          "required": [
            "kind",
            "templateId"
          ],
          "additionalProperties": true
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "computer"
              ]
            },
            "computerId": {
              "type": "string",
              "minLength": 1
            },
            "environmentId": {
              "not": {}
            },
            "templateId": {
              "not": {}
            },
            "executionTemplateId": {
              "not": {}
            },
            "sourceComputerId": {
              "not": {}
            },
            "sessionId": {
              "not": {}
            }
          },
          "required": [
            "kind",
            "computerId"
          ],
          "additionalProperties": true
        },
        {
          "type": "object",
          "properties": {
            "kind": {
              "type": "string",
              "enum": [
                "session"
              ]
            },
            "sessionId": {
              "type": "string",
              "minLength": 1
            },
            "environmentId": {
              "not": {}
            },
            "templateId": {
              "not": {}
            },
            "executionTemplateId": {
              "not": {}
            },
            "computerId": {
              "not": {}
            },
            "sourceComputerId": {
              "not": {}
            }
          },
          "required": [
            "kind",
            "sessionId"
          ],
          "additionalProperties": true
        }
      ]
    },
    "model": {
      "type": "string",
      "minLength": 1
    },
    "reasoningEffort": {
      "type": "string",
      "enum": [
        "none",
        "dynamic",
        "off",
        "minimal",
        "low",
        "medium",
        "high",
        "xhigh",
        "max"
      ]
    }
  },
  "required": [
    "prompt",
    "target"
  ],
  "additionalProperties": false
}
```

**Response:** `202` - Response for status 202

```json
{
  "type": "object",
  "properties": {
    "sessionId": {
      "type": "string",
      "minLength": 1
    },
    "computerId": {
      "type": "string",
      "minLength": 1
    },
    "messageId": {
      "type": "string",
      "minLength": 1
    }
  },
  "required": [
    "sessionId",
    "computerId",
    "messageId"
  ],
  "additionalProperties": false
}
```

**Response:** `400` - Response for status 400

```json
{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "status": {
      "type": "number",
      "description": "HTTP status code"
    },
    "title": {
      "type": "string",
      "description": "HTTP status title"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {},
      "description": "Additional error metadata"
    }
  },
  "required": [
    "detail",
    "status",
    "title"
  ],
  "additionalProperties": false
}
```

**Response:** `401` - Response for status 401

```json
{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "status": {
      "type": "number",
      "description": "HTTP status code"
    },
    "title": {
      "type": "string",
      "description": "HTTP status title"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {},
      "description": "Additional error metadata"
    }
  },
  "required": [
    "detail",
    "status",
    "title"
  ],
  "additionalProperties": false
}
```

**Response:** `402` - Response for status 402

```json
{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "status": {
      "type": "number",
      "description": "HTTP status code"
    },
    "title": {
      "type": "string",
      "description": "HTTP status title"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {},
      "description": "Additional error metadata"
    }
  },
  "required": [
    "detail",
    "status",
    "title"
  ],
  "additionalProperties": false
}
```

**Response:** `403` - Response for status 403

```json
{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "status": {
      "type": "number",
      "description": "HTTP status code"
    },
    "title": {
      "type": "string",
      "description": "HTTP status title"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {},
      "description": "Additional error metadata"
    }
  },
  "required": [
    "detail",
    "status",
    "title"
  ],
  "additionalProperties": false
}
```

**Response:** `404` - Response for status 404

```json
{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "status": {
      "type": "number",
      "description": "HTTP status code"
    },
    "title": {
      "type": "string",
      "description": "HTTP status title"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {},
      "description": "Additional error metadata"
    }
  },
  "required": [
    "detail",
    "status",
    "title"
  ],
  "additionalProperties": false
}
```

**Response:** `409` - Response for status 409

```json
{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "status": {
      "type": "number",
      "description": "HTTP status code"
    },
    "title": {
      "type": "string",
      "description": "HTTP status title"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {},
      "description": "Additional error metadata"
    }
  },
  "required": [
    "detail",
    "status",
    "title"
  ],
  "additionalProperties": false
}
```

**Response:** `413` - Response for status 413

```json
{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "status": {
      "type": "number",
      "description": "HTTP status code"
    },
    "title": {
      "type": "string",
      "description": "HTTP status title"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {},
      "description": "Additional error metadata"
    }
  },
  "required": [
    "detail",
    "status",
    "title"
  ],
  "additionalProperties": false
}
```

**Response:** `429` - Response for status 429

```json
{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "status": {
      "type": "number",
      "description": "HTTP status code"
    },
    "title": {
      "type": "string",
      "description": "HTTP status title"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {},
      "description": "Additional error metadata"
    }
  },
  "required": [
    "detail",
    "status",
    "title"
  ],
  "additionalProperties": false
}
```

**Response:** `500` - Response for status 500

```json
{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "status": {
      "type": "number",
      "description": "HTTP status code"
    },
    "title": {
      "type": "string",
      "description": "HTTP status title"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {},
      "description": "Additional error metadata"
    }
  },
  "required": [
    "detail",
    "status",
    "title"
  ],
  "additionalProperties": false
}
```

**Response:** `503` - Response for status 503

```json
{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "status": {
      "type": "number",
      "description": "HTTP status code"
    },
    "title": {
      "type": "string",
      "description": "HTTP status title"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {},
      "description": "Additional error metadata"
    }
  },
  "required": [
    "detail",
    "status",
    "title"
  ],
  "additionalProperties": false
}
```

**Response:** `504` - Response for status 504

```json
{
  "type": "object",
  "properties": {
    "detail": {
      "type": "string",
      "description": "Human-readable error message"
    },
    "status": {
      "type": "number",
      "description": "HTTP status code"
    },
    "title": {
      "type": "string",
      "description": "HTTP status title"
    },
    "metadata": {
      "type": "object",
      "additionalProperties": {},
      "description": "Additional error metadata"
    }
  },
  "required": [
    "detail",
    "status",
    "title"
  ],
  "additionalProperties": false
}
```