API

How to use GET/POST API requests with Integrail.

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:

https://cloud.integrail.ai/api/yA7Pnm2sSW2uTjnTh/agent/m6hfnCu9C9hz6t4AA/execute

Then for multipart execution, send your request to:

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.

{
  "inputs": {
    "userPrompt": "What is the first word in this document?"
  },
  "stream": true
}

Example Using cURL (Command Line)

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