API

Promptly provides a HTTP API that allows you to programmatically interact with the platform. This API can be used to integrate AI experiences into your existing applications or to build new applications on top of Promptly.

Promptly supports both streaming and non-streaming APIs for running apps. Streaming API allows you to stream output of the app in real-time. Non-streaming API allows you to run the app and get the output once the app is finished running. Below is the API endpoint for running apps:

info

Replace <app_uuid> with the UUID of the app you want to run. You can find the UUID of the app in the url of the app builder page.

POST /api/apps/<app_uuid>/run

Request body

Below is the format of request body for running apps:

{
  "input": {
    <INPUT_KEY_VALUE_JSON>
  },
  "stream": true
}

INPUT_KEY_VALUE_JSON is a JSON object with input keys and values. For example, if the app has two input fields file and question, the request body will look like:

{
  "input": {
    "file": "<file_value>",
    "question": "<question_value>"
  },
  "stream": true
}

stream is a boolean value that indicates whether to stream output of the app or not. If stream is set to true, the API will stream output of the app in real-time. If stream is set to false, the API will wait for the app to finish running and return the output once the app is finished running.

Response body

Below is the format of response body for running apps:

{
  "session": {
    "id": "<session_id_value>"
  },
  "output": {
    <OUTPUT_KEY_VALUE_JSON>
  },
}

Authentication

All API requests must be authenticated using a token. You can find the token in Settings page. This token must be passed in the Authorization header of the request with Token: prefix.

App Session

Depending on the processors used in an app, Promptly app can retain information between requests using sessions. For example, if you use Promptly / Text Chat or OpenAI / ChatGPT processors with history enabled, the app will retain the chat history between requests. This allows you to build apps that can remember information from previous requests. In order to use sessions from API, you will need to include session_id in the requests. You can find the session id in the response of the API request. Below is an example of how to use session_id in the API request:

POST /api/apps/<app_uuid>/run/<session_id>

Examples

Below are examples of how to use API to run apps.

Streaming API

Python

import requests

PROMPTLY_TOKEN = '<promptly_token>'
url = 'http://localhost:3000/api/apps/<app_uuid>/run'

payload = {
  "input": {
    "file": "<file_value>",
    "question": "<question_value>"
  },
  "stream": True,
}
headers = {
  "Content-Type": "application/json",
  "Authorization": "Token " + PROMPTLY_TOKEN,
}

response = requests.post(url, headers=headers, json=payload, stream=True)
for line in response.iter_lines():
  if line:
    print(line.decode('utf8'))

cURL

curl --location --request POST \
'http://localhost:3000/api/apps/<app_uuid>/run' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token <promptly_token>' \
--data-raw '{
  "input": {
    "file": "<file_value>",
    "question": "<question_value>"
  },
  "stream": true
}'

JavaScript

const axios = require("axios");

const url = "http://localhost:3000/api/apps/<app_uuid>/run";
const PROMPTLY_TOKEN = "<promptly_token>";
const payload = {
  input: {
    file: "<file_value>",
    question: "<question_value>",
  },
  stream: true,
};
const headers = {
  "Content-Type": "application/json",
  Authorization: "Token " + PROMPTLY_TOKEN,
};
axios
  .post(url, payload, { headers, responseType: "stream" })
  .then((response) => {
    response.data.on("data", (line) => {
      if (line) {
        console.log(line.toString("utf8"));
      }
    });
  })
  .catch((error) => {
    console.error(error);
  });

Blocking API

Python

import requests

PROMPTLY_TOKEN = '<promptly_token>'
url = 'http://localhost:3000/api/apps/<app_uuid>/run'

payload = {
  "input": {
    "file": "<file_value>",
    "question": "<question_value>"
  },
  "stream": False,
}
headers = {
  "Content-Type": "application/json",
  "Authorization": "Token " + PROMPTLY_TOKEN,
}

response = requests.request("POST", url, headers=headers, json=payload)

print(response.text.encode('utf8'))

cURL

curl --location --request POST \
'http://localhost:3000/api/apps/<app_uuid>/run' \
--header 'Content-Type: application/json' \
--header 'Authorization: Token <promptly_token>' \
--data-raw '{
  "input": {
    "file": "<file_value>",
    "question": "<question_value>"
  },
  "stream": false
}'

JavaScript

const axios = require("axios");

const url = "http://localhost:3000/api/apps/<app_uuid>/run";
const PROMPTLY_TOKEN = "<promptly_token>";
const payload = {
  input: {
    file: "<file_value>",
    question: "<question_value>",
  },
  stream: false,
};
const headers = {
  "Content-Type": "application/json",
  Authorization: "Token " + PROMPTLY_TOKEN,
};

axios.post(url, payload, { headers: headers }).then((response) => {
  console.log(response.data);
});