> For the complete documentation index, see [llms.txt](https://docs.tailent.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tailent.com/getting-started/tailent-gateway-agent/tap-gateway-agent-api-references/start-session-bot.md).

# Start Session Bot

```sh
[POST] https://tap.gateway:port/StartRobot
```

## Request headers

Content-Type: multipart/form-data'

## Request body

All parameters for this request are passed via multipart form-data. The following keys are expected:

* **username -** the Windows username that will be used to create the session
* **password -** the Windows user password that will be used to create the session
* **token -** this is the token that is configured in the TGA (within appsettings.json); if this does not match with provided token, the response will feature a 403 Forbidden code.
* **botPath** - the absolute path to the target automation. This needs to be a solution file (.tap) 
* **ip** - the ip address of the session creation host. This is usually set to **127.0.0.1** or whatever the terminal services listener is configured to.
* **port -** the default value is **3389**, which is the default RDP protocol port. If terminal services are listening on a diferent port, this needs to be changed.
* **domain** - the domain name, if the server is part of one. Otherwise, this value can be left empty.
* **colorDepth -** default value is **32**, representing the color depth for the Windows session.
* **desktopHeight -** the height in pixels for the resolution of the Windows session.
* **desktopWidth -** the width in pixels for the resolution of the Windows session.<br>

Besides the mandatory parameters required above, you can specify an unlimited number of additional parameters which will be passed to the bot runtime once triggered.

* data1=some\_value
* data2=some\_other\_value
* file1='@C:\file1.pdf'
* file2='@C:\file2.txt'
* ...

## Returns

The TGA should reply with a code **200** and aditional runtime information as JSON:

```json
{
	"response": {
		"message": "Robot C:\\Tailent\\Test\\Test.tap started",
		"messageType": 6,
		"metadata": ["7876"]
	},
	"guid": "2777f2d5-dbf1-41a0-ad1a-b2c9b9388baf",
	"accessTokenSet": true,
	"accessToken": "AiUAOWUjyvZSRkabP9208JguJ4NUYXktMAteQVZZDoHfRJ4FTk46CrYuBZmiK1fWkVCn39BGYItxtHoYBTKlfO8bLE8avBENhOaQ9kIk6MuEgpA3HnlT5PKRhAwCQM4U"
}
```

This response features important information that can be used in other REST requests.&#x20;

The first section **"response"** offers information about what automation was started:

* **message** is the response from the TGA component
* **messageType** signals the outcome of the requested operation (6 is the code for successful remote start)
* **metadata** is an array with additional information regarding to the request; by default this contains the **PID** of the TAP.Runtime process (automation)

**guid** - is the unique identifier assigned at runtime to the bot instance and can be used to uniquely identify this bot.

**accessTokenSet** - can be true/false depending on wether the OTP (or access token generated was set correctly).

**accessToken** - is a OTP (one time password) generated only once for this particular bot instance. This can used (along with the **guid**) to interogate on the status or updates of this particular bot instance. Please note that this access token is not saved and cannot be regenerated if lost.

## Example curl request

```sh
curl --request POST \
  --url https://tap.gateway:port/StartRobot \
  --header 'Content-Type: multipart/form-data' \
  --form username=TestUser \
  --form 'password=Password' \
  --form token=12345678 \
  --form 'botPath=C:\Tailent\Test\Test.tap' \
  --form ip=127.0.0.1 \
  --form port=3389 \
  --form domain= \
  --form colorDepth=32 \
  --form desktopHeight=768 \
  --form desktopWidth=1024 \
  --form data1=some_value \
  --form data2=some_other_value \
  --form 'file1=@C:\file1.pdf'
  --form 'file2=@C:\file2.txt'
```