# API
### **Deploy**
Agents, when deployed (requires Builder license or higher, deployment is done with a 🚀 icon), can receive INPUT with POST requests, and provide output with GET requests.
### **Implementation**
To be able to work with Agent cloud deployment and GET/POST API, you need to have a Builder license or above. That gives you “Deploy agent to cloud” capability.
1. Create an agent with desired Inputs, Outputs, and processing nodes. Deploy it to the cloud by pressing a button.
2. Click on the main popup menu (bottom left), and select Settings.
3. Open the “App Token” tab and create an API key.
4. Open the “Agents” tab. It will list all agents you deployed to the cloud. From here, you can copy full POST and GET commands that you can use with your API caller of choice.
Please make sure to introduce a check on the GET command to check the status of the agent. If it says “running,” you need to wait.
### Example
1. Select POST request and input your `/execute` path provided by the POST curl request on the Settings → Agents page.
Example:\
`POST https://cloud.integrail.ai/api/your-agent-path/execute`
2. Copy your API key. In the httpie.io/app, input the key into the “Auth” tab with the “Bearer token” authentication type.
1. 
3. Input the body from the POST request into the “Body” tab as text.
4. Click “SEND”. It should return the status and execution ID.
Example Response:
```
{
"status": "ok",
"executionId": "1fe040db-916a-4f1b-a59c-194ba4995ed7"
}
```
5. Now run a GET request to the `/status` endpoint. Substitute `{execution-id}` with the actual ID from the execution response.
Example:\
`.../agent/{execution-id}/status`
Check the status. If the status is “finished,” you will see the outputs below. If the status is “running,” repeat the GET request.
### Uploading local files as Inputs via Multipart execution
You can upload files directly from your local disk for processing by agents using multipart execution. This is done by sending a **multipart POST** request instead of a standard **POST** request.
### How to use Multipart Execution
Instead of sending your request to the standard `/execute` endpoint, send it to `/execute/multipart`.
**Example:**
If your standard `/execute` URL is:
```url
https://cloud.integrail.ai/api/yA7Pnm2sSW2uTjnTh/agent/m6hfnCu9C9hz6t4AA/execute
```
Then for multipart execution, send your request to:
```url
https://cloud.integrail.ai/api/yA7Pnm2sSW2uTjnTh/agent/m6hfnCu9C9hz6t4AA/execute/multipart
```
### Formatting your request
Use forms to upload inputs:
* **String** inputs should be included in a payload form.
* **File** inputs should be in separate forms, where the form name matches the input name.
**Examples** are provided for an Agent with a ***userPrompt*** (string input) and ***doc*** (file input)
### Example using HTTP Web Client Payload and file forms:
Note that the file name should be equal to the file's input name in Agen Inputs.
```json
{
"inputs": {
"userPrompt": "What is the first word in this document?"
},
"stream": true
}
```
### **Example Using cURL (Command Line)**
```bash
.\curl.exe --location 'https://cloud.integrail.ai/api/yA7Pnm2sSW2uTjnTh/agent/m6hfnCu9C9hz6t4AA/execute/multipart' --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJHY2BvdW30SwQiOiJ5qTWQbm0yc1NXMnVUam5UaCIsImlhdCI6MTczNjY4MjcxOX0.kchROzhlW4HiK7n65urRUXw0kLMtbyS2YZa_AIezQe0' --form 'doc="@.\Questionnaire.pdf"' --form 'payload={\"inputs\":{\"userPrompt\": \"describe this document\"},\"stream\":true}'
```
#### Notes:
* **Escaping Characters:** In command-line environments, double quotes (`"`) must be **escaped** (e.g., with `\` on Windows).
* **File Paths:** In the example above, `Questionnaire.pdf` is in the same folder as `curl.exe, that's why it is passed as` 'doc="@.\Questionnaire.pdf"'. You can also use **absolute paths**.
