Introduction

ScriptRun Al: Visual Al script builder

Create simple and complex Al scripts to integrate into your business project. Fast, reliable and without limitations.

What is a Project? A project is a container where you can organize and manage your Al scenarios and related data. You can manage access and collaboration by doing projects with your colleagues.

A Script in ScriptRun Al is a sequence of instructions for interacting with language models (such as OpenAl's GPT-4, o1-preview) and third-party services (such as for SEO keyword research) that you specify when you create a Script. Each Scenario consists of a given sequence of Messages, which are text requests to the language models via ARL.

The Scenario API allows you to create, manage, and execute predefined workflows, called Scenarios (scripts), and track their execution through ScenarioRuns. A Scenario is essentially a blueprint that defines a sequence of actions, messages, and conditions, guiding the flow of a conversation, process, or automation task. Scenarios are highly customizable and can be used for a wide range of applications, from chatbot dialogues to complex automation workflows. When you execute a Scenario, the system generates a ScenarioRun. This is an instance of the Scenario's execution, which tracks real-time interactions, stores the data generated, and logs the results. ScenarioRuns allow you to monitor every aspect of the process, including user inputs, variables, and any conditional logic that is applied during the run. Together, Scenarios and ScenarioRuns form a powerful framework for handling dynamic workflows, customer interactions, and automated tasks, all while providing complete tracking and flexibility to adapt based on real-time data. The API is designed to help you automate and optimize processes efficiently, making it a versatile tool for business automation and customer service operations.

Authentication

Working with API Keys

API keys are required for authentication when interacting with scriptRun's API. Each API request must include the API key in the request headers to ensure secure communication between the client and the backend.

To use an API key, include the following header in your requests:

X-API-Key: {api_key}

You can create an API key through the user interface as shown below, or by interacting with the available endpoints.

Steps to Create an API Key

1) Access your profile: Navigate to your profile by clicking on the user icon in the top right corner of the page, as shown in the screenshot below.

2) View Your API Keys: Once created, your API keys will be listed. You can manage (delete) them as needed.

3) Create an API Key: In the "API keys" section of your profile, click on the "Create API Key" button.

4) Copy your API Key:

Rate Limits

Each API key is associated with a user profile and can be configured with rate limits. These limits control how many requests the API key can make in a given time period.

Rate limits can be defined as follows:

• Default limits is such allow 60 requests per minute

To get permission to send requests through the API, you must request permission from your administrators. To get access and for more information, visit our Telegram channel or send an email to support@scriptrun.ai

Example Usage

You need to include this header in every query:
X-API-Key: <Your_API_Key>

# You can also use wget
curl -X GET https://scriptrun.ai/api/v1/projects/ \
  -H 'Accept: application/json' \
  -H 'X-Api-Key: <Your API Key>' 

import requests
headers = {
  'Accept': 'application/json',
  'x-api-key': '<Your API Key>'
}

r = requests.get('https://scriptrun.ai/api/v1/projects/', headers = headers)

print(r.json())

When making API requests using your API key, be sure to include the following header in every request:

Versioning

The URLs for the various resources use the following pattern:

https://scriptrun.ai/api/v{version}/{operation-specific component}

The components of the URL are: version - the API version. Currently there is only one version, "1", in operation operation-specific component - this identifies the actual operation you want to do. For example a list of projects. Thus the URL getting a list of the project for the authenticated user is https://scriptrun.ai/v1/projects/

Pagination

Example Responses
200 Response
{
  "items": [
    {
      "id": 1,
      "name": "Python Course",
      "total_spent": 0,
      "created_at": "2024-09-26T01:34:43.155232Z",
      "updated_at": "2024-09-26T01:34:43.155236Z",
    }
  ],
  "page": 1,
  "size": 1,
  "total": 1
}

Example Responses
200 Response
{
  "items": [
    {
      "id": 1,
      "name": "Python Course",
      "total_spent": 0,
      "created_at": "2024-09-26T01:34:43.155232Z",
      "updated_at": "2024-09-26T01:34:43.155236Z",
    }
  ],
  "page": 1,
  "size": 1,
  "total": 1
}

All GET endpoints which return an object list support cursor based pagination with pagination information inside a pagination object. Use parameter page and limit to configure pagination. Default limit is set to 10 but values up to 50 are permitted.

Errors

The ScriptRun API uses the following error codes:

Projects API

List of Projects

curl -X GET "https://scriptrun.ai/api/v1/projects/?page=1&size=10&name__icontains=test" \
  -H "X-Api-Key: <Your API Key>"

import requests

url = "https://scriptrun.ai/api/v1/projects/"
headers = {"X-Api-Key": "<Your API Key>"}
params = {"page": 1, "size": 10, "name__icontains": "test"}

response = requests.get(url, headers=headers, params=params)
print(response.json())

GET /api/v1/projects/

Summary: Retrieves a list of projects. Projects track expenses related to rendering prompts and may include various plans (e.g., JustmagicPlan) as well as webhook configurations.

Parameters:

Responses:

• 200 OK:
  • Content-Type: application/json
  • Schema:
    • page (integer) Required: Page of query.
    • size (integer) Optional: Number of results per call. Accepted values: 0 - 100. Default 10.
    • total (integer) Optional: Total objects in query.
    • items (array) Required: List of projects.

Create a Project

curl -X POST "https://scriptrun.ai/api/v1/projects/" \
  -H "X-Api-Key: <Your API Key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "New Project", "webhook_url": "https://example.com/webhook/"}'

import requests

url = "https://scriptrun.ai/api/v1/projects/"
headers = {
    "X-Api-Key": "<Your API Key>",
    "Content-Type": "application/json"
}
data = {
    "name": "New Project",
    "webhook_url": "https://example.com/webhook/"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

POST /api/v1/projects/

Summary: Creates a new project. A project tracks expenses for prompt rendering and includes webhook settings and various plans.

Request Body:

• Content-Type: application/json
• Schema:
  • id (integer) Required: Unique identifier for the project.
  • name (string) Required: Name of the project.
  • total_spent (number) Optional: Total amount spent on the project. # delete total
  • webhook_url (string) Optional: URL for project webhook notifications.
  • is_webhook_enabled (boolean) Optional: Whether the webhook is enabled.

Responses:

• 201 Created:
  • Content-Type: application/json
  • Schema:
    • id (integer) Required: ID of the newly created project.
    • name (string) Required: Name of the project.
    • total_spent (number) Optional: Total spent on the project.
    • created_at (string) Required: Timestamp when the project was created.
    • updated_at (string) Required: Timestamp when the project was last updated.
    • webhook_url (string) Optional: Webhook URL for the project.
    • is_webhook_enabled (boolean) Optional: Whether the webhook is enabled.

Retrieve a Project

curl -X GET "https://scriptrun.ai/api/v1/projects/123/" \
  -H "X-Api-Key: <Your API Key>"

import requests

url = "https://scriptrun.ai/api/v1/projects/123/"
headers = {"X-Api-Key": "<Your API Key>"}

response = requests.get(url, headers=headers)
print(response.json())

GET /api/v1/projects/{id}/

Summary: Retrieves the details of a specific project, including its name, plan, and webhook configuration.

Parameters:

Responses:

• 200 OK:
  • Content-Type: application/json
  • Schema:
    • id (integer) Required: Unique ID of the project.
    • name (string) Required: Name of the project.
    • total_spent (number) Optional: Total spent on the project.
    • created_at (string) Required: Timestamp when the project was created.
    • updated_at (string) Required: Timestamp when the project was last updated.
    • webhook_url (string) Optional: Webhook URL for notifications.
    • is_webhook_enabled (boolean) Optional: Whether the webhook is enabled.

Update a Project

curl -X PATCH "https://scriptrun.ai/api/v1/projects/123/" \
  -H "X-Api-Key: <Your API Key>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Updated Project", "webhook_url": "https://example.com", "is_webhook_enabled": true}'

import requests

url = "https://scriptrun.ai/api/v1/projects/123/"
headers = {
    "X-Api-Key": "<Your API Key>",
    "Content-Type": "application/json"
}
data = {
    "name": "Updated Project",
    "is_webhook_enabled": True,
    "webhook_url": "https://example.com"
}

response = requests.patch(url, headers=headers, json=data)
print(response.json())

PATCH /api/v1/projects/{id}/

Summary: Updates the details of a specific project. Only certain fields such as name, total_spent, webhook_url, or is_webhook_enabled can be updated.

Parameters:

Request Body:

• Content-Type: application/json
• Schema:
  • name (string) Optional: New name for the project.
  • webhook_url (string) Optional: Updated webhook URL.
  • is_webhook_enabled (boolean) Optional: Whether the webhook is enabled.

Responses:

• 200 OK:
  • Content-Type: application/json
  • Schema:
    • id (integer) Required: ID of the updated project.
    • name (string) Required: Name of the project.
    • webhook_url (string) Optional: Updated webhook URL.
    • is_webhook_enabled (boolean) Optional: Whether the webhook is enabled.

Delete a Project

curl -X DELETE "https://scriptrun.ai/api/v1/projects/123/" \
  -H "X-Api-Key: <Your API Key>"

import requests

url = "https://scriptrun.ai/api/v1/projects/123/"
headers = {"X-Api-Key": "<Your API Key>"}

response = requests.delete(url, headers=headers)
print(response.status_code)  # 204 indicates success

DELETE /api/v1/projects/{id}/

Summary: Deletes a specific project by its ID.

Parameters:

Responses:

• 204 No Content: No response body.

Scenario and ScenarioRun Relations

Scenario

A Scenario is essentially a blueprint or script that defines a sequence of actions, messages, and workflows. It can be considered a container that holds the logic for a certain process or interaction.

Key Concepts:

1. Structure: A scenario includes messages, variables, prompts, and conditions. It defines a flow, which can be a conversation, automation task, or other processes.
2. Messages: Messages are individual units within a scenario. Each message might represent a question, instruction, or data transmission point. Messages can have attached prompts (e.g., input fields, options for users to select), and the logic around which message is sent can depend on conditions.
3. Variables: Scenarios use variables to store data (e.g., user responses). These variables can be dynamically modified as the scenario is executed, allowing for real-time interaction. For example, you could store a user’s response and use it later in the process.
4. Prompts: These are user interaction points, like forms or choices. They gather input and conditionally affect how the scenario proceeds. For example, a prompt could ask for a user’s email, and based on the input, different messages could be sent.
5. Conditions: Scenarios can have conditions that determine the flow. For instance, if a certain variable has a specific value, a different message might be sent, or the flow could branch off into different paths.

Creation and Usage:

• Create a Scenario: You can create a scenario by defining its name, attaching a project (i.e., the workspace or context), messages, variables, and other attributes like fees for running it.
• Use Cases: Scenarios are versatile. You might use them for chatbot dialogues, automation workflows, customer support scripts, or other repeatable processes that need conditional logic.

ScenarioRun

A ScenarioRun is an execution of a scenario. While a scenario is a template or plan, the ScenarioRun is the actual instance that carries out the process.

Key Concepts:

1. Execution: When you want to run a scenario, a ScenarioRun instance is created. This instance tracks everything: when it started, how long it ran, the messages that were processed, and any errors that occurred during execution.
2. Cloning of Data: When a scenario is executed, a ScenarioRun will often copy or clone the variables, messages, and logic from the original scenario. This ensures that any data generated during the run is tied to that specific instance, and the original scenario remains unchanged.
3. Dynamic Updates: During a ScenarioRun, you can update the messages, variables, or prompts dynamically. This allows flexibility based on user input or other real-time data. For example, if a user inputs certain information, you can update the variable to reflect that and change how the scenario proceeds based on the new data.
4. Tracking: The ScenarioRun tracks every interaction and result. This includes:
   • Tokens: If using external providers like LLMs (large language models), it tracks the tokens consumed.
   • Cost: It calculates the cost of the run, especially if you’re using external APIs with associated costs.
   • Final Result: After the ScenarioRun completes, a final result (like a summary or final output) is stored.
5. Webhook Integration: You can provide a webhook_url when running a scenario. Once the ScenarioRun is completed, the system can send the result or status to this webhook, notifying external systems of the result.

Execution Flow:

1. Initiating a Run: You start a ScenarioRun either from a specific scenario or from an existing run (in case you want to repeat or adjust the previous execution).
2. Handling Messages: As the run progresses, messages are processed in sequence, and any prompts within them are executed, gathering user input if needed. Conditions can also alter the flow during the run.
3. Variables and Results: Variables are updated dynamically based on user input or external data. If any error occurs, it’s logged, and the status of the run is updated accordingly.
4. Finalization: When the ScenarioRun finishes, all results are stored, including any messages, final outputs, or errors. Optionally, the system can send the results to a provided webhook.

Use Cases:

• Customer Interactions: You might create a scenario for handling a specific customer interaction, like resetting a password or troubleshooting an issue. When a customer requests help, a ScenarioRun would execute this flow.
• Automations: You could use a scenario to automate workflows, such as onboarding a new user or conducting a survey, and the ScenarioRun would handle individual instances of these processes.
• Testing: Before deploying a scenario, you could run test ScenarioRuns to ensure everything behaves as expected.

Relationship Between Scenario and ScenarioRun

• Scenario: The blueprint or logic of the process, containing messages, prompts, variables, and conditions.
• ScenarioRun: The execution instance that follows the logic and tracks real-time updates and results.

In simpler terms, you can think of a Scenario as a plan for a journey, and the ScenarioRun as someone actually taking the journey and recording what happens along the way.

Example:

• Scenario: “Customer Support Chat”

  • Messages: “Welcome”, “How can we assist you?”
  • Variables: Customer Issue
  • Conditions: If the customer says “password reset”, then offer password assistance.

• ScenarioRun: An instance of that customer support chat, where one customer asks for help with their password. The run records what messages were sent, the customer’s input, and the final result of the conversation.

Scenario API

The Scenario API allows you to manage and interact with scripts and their runs (ScenarioRun). A scenario is a blueprint or script that defines a sequence of actions, messages, and workflows, while the ScenarioRun tracks the actual execution of the scenario and the results. This API provides endpoints to create, retrieve, update, and delete scenarios, as well as execute them via a ScenarioRun.

Retrieve Scenarios

import requests

url = "https://scriptrun.ai/api/v1/scenarios/"
headers = {"X-Api-Key": "<Your API Key>"}
params = {"name__icontains": "example", "project": 1, "page": 2}

response = requests.get(url, headers=headers, params=params)
print(response.json())

curl -X GET "https://scriptrun.ai/api/v1/scenarios/?name__icontains=example&project=1&page=2" \
-H "X-Api-Key: <Your API Key>"

GET /api/v1/scenarios/

Summary: Retrieves a list of scenarios with optional filtering.

This endpoint allows users to retrieve a list of scenarios, with options to filter by various parameters such as name, project, or the existence of a ScenarioRun.

Parameters:

Responses:

• 200: Returns a paginated list of scenarios.

Retrieve a Specific Scenario

import requests

url = "https://scriptrun.ai/api/v1/scenarios/42/"
headers = {"X-Api-Key": "<Your API Key>"}

response = requests.get(url, headers=headers)
print(response.json())

curl -X GET "https://scriptrun.ai/api/v1/scenarios/42/" \
-H "X-Api-Key: <Your API Key>"

GET /api/v1/scenarios/{id}/

Summary: Retrieves the details of a specific scenario by its ID.

This endpoint retrieves all the details of a specific scenario, including its messages, project information, and other metadata.

Parameters:

Responses:

• 200: Returns the details of the requested scenario.
• 404: Scenario not found.

Create a Scenario

import requests

url = "https://scriptrun.ai/api/v1/scenarios/"
headers = {"X-Api-Key": "<Your API Key>"}
data = {
    "name": "New Scenario",
    "project": 12,
    "category": 5,
    "run_fee": 50,
    "free_runs_per_user": 3,
    "messages": [1, 2, 3],
    "available_languages": ["en", "ru"],
    "market_title": "Sample Scenario",
    "short_description": "A new scenario example."
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

curl -X POST "https://scriptrun.ai/api/v1/scenarios/" \
-H "X-Api-Key: <Your API Key>" \
-H "Content-Type: application/json" \
-d '{
  "name": "New Scenario",
  "project": 12,
  "category": 5,
  "subcategory": 5,
  "run_fee": 50,
  "free_runs_per_user": 3,
  "messages": [1, 2, 3],
  "available_languages": ["en", "ru"],
  "market_title": "Sample Scenario",
  "short_description": "A new scenario example."
  "market_permission": "market_available",
  "readme_guide": "Some readme guide"
}'

POST /api/v1/scenarios/

Summary: Creates a new scenario.

This endpoint allows the creation of a new scenario by providing the necessary details, including project, category, messages, and other attributes.

Request Body:

Responses:

• 201: Scenario successfully created.
• 400: Invalid input or missing required parameters.

Update a Scenario

import requests

url = "https://scriptrun.ai/api/v1/scenarios/42/"
headers = {"X-Api-Key": "<Your API Key>"}
data = {
    "name": "Updated Scenario Name",
    "run_fee": 25
}

response = requests.patch(url, headers=headers, json=data)
print(response.json())

curl -X PATCH "https://scriptrun.ai/api/v1/scenarios/42/" \
-H "X-Api-Key: <Your API Key>" \
-H "Content-Type: application/json" \
-d '{
  "name": "Updated Scenario Name",
  "run_fee": 25
}'

PATCH /api/v1/scenarios/{id}/

Summary: Updates an existing scenario.

This endpoint allows partial updates to a scenario by providing new values for the desired attributes.

Parameters:

Request Body:

Responses:

• 200: Scenario successfully updated.
• 404: Scenario not found.

Delete a Scenario

import requests

url = "https://scriptrun.ai/api/v1/scenarios/42/"
headers = {"X-Api-Key": "<Your API Key>"}

response = requests.delete(url, headers=headers)
print(response.status_code)

curl -X DELETE "https://scriptrun.ai/api/v1/scenarios/42/" \
-H "X-Api-Key: <Your API Key>"

DELETE /api/v1/scenarios/{id}/

Summary: Deletes a specific scenario by its ID.

Parameters:

Responses:

• 204: Scenario successfully deleted.
• 404: Scenario not found.

ScenarioRun API

A ScenarioRun represents the execution of a scenario. It tracks the details of the run, such as the messages processed, variables updated, and the final result.

Create and Execute a ScenarioRun

import requests

url = "https://scriptrun.ai/api/v1/scenarioruns/run/"
headers = {"X-Api-Key": "<Your API Key>"}
data = {
    "scenario": 42,
    "webhook_url": "https://example.com/webhook",
    "do_run_default": True,
    "messages": [{"id": 1, "key": "newmessagekey1"}],
    "variables": [
        {
            "id": 3,
            "variable_names": [
                {
                    "id": 4,
                    "name": "newname123",
                },
            ],
        },
    ]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

curl -X POST "https://scriptrun.ai/api/v1/scenarioruns/run/" \
-H "X-Api-Key: <Your API Key>" \
-H "Content-Type: application/json" \
-d '{
  "scenario": 42,
  "webhook_url": "https://example.com/webhook",
  "do_run_default": true,
  "messages": [{"id": 1, "key": "newmessagekey1"}],
  "variables": [{"id": 3,"variable_names": [{"id": 4, "name": "newname123"}]}]
}'

POST /api/v1/scenarioruns/run/

Summary: Executes a scenario or an existing ScenarioRun.

This endpoint creates and starts a ScenarioRun, allowing you to execute a scenario and track the results.

Request Body:

Responses:

• 201: ScenarioRun successfully created and started.
• 400: Invalid input or missing parameters.

Retrieve a ScenarioRun

import requests

url = "https://scriptrun.ai/api/v1/scenarioruns/42/"
headers = {"X-Api-Key": "<Your API Key>"}

response = requests.get(url, headers=headers)
print(response.json())

curl -X GET "https://scriptrun.ai/api/v1/scenarioruns/42/" \
-H "X-Api-Key: <Your API Key>"

GET /api/v1/scenarioruns/{id}/

Summary: Retrieves a specific ScenarioRun by ID, including its execution details.

Parameters:

Responses:

• 200: Returns the details of the requested ScenarioRun.
• 404: ScenarioRun not found.

Update a ScenarioRun

import requests

url = "https://scriptrun.ai/api/v1/scenarioruns/42/"
headers = {"X-Api-Key": "<Your API Key>"}
data = {
    "webhook_url": "https://newexample.com/webhook",
    "do_run_default": False,
    "variables": [{"id": 3, "value": "updated value"}]
}

response = requests.patch(url, headers=headers, json=data)
print(response.json())

curl -X PATCH "https://scriptrun.ai/api/v1/scenarioruns/42/" \
-H "X-Api-Key: <Your API Key>" \
-H "Content-Type: application/json" \
-d '{
  "webhook_url": "https://newexample.com/webhook",
  "do_run_default": false,
  "variables": [{"id": 3, "value": "updated value"}]
}'

PATCH /api/v1/scenarioruns/{id}/

Summary: Updates an existing ScenarioRun.

This endpoint allows partial updates to a ScenarioRun by providing new values for the desired attributes.

Parameters:

Request Body:

Responses:

• 200: ScenarioRun successfully updated.
• 404: ScenarioRun not found.

Delete a ScenarioRun

import requests

url = "https://scriptrun.ai/api/v1/scenarioruns/42/"
headers = {"X-Api-Key": "<Your API Key>"}

response = requests.delete(url, headers=headers)
print(response.status_code)

curl -X DELETE "https://scriptrun.ai/api/v1/scenarioruns/42/" \
-H "X-Api-Key: <Your API Key>"

DELETE /api/v1/scenarioruns/{id}/

Summary: Deletes a specific ScenarioRun by its ID.

Parameters:

Responses:

• 204: ScenarioRun successfully deleted.
• 404: ScenarioRun not found.

Summary: Drafts, Runs, and Re-runs

After a scenario is executed (whether successful or not), the results will either appear in the Final Result or Local Variables, depending on the selected return parameter in the messages.

• You can Re-run a local scenario calling Execute a ScenarioRun.
• You can also edit the message parameters and local variables of the scenario.
• Drafts are created whenever you make the first change to a local scenario. A draft is a modified version of the scenario with your changes.
• To run the draft, calling Execute a ScenarioRun.

Update ScenarioRun Inserted Variable

curl -X PATCH "https://scriptrun.ai/api/v1/scenarioruns/42/update-inserted-variable" \
-H "X-Api-Key: <Your API Key>" \
-H "Content-Type: application/json" \
-d '{
  "id": <Your scnarionrun inserted_variable id>,
  "variable": <Your scnarionrun variable id,
  "variable_name": <Your scnarionrun variable name 2 id>,
}'

import requests

url = "https://scriptrun.ai/api/v1/scenarioruns/42/update-inserted-variable/"
headers = {"X-Api-Key": "<Your API Key>"}
data = {
  "id": "<Your scnarionrun inserted_variable id>",
  "variable": "<Your scnarionrun variable id>",
  "variable_name": "<Your scnarionrun variable name 2 id>",
}

response = requests.patch(url, headers=headers, json=data)
print(response.json())

PATCH /api/v1/scenarioruns/{id}/update-inserted-variable

Summary: Updates an existing inserted variable for a specific ScenarioRun.

Parameters:

Request Body:

Responses:

• 200: Inserted variable successfully updated.
• 404: ScenarioRun or inserted variable not found.

Update ScenarioRun Variable

curl -X PATCH "https://scriptrun.ai/api/v1/scenarioruns/42/update-variable" \
-H "X-Api-Key: <Your API Key>" \
-H "Content-Type: application/json" \
-d '{
    "id": <Your variable id>,
    "key": "new123",
    "variable_names": [
        {
            "id": <Your ScnarionRun variable_name id>,
            "name": "new_name",
            "value": "new_value",
        },
    ],
}'

import requests

url = "https://scriptrun.ai/api/v1/scenarioruns/42/update-variable/"
headers = {"X-Api-Key": "<Your API Key>"}
data = {
    "id": "<ScnarionRun Your variable id>",
    "key": "new123",
    "variable_names": [
        {
            "id": "<Your ScnarionRun variable_name id>",
            "name": "new_name",
            "value": "new_value",
        },
    ],
}

response = requests.patch(url, headers=headers, json=data)
print(response.json())

PATCH /api/v1/scenarioruns/{id}/update-variable

Summary: Updates an existing variable for a specific ScenarioRun.

Parameters:

Request Body:

Responses:

• 200: Variable successfully updated.
• 404: ScenarioRun or variable not found.

Update ScenarioRun Message

curl -X PATCH "https://scriptrun.ai/api/v1/scenarioruns/42/update-message" \
-H "X-Api-Key: <Your API Key>" \
-H "Content-Type: application/json" \
-d '{
    "id": <Your variable id>,
    "key": "new123",
    "variable_names": [
        {
            "id": <Your variable_name id>,
            "name": "new_name",
            "value": "new_value",
        },
    ],
}'

import requests

url = "https://scriptrun.ai/api/v1/scenarioruns/42/update-message/"
headers = {"X-Api-Key": "<Your API Key>"}
data = {"id": 123, "key": "Updated message key"}

response = requests.patch(url, headers=headers, json=data)
print(response.json())

PATCH /api/v1/scenarioruns/{id}/update-message

Summary: Updates an existing message for a specific ScenarioRun.

Parameters:

Request Body:

You can check message schema in Create a Message

Responses:

• 200: Message successfully updated.
• 404: ScenarioRun or message not found.

Workflow API Documentation

A Workflow in Slate is a flexible, visual representation of a process or automation. It consists of interconnected nodes (steps, triggers, actions, outputs) and edges (connections between nodes), allowing you to design and execute complex logic flows.

Key Concepts

• Workflow: A schema consisting of nodes and edges that defines the sequence of actions.
• Node: A step in the process (e.g., trigger, LLM request, data processing, output).
• Edge: Connects two nodes, defining the direction of the flow.
• Data: The structure describing all nodes, edges, the start node, and viewport parameters.

Workflow Data Structure Example

{
  "id": 6,
  "project": 307,
  "title": "New workflow",
  "data": {
    "edges": [
      {
        "id": "xy-edge__3d63f846-0f6a-478c-b91c-5921259429c1-a67fef47-c844-4489-9024-ff894b5d7465",
        "type": "custom-edge",
        "source": "3d63f846-0f6a-478c-b91c-5921259429c1",
        "target": "a67fef47-c844-4489-9024-ff894b5d7465",
        "style": {"stroke": "#76A9FA", "strokeWidth": 2},
        "animated": false,
        "markerEnd": "edge-target",
        "markerStart": "edge-source"
      }
    ],
    "nodes": [
      {
        "id": "3d63f846-0f6a-478c-b91c-5921259429c1",
        "type": "trigger-node",
        "data": { ... },
        ...
      },
      {
        "id": "a67fef47-c844-4489-9024-ff894b5d7465",
        "type": "basic-node",
        "data": { ... },
        ...
      },
      {
        "id": "2dfa426d-4233-49f2-8532-4b82f57640b6",
        "type": "output-node",
        "data": { ... },
        ...
      }
    ],
    "viewport": {"x": 0.25, "y": 152.25, "zoom": 0.5},
    "start_node": "a67fef47-c844-4489-9024-ff894b5d7465"
  }
}

API Endpoints

Create a Workflow

import requests

url = "https://scriptrun.ai/api/v1/workflows/"
headers = {"X-Api-Key": "<Your API Key>"}
data = {
    "project": 307,
    "title": "New workflow",
    "data": { ... }  # see structure above
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

curl -X POST "https://scriptrun.ai/api/v1/workflows/" \
-H "X-Api-Key: <Your API Key>" \
-H "Content-Type: application/json" \
-d '{
  "project": 307,
  "title": "New workflow",
  "data": { ... }
}'

POST /api/v1/workflows/

Summary: Creates a new workflow.

Request Body:

Responses:

• 201: Workflow successfully created.
• 400: Invalid input or missing required parameters.

Retrieve Workflows

url = "https://scriptrun.ai/api/v1/workflows/"
headers = {"X-Api-Key": "<Your API Key>"}
params = {"project": 307}

response = requests.get(url, headers=headers, params=params)
print(response.json())

curl -X GET "https://scriptrun.ai/api/v1/workflows/?project=307" \
-H "X-Api-Key: <Your API Key>"

GET /api/v1/workflows/

Summary: Retrieves a list of workflows, optionally filtered by project.

Parameters:

Responses:

• 200: Returns a paginated list of workflows.

Retrieve a Specific Workflow

url = "https://scriptrun.ai/api/v1/workflows/6/"
headers = {"X-Api-Key": "<Your API Key>"}

response = requests.get(url, headers=headers)
print(response.json())

curl -X GET "https://scriptrun.ai/api/v1/workflows/6/" \
-H "X-Api-Key: <Your API Key>"

GET /api/v1/workflows/{id}/

Summary: Retrieves the details of a specific workflow by its ID.

Parameters:

Responses:

• 200: Returns the workflow details.
• 404: Workflow not found.

Update a Workflow

url = "https://scriptrun.ai/api/v1/workflows/6/"
headers = {"X-Api-Key": "<Your API Key>"}
data = {
    "title": "Updated Workflow Title",
    "data": { ... }
}

response = requests.patch(url, headers=headers, json=data)
print(response.json())

curl -X PATCH "https://scriptrun.ai/api/v1/workflows/6/" \
-H "X-Api-Key: <Your API Key>" \
-H "Content-Type: application/json" \
-d '{
  "title": "Updated Workflow Title",
  "data": { ... }
}'

PATCH /api/v1/workflows/{id}/

Summary: Updates an existing workflow.

Parameters:

Request Body:

Responses:

• 200: Workflow successfully updated.
• 404: Workflow not found.

Delete a Workflow

url = "https://scriptrun.ai/api/v1/workflows/6/"
headers = {"X-Api-Key": "<Your API Key>"}

response = requests.delete(url, headers=headers)
print(response.status_code)

curl -X DELETE "https://scriptrun.ai/api/v1/workflows/6/" \
-H "X-Api-Key: <Your API Key>"

DELETE /api/v1/workflows/{id}/

Summary: Deletes a specific workflow by its ID.

Parameters:

Responses:

• 204: Workflow successfully deleted.
• 404: Workflow not found.

Additional Workflow Endpoints

Check Workflow Structure

POST /api/v1/workflows/check_workflow/

Summary: Validates the structure of a workflow before saving or running it.

import requests
url = "https://scriptrun.ai/api/v1/workflows/check_workflow/"
headers = {"X-Api-Key": "<Your API Key>"}
data = {
  "data": {
    "nodes": [...],
    "edges": [...],
    "viewport": {"x": 0, "y": 0, "zoom": 1},
    "start_node": "node-id-1"
  }
}
response = requests.post(url, headers=headers, json=data)
print(response.json())

curl -X POST "https://scriptrun.ai/api/v1/workflows/check_workflow/" \
  -H "X-Api-Key: <Your API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "nodes": [...],
      "edges": [...],
      "viewport": {"x": 0, "y": 0, "zoom": 1},
      "start_node": "node-id-1"
    }
  }'

Get Node Schemas for Frontend

GET /api/v1/workflows/get_nodes/

Summary: Retrieves the available node schemas for rendering and configuration in the frontend.

import requests
url = "https://scriptrun.ai/api/v1/workflows/get_nodes/"
headers = {"X-Api-Key": "<Your API Key>"}
response = requests.get(url, headers=headers)
print(response.json())

curl -X GET "https://scriptrun.ai/api/v1/workflows/get_nodes/" \
  -H "X-Api-Key: <Your API Key>"

Run a Workflow

POST /api/v1/workflows/run/

Summary: Starts the execution of a workflow. Requires a task_id as a query parameter.

import requests
url = "https://scriptrun.ai/api/v1/workflows/run/?task_id=123e4567-e89b-12d3-a456-426614174000"
headers = {"X-Api-Key": "<Your API Key>"}
data = {
  "data": {
    "nodes": [...],
    "edges": [...],
    "viewport": {"x": 0, "y": 0, "zoom": 1},
    "start_node": "node-id-1"
  }
}
response = requests.post(url, headers=headers, json=data)
print(response.json())

curl -X POST "https://scriptrun.ai/api/v1/workflows/run/?task_id=123e4567-e89b-12d3-a456-426614174000" \
  -H "X-Api-Key: <Your API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "nodes": [...],
      "edges": [...],
      "viewport": {"x": 0, "y": 0, "zoom": 1},
      "start_node": "node-id-1"
    }
  }'

Get Workflow Node Result

GET /api/v1/workflows/workflow_result/

Summary: Retrieves the result for a specific node in a workflow run.

import requests
url = "https://scriptrun.ai/api/v1/workflows/workflow_result/?task_id=123e4567-e89b-12d3-a456-426614174000&node_id=a67fef47-c844-4489-9024-ff894b5d7465"
headers = {"X-Api-Key": "<Your API Key>"}
response = requests.get(url, headers=headers)
print(response.json())

curl -X GET "https://scriptrun.ai/api/v1/workflows/workflow_result/?task_id=123e4567-e89b-12d3-a456-426614174000&node_id=a67fef47-c844-4489-9024-ff894b5d7465" \
  -H "X-Api-Key: <Your API Key>"

Workflow Run History

GET /api/v1/workflows/history/

Summary: Retrieves the history of workflow runs.

import requests
url = "https://scriptrun.ai/api/v1/workflows/history/?workflow_id=6&limit=10"
headers = {"X-Api-Key": "<Your API Key>"}
response = requests.get(url, headers=headers)
print(response.json())

curl -X GET "https://scriptrun.ai/api/v1/workflows/history/?workflow_id=6&limit=10" \
  -H "X-Api-Key: <Your API Key>"

Workflow Data Structure

• nodes: List of nodes, each containing:
  • id: Unique node identifier.
  • type: Node type (e.g., "trigger-node", "basic-node", "output-node").
  • data: Node parameters (name, settings, schema, messages, etc.).
  • position, measured, selected, etc. — visualization parameters.
• edges: List of connections between nodes, each containing:
  • id: Unique edge identifier.
  • source: Source node id.
  • target: Target node id.
  • type, style, markerEnd, markerStart, etc. — visualization parameters.
• viewport: Viewport parameters (x, y, zoom).
• start_node: id of the start node (usually the first action or trigger).

Summary

• A Workflow is a visual process schema consisting of nodes and edges.
• The API allows you to create, retrieve, update, and delete workflows.
• The data structure supports complex scenarios, branching, parameters, and visualization.
• For workflow execution , use the dedicated endpoints.

Documents API

The Documents API allows you to manage files uploaded to the system. These files are typically associated with specific projects and can be used in workflows like document recognition. The API supports operations like uploading multiple documents, retrieving document details, updating information, and deleting documents.

List of Documents

curl -X GET "https://scriptrun.ai/api/v1/documents/" \
  -H "X-Api-Key: <Your API Key>"

import requests

url = "https://scriptrun.ai/api/v1/documents/"
headers = {
    "X-Api-Key": "<Your API Key>"
}

response = requests.get(url, headers=headers)
print(response.json())

Responses:

• 200 OK: A paginated list of document objects.

  {
    "page": 1,
    "total": 2,
    "size": 2,
    "items": [
      {
        "id": 42,
        "project": 1,
        "key": "doc-abc123",
        "filename": "example.pdf",
        "result_file": "example.pdf",
        "result_url": "https://example.com/result.pdf",
        "created_at": "2024-10-03T10:00:00Z",
        "updated_at": "2024-10-03T10:05:00Z"
      },
      {
        "id": 43,
        "project": 1,
        "key": "doc-xyz456",
        "filename": "report.docx",
        "result_file": "report.docx",
        "result_url": "https://example.com/result.docx",
        "created_at": "2024-10-03T11:00:00Z",
        "updated_at": "2024-10-03T11:30:00Z"
      }
    ]
  }

GET /api/v1/documents/

Summary: Retrieves a list of all documents accessible to the authenticated user.

Response Explanation:

• page: Current page of the result set.
• total: Total number of documents available.
• size: Number of results returned per page.
• items: A list of documents with the following fields:
  • id: Unique identifier for the document.
  • project: The ID of the project the document belongs to.
  • key: Unique key identifier for the document.
  • filename: The original name of the uploaded file.
  • result_file: Path to the stored file.
  • result_url: URL to access the result (if applicable).
  • created_at: Timestamp when the document was created.
  • updated_at: Timestamp when the document was last updated.

Retrieve a Specific Document

curl -X GET "https://scriptrun.ai/api/v1/documents/42/" \
  -H "X-Api-Key: <Your API Key>"

import requests

url = "https://scriptrun.ai/api/v1/documents/42/"
headers = {
    "X-Api-Key": "<Your API Key>"
}

response = requests.get(url, headers=headers)
print(response.json())

GET /api/v1/documents/{id}/

Summary: Retrieves the details of a specific document by its ID.

Parameters:

Responses:

• 200 OK: The details of the requested document.

Upload Multiple Documents

POST /api/v1/documents/

curl -X POST "https://scriptrun.ai/api/v1/documents/" \
  -H "X-Api-Key: <Your API Key>" \
  -F "file1=@/path/to/example.pdf" \
  -F "file2=@/path/to/report.docx" \
  -F "project=1"

import requests

url = "https://scriptrun.ai/api/v1/documents/"
files = {
    'file1': open('/path/to/example.pdf', 'rb'),
    'file2': open('/path/to/report.docx', 'rb')
}
data = {
    'project': 1
}
headers = {
    "X-Api-Key": "<Your API Key>"
}

response = requests.post(url, headers=headers, files=files, data=data)
print(response.json())

Summary: Uploads up to five documents for a specific project.

Request Body:

• Content-Type: multipart/form-data

Responses:

• 201 Created: The documents were successfully uploaded.

Update Document

curl -X PATCH "https://scriptrun.ai/api/v1/documents/42/" \
  -H "X-Api-Key: <Your API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "updated-key",
    "filename": "updated-file.pdf"
  }'

import requests

url = "https://scriptrun.ai/api/v1/documents/42/"
data = {
    "key": "updated-key",
    "filename": "updated-file.pdf"
}
headers = {
    "X-Api-Key": "<Your API Key>",
    "Content-Type": "application/json"
}

response = requests.patch(url, headers=headers, json=data)
print(response.json())

PATCH /api/v1/documents/{id}/

Summary: Updates the metadata or file of a specific document.

Request Body:

• Content-Type: application/json

• Schema:

  • key (string) Optional: Updated key for the document.
  • filename (string) Optional: Updated filename for the document.
  • result_file (string) Optional: Updated result file path.
  • result_url (string) Optional: Updated result file URL.

Responses:

• 200 OK: The document was successfully updated.

Delete Document

curl -X DELETE "https://scriptrun.ai/api/v1/documents/42/" \
  -H "X-Api-Key: <Your API Key>"

import requests

url = "https://scriptrun.ai/api/v1/documents/42/"
headers = {
    "X-Api-Key": "<Your API Key>"
}

response = requests.delete(url, headers=headers)
print(response.status_code)

DELETE /api/v1/documents/{id}/

Summary: Deletes a specific document by its ID.

Parameters:

Responses:

• 204 No Content: The document was successfully deleted.

Documents and Recognition Relations

Documents are often used as input for document recognition processes. Once a document is uploaded via the Documents API, it can be linked to a Recognitionrun for processing. During a Recognitionrun, the document is processed, and chunks of recognized content are produced. The API allows full control over both the document upload and the recognition process, making it easy to manage files and automate workflows.

Recognition API

The Recognition API is responsible for managing document recognition runs and their chunks. It allows you to initiate recognition processes, retrieve recognition results, and manage the chunks of data produced during the recognition process.

List of Recognitionruns

{
  "page": 1,
  "total": 2,
  "size": 2,
  "items": [
    {
      "id": 42,
      "project": 1,
      "status": "created",
      "cost": 10.5,
      "chunk_size": 1000,
      "document": 123,
      "created_at": "2024-10-03T10:00:00Z",
      "updated_at": "2024-10-03T10:05:00Z"
    },
    {
      "id": 43,
      "project": 1,
      "status": "finished",
      "cost": 12.0,
      "chunk_size": 2000,
      "document": 124,
      "created_at": "2024-10-03T11:00:00Z",
      "updated_at": "2024-10-03T11:30:00Z"
    }
  ]
}

curl -X GET "https://scriptrun.ai/api/v1/recognitionruns/" \
  -H "X-Api-Key: <Your API Key>"

import requests

url = "https://scriptrun.ai/api/v1/recognitionruns/"
headers = {
    "X-Api-Key": "<Your API Key>"
}

response = requests.get(url, headers=headers)
print(response.json())

GET /api/v1/recognitionruns/

Summary: Retrieves a list of all recognition runs accessible to the authenticated user.

Responses:

• 200 OK: A paginated list of recognition run objects.
  • Content-Type: application/json
  • Schema:
    • page (integer) Required: Page of query.
    • size (integer) Optional: Number of results per call. Accepted values: 0 - 100. Default 10.
    • total (integer) Optional: Total objects in query.
    • items (array) Required A list of recognition runs with their metadata:

Retrieve a Specific Recognitionrun

curl -X GET "https://scriptrun.ai/api/v1/recognitionruns/42/" \
  -H "X-Api-Key: <Your API Key>"

import requests

url = "https://scriptrun.ai/api/v1/recognitionruns/42/"
headers = {
    "X-Api-Key": "<Your API Key>"
}

response = requests.get(url, headers=headers)
print(response.json())

GET /api/v1/recognitionruns/{id}/

Summary: Retrieves the details of a specific recognition run by its ID.

Parameters:

Responses:

• 200 OK: The details of the requested recognition run, including metadata and chunks.

Create a Recognitionrun

curl -X POST "https://scriptrun.ai/api/v1/recognitionruns/" \
  -H "X-Api-Key: <Your API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "project": 1,
    "chunk_size": 1000,
    "document": 123
  }'

import requests

url = "https://scriptrun.ai/api/v1/recognitionruns/"
headers = {
    "X-Api-Key": "<Your API Key>",
    "Content-Type": "application/json"
}
data = {
    "project": 1,
    "chunk_size": 1000,
    "document": 123
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

POST /api/v1/recognitionruns/

Summary: Creates a new recognition run for a project.

Request Body:

• Content-Type: application/json
• Schema:
  • project (integer) Required: The ID of the associated project.
  • chunk_size (integer) Optional: The chunk size for the recognition process.
  • document (integer) Required: The ID of the document to be recognized.

Responses:

• 201 Created: Created recognition run object.

Enable All Chunks in a Recognitionrun

curl -X POST "https://scriptrun.ai/api/v1/recognitionruns/42/enable-chunks/" \
  -H "X-Api-Key: <Your API Key>"

import requests

url = "https://scriptrun.ai/api/v1/recognitionruns/42/enable-chunks/"
headers = {
    "X-Api-Key": "<Your API Key>"
}

response = requests.post(url, headers=headers)
print(response.json())

POST /api/v1/recognitionruns/{id}/enable-chunks/

Summary: Enables all chunks in the specified recognition run.

Parameters:

Responses:

• 200 OK: All chunks have been enabled for the recognition run.

Disable All Chunks in a Recognitionrun

curl -X POST "https://scriptrun.ai/api/v1/recognitionruns/42/disable-chunks/" \
  -H "X-Api-Key: <Your API Key>"

import requests

url = "https://scriptrun.ai/api/v1/recognitionruns/42/disable-chunks/"
headers = {
    "X-Api-Key": "<Your API Key>"
}

response = requests.post(url, headers=headers)
print(response.json())

POST /api/v1/recognitionruns/{id}/disable-chunks/

Summary: Disables all chunks in the specified recognition run.

Parameters:

Responses:

• 200 OK: All chunks have been disabled for the recognition run.

Enable a Specific Chunk in a Recognitionrun

curl -X POST "https://scriptrun.ai/api/v1/recognitionruns/42/enable-chunk/" \
  -H "X-Api-Key: <Your API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 123
  }'

import requests

url = "https://scriptrun.ai/api/v1/recognitionruns/42/enable-chunk/"
headers = {
    "X-Api-Key": "<Your API Key>",
    "Content-Type": "application/json"
}
data = {
    "id": 123
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

POST /api/v1/recognitionruns/{id}/enable-chunk/

Summary: Enables a specific chunk in the recognition run.

Request Body:

• Content-Type: application/json
• Schema:
  • id (integer) Required: The unique ID of the chunk to enable.

Responses:

• 200 OK: The specified chunk has been enabled.

Disable a Specific Chunk in a Recognitionrun

curl -X POST "https://scriptrun.ai/api/v1/recognitionruns/42/disable-chunk

/" \
  -H "X-Api-Key: <Your API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 123
  }'

import requests

url = "https://scriptrun.ai/api/v1/recognitionruns/42/disable-chunk/"
headers = {
    "X-Api-Key": "<Your API Key>",
    "Content-Type": "application/json"
}
data = {
    "id": 123
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

POST /api/v1/recognitionruns/{id}/disable-chunk/

Summary: Disables a specific chunk in the recognition run.

Request Body:

• Content-Type: application/json
• Schema:
  • id (integer) Required: The unique ID of the chunk to disable.

Responses:

• 200 OK: The specified chunk has been disabled.

Recognitionrun Chunk API

curl -X GET "https://scriptrun.ai/api/v1/recognitionrun-chunks/42/" \
  -H "X-Api-Key: <Your API Key>"

import requests

url = "https://scriptrun.ai/api/v1/recognitionrun-chunks/42/"
headers = {
    "X-Api-Key": "<Your API Key>"
}

response = requests.get(url, headers=headers)
print(response.json())

Retrieve a Specific Recognitionrun Chunk

GET /api/v1/recognitionrun-chunks/{id}/

Summary: Retrieves the details of a specific recognition run chunk by its ID.

Parameters:

Responses:

• 200 OK: The details of the requested recognition run chunk.

Using Recognitionrun and Chunks

• Recognitionrun stores metadata of the document recognition process.
• Chunks hold portions of the recognized document.
• Chunks can be enabled or disabled individually or in bulk using the API endpoints provided.

These endpoints allow full control over document recognition, including starting recognition runs, managing chunks, and retrieving results.

Prompts and Messages Relations

The Prompts and Messages APIs allow you to manage and interact with prompts and messages within the system. Prompts are user interaction points that gather input and conditionally affect the workflow, while Messages represent individual communication units that can be sent, retrieved, updated, deleted, and reordered. These APIs provide endpoints to create, retrieve, update, delete, and reorder both prompts and messages. The API uses token-based authentication; include your API key in the X-Api-Key header in each request.

Key Concepts

Prompts

A Prompt is an interaction point within a scenario that gathers input from users or performs specific actions based on conditions. Prompts can be simple text inputs, multiple-choice selections, or more complex forms that collect various types of data. They play a crucial role in guiding users through a workflow or conversation, enabling dynamic and interactive experiences.

Structure:

1. Key: A unique identifier for the prompt within a project.
2. Role: Defines the role associated with the prompt (e.g., user, system, assistant, positive, negative).
3. Content: The textual content of the prompt that is presented to the user.
4. Project: The project to which the prompt belongs.
5. Prompt Conditions: Conditions that determine when and how the prompt is rendered based on variables or inserted variables.
6. Attached Prompts: Prompts that are linked to messages, allowing for complex interactions and data collection.
7. Inserted Variables and Messages: Variables and messages embedded within the prompt content that can be dynamically updated or manipulated.

Key Components:

• Prompt Conditions: Define the logic for when a prompt should be rendered or skipped based on certain conditions.
• Attached Prompts: Links prompts to specific messages, enabling the association of user inputs with messages.
• Inserted Variables: Variables embedded within the prompt content that can store and manipulate user input or other dynamic data.

Messages

A Message is an individual communication unit within a scenario that can represent a question, instruction, or data transmission point. Messages can be looped, sent asynchronously, and have different return types based on the provider used (e.g., text, variables, image). They are essential for structuring the flow of communication within a scenario.

Structure:

1. Key: A unique identifier for the message within a project.
2. Project: The project to which the message belongs.
3. Provider: The AI provider used to generate the message (e.g., openai, claude, gemini, togetherai).
4. Return Type: The type of content returned by the message (text, variables, image).
5. Provider-Specific Parameters: Configuration parameters specific to the chosen AI provider (e.g., model name, temperature, max tokens).
6. Loop Settings: Determines if the message should be looped and how many times.
7. Attached Prompts: Prompts linked to the message for gathering user input.
8. Sort ID: Determines the order of the message within the project.

Key Components:

• Return Types: Define the format of the response returned by the AI provider, allowing for flexibility in how messages are processed and displayed.
• Provider-Specific Configurations: Customize the behavior of messages based on the capabilities and requirements of different AI providers.
• Looping Mechanism: Enables repetitive sending of messages based on predefined conditions and limits.

Prompts

Prompts are designed to interact with users, gather input, and influence the flow of messages based on predefined conditions. They serve as the bridge between user inputs and the dynamic behavior of messages within a scenario.

Messages

Messages utilize prompts to create interactive and responsive communication flows. Each message can have multiple attached prompts, allowing for complex interactions where user inputs can dictate subsequent messages or actions.

Interaction Flow:

1. Message Sends Prompt: A message can trigger one or more prompts to gather input from the user.
2. User Provides Input: The user interacts with the prompt, providing necessary data or selections.
3. Condition Evaluation: Based on the input, conditions associated with prompts are evaluated to determine the next steps.
4. Dynamic Message Flow: Depending on the conditions and user input, different messages may be sent, skipped, or reordered, creating a dynamic and personalized experience.

Example Workflow:

1. Message 1: Sends a greeting to the user.
2. Prompt 1: Asks the user for their name.
3. Message 2: Greets the user by name using the input from Prompt 1.
4. Prompt 2: Asks the user how they can be assisted.
5. Condition: If the user requests a password reset, send Message 3; otherwise, send Message 4.
6. Message 3: Provides password reset instructions.
7. Message 4: Offers general assistance based on user input.

Prompts and Messages API Reference

Messages API Endpoints

• List Messages: GET /api/v1/messages/
• Retrieve a Message: GET /api/v1/messages/{id}/
• Create a Message: POST /api/v1/messages/
• Update a Message: PATCH /api/v1/messages/{id}/
• Delete a Message: DELETE /api/v1/messages/{id}/
• Reorder Messages: POST /api/v1/messages/{id}/reorder/
• List Available Models: GET /api/v1/messages/models/

Prompts API Endpoints

• List Prompts: GET /api/v1/prompts/
• Retrieve a Prompt: GET /api/v1/prompts/{id}/
• Create a Prompt: POST /api/v1/prompts/
• Update a Prompt: PATCH /api/v1/prompts/{id}/
• Delete a Prompt: DELETE /api/v1/prompts/{id}/
• Reorder a Prompt: POST /api/v1/prompts/{id}/reorder/

Conclusion

The Prompts and Messages APIs provide a comprehensive framework for creating dynamic, interactive workflows within your projects. By leveraging these APIs, you can build sophisticated scenarios that respond to user inputs, adapt based on conditions, and integrate seamlessly with various AI providers to deliver personalized and effective user experiences.

For more detailed information on specific endpoints, parameters, and usage examples, refer to the respective API sections above.

Messages API

This documentation describes the API endpoints for managing messages in the system. You can use these endpoints to create, retrieve, update, delete, and reorder messages. The API uses token-based authentication; include your API key in the X-Api-Key header in each request.

List of Messages

curl -X GET "https://scriptrun.ai/api/v1/messages/" \
  -H "X-Api-Key: <Your API Key>"

import requests

url = "https://scriptrun.ai/api/v1/messages/"
headers = {
    "X-Api-Key": "<Your API Key>"
}

response = requests.get(url, headers=headers)
print(response.json())

GET /api/v1/messages/

Summary: Retrieves a list of all messages accessible to the authenticated user.

Parameters:

• Query Parameters (optional):

Responses:

• 200 OK:

  • Content-Type: application/json
  • Schema: A paginated list of message objects.

Retrieve a Message

curl -X GET "https://scriptrun.ai/api/v1/messages/1/" \
  -H "X-Api-Key: <Your API Key>"

import requests

url = "https://scriptrun.ai/api/v1/messages/1/"
headers = {
    "X-Api-Key": "<Your API Key>"
}

response = requests.get(url, headers=headers)
print(response.json())

GET /api/v1/messages/{id}/

Summary: Retrieves the details of a specific message by its ID.

Parameters:

• Path Parameters:

Responses:

• 200 OK:

  • Content-Type: application/json
  • Schema: Message object.

• 404 Not Found:

  • The message does not exist or is not accessible to the user.

Create a Message

curl -X POST "https://scriptrun.ai/api/v1/messages/" \
  -H "X-Api-Key: <Your API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "unique_key",
    "project": 1,
    "provider": "openai",
    "return_type": "text",
    "openai_model": "gpt-4",
    "openai_temperature": 0.7,
    "prompts": [1, 2],
}'

import requests

url = "https://scriptrun.ai/api/v1/messages/"
headers = {
    "X-Api-Key": "<Your API Key>",
    "Content-Type": "application/json"
}
data = {
    "key": "unique_key",
    "project": 1,
    "provider": "openai",
    "return_type": "text",
    "openai_model": "gpt-4",
    "openai_temperature": 0.7
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

POST /api/v1/messages/

Summary: Creates a new message.

Request Body:

• Content-Type: application/json
• Schema:

Provider-Specific Parameters:

• OpenAI:

• Claude:

• Other providers follow similar patterns.

Responses:

• 201 Created:

  • Content-Type: application/json
  • Schema: The created message object.

• 400 Bad Request:

  • Invalid input data.

Update a Message

curl -X PATCH "https://scriptrun.ai/api/v1/messages/1/" \
  -H "X-Api-Key: <Your API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "openai_temperature": 0.9
}'

import requests

url = "https://scriptrun.ai/api/v1/messages/1/"
headers = {
    "X-Api-Key": "<Your API Key>",
    "Content-Type": "application/json"
}
data = {
    "openai_temperature": 0.9
}

response = requests.patch(url, headers=headers, json=data)
print(response.json())

PATCH /api/v1/messages/{id}/

Summary: Updates an existing message.

Parameters:

• Path Parameters:

Request Body:

• Content-Type: application/json
• Schema: Fields to update. Same as in Create a Message, but all fields are optional.

Responses:

• 200 OK:

  • Content-Type: application/json
  • Schema: The updated message object.

• 400 Bad Request:

  • Invalid input data.

• 404 Not Found:

  • The message does not exist or is not accessible to the user.

Delete a Message

curl -X DELETE "https://scriptrun.ai/api/v1/messages/1/" \
  -H "X-Api-Key: <Your API Key>"

import requests

url = "https://scriptrun.ai/api/v1/messages/1/"
headers = {
    "X-Api-Key": "<Your API Key>"
}

response = requests.delete(url, headers=headers)
print(response.status_code)

DELETE /api/v1/messages/{id}/

Summary: Deletes a message.

Parameters:

• Path Parameters:

Responses:

• 204 No Content:

  • The message was successfully deleted.

• 404 Not Found:

  • The message does not exist or is not accessible to the user.

Reorder Messages

curl -X POST "https://scriptrun.ai/api/v1/messages/1/reorder/" \
  -H "X-Api-Key: <Your API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "sort_id": 2
}'

import requests

url = "https://scriptrun.ai/api/v1/messages/1/reorder/"
headers = {
    "X-Api-Key": "<Your API Key>",
    "Content-Type": "application/json"
}
data = {
    "sort_id": 2
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

POST /api/v1/messages/{id}/reorder/

Summary: Changes the sorting order of a message within its project.

Parameters:

• Path Parameters:

Request Body:

• Content-Type: application/json
• Schema:

Responses:

• 200 OK:

  • Content-Type: application/json
  • Schema: The updated message object with the new sort_id.

• 400 Bad Request:

  • Invalid sort_id value.

• 404 Not Found:

  • The message does not exist or is not accessible to the user.

List of Available Models

curl -X GET "https://scriptrun.ai/api/v1/messages/models/" \
  -H "X-Api-Key: <Your API Key>"

import requests

url = "https://scriptrun.ai/api/v1/messages/models/"
headers = {
    "X-Api-Key": "<Your API Key>"
}

response = requests.get(url, headers=headers)
print(response.json())

//Example response
[
  {
    "slug": "claude-3-5-sonnet-20240620",
    "label": "claude-3-5-sonnet-20240620",
    "provider": "claude",
    "max_tokens": 8192,
    "temperature": {
      "min": 0,
      "max": 1,
      "default": 1
    },
    "frequency_penalty": null,
    "presence_penalty": null
  },
  {
    "slug": "claude-3-haiku-20240307",
    "label": "claude-3-haiku-20240307",
    "provider": "claude",
    "max_tokens": 4096,
    "temperature": {
      "min": 0,
      "max": 1,
      "default": 1
    },
    "frequency_penalty": null,
    "presence_penalty": null
  },
  {
    "slug": "gemini-1.5-flash",
    "label": "gemini-1.5-flash",
    "provider": "gemini",
    "max_tokens": 8192,
    "temperature": {
      "min": 0,
      "max": 2,
      "default": 1
    },
    "frequency_penalty": null,
    "presence_penalty": null
  },
  {
    "slug": "gemini-1.5-pro",
    "label": "gemini-1.5-pro",
    "provider": "gemini",
    "max_tokens": 8192,
    "temperature": {
      "min": 0,
      "max": 2,
      "default": 1
    },
    "frequency_penalty": null,
    "presence_penalty": null
  },
  ... and others
]

GET /api/v1/messages/models/

Summary: Retrieves a list of available AI models along with their parameters and constraints.

Responses:

• 200 OK:

  • Content-Type: application/json

• Schema: A list of model objects containing:

Message Fields

Common Fields

• id (integer): Unique identifier of the message.
• key (string): Unique key for the message within the project.
• project (integer): ID of the project the message belongs to.
• provider (string): AI provider (openai, claude, gemini, togetherai).
• return_type (string): Type of the return value (text, variables, image).
• sort_id (integer): Sorting index of the message.

Provider-Specific Fields

OpenAI Fields

• openai_model (string): Model name (e.g., gpt-4).
• openai_temperature (float): Sampling temperature.
• openai_max_tokens (integer): Maximum number of tokens.
• openai_frequency_penalty (float): Frequency penalty.
• openai_presence_penalty (float): Presence penalty.

Claude Fields

• claude_model (string): Model name.
• claude_temperature (float): Sampling temperature.
• claude_max_tokens (integer): Maximum number of tokens.

Gemini Fields

• gemini_model (string): Model name.
• gemini_temperature (float): Sampling temperature.
• gemini_max_tokens (integer): Maximum number of tokens.

TogetherAI Fields

• togetherai_model (string): Model name.
• togetherai_temperature (float): Sampling temperature.
• togetherai_max_tokens (integer): Maximum number of tokens.
• togetherai_top_k (integer): Top-K sampling.
• togetherai_top_p (float): Top-P (nucleus) sampling.
• togetherai_repetition_penalty (float): Repetition penalty.

You can check all validation conditions in List of Available Models

Stability Fields

• stabilityai_engine_id (integer): Engine id.
• stabilityai_style_preset (string): Style presets:
  • 3d-model
  • analog-film
  • anime
  • cinematic
  • comic-book
  • digital-art
  • enhance
  • fantasy-art
  • isometric
  • line-art
  • low-poly
  • modeling-compound
  • neon-punk
  • origami
  • photographic
  • pixel-art
  • tile-texture
• stabilityai_cfg_scale (integer): Config scale.
• stabilityai_clip_guidance_preset (string): Clip guidance preset:
  • FAST_BLUE
  • FAST_GREEN
  • SIMPLE
  • SLOW
  • SLOWER
  • SLOWEST
• stabilityai_height (integer): Image height.
• stabilityai_width (integer): Image width.
• stabilityai_samples (integer): Samples.
• stabilityai_steps (integer): Steps.

Prompts API

This documentation describes the API endpoints for managing prompts in the system. You can use these endpoints to create, retrieve, update, delete, and reorder prompts. The API uses token-based authentication; include your API key in the X-Api-Key header in each request.

List of Prompts

curl -X GET "https://scriptrun.ai/api/v1/prompts/" \
  -H "X-Api-Key: <Your API Key>"

import requests

url = "https://scriptrun.ai/api/v1/prompts/"
headers = {
    "X-Api-Key": "<Your API Key>"
}

response = requests.get(url, headers=headers)
print(response.json())

GET /api/v1/prompts/

Summary: Retrieves a list of all prompts accessible to the authenticated user.

Parameters:

• Query Parameters (optional):

Responses:

• 200 OK:

  • Content-Type: application/json
  • Schema: A paginated list of prompt objects.

Retrieve a Prompt

curl -X GET "https://scriptrun.ai/api/v1/prompts/1/" \
  -H "X-Api-Key: <Your API Key>"

import requests

url = "https://scriptrun.ai/api/v1/prompts/1/"
headers = {
    "X-Api-Key": "<Your API Key>"
}

response = requests.get(url, headers=headers)
print(response.json())

GET /api/v1/prompts/{id}/

Summary: Retrieves the details of a specific prompt by its ID.

Parameters:

• Path Parameters:

Responses:

• 200 OK:

  • Content-Type: application/json
  • Schema: Prompt object.

- 404 Not Found:

• The prompt does not exist or is not accessible to the user.

Create a Prompt

POST /api/v1/prompts/

curl -X POST "https://scriptrun.ai/api/v1/prompts/" \
  -H "X-Api-Key: <Your API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "api_key_prompt",
    "role": "user",
    "content": "Please enter your API key: <variable>-1,40330,274261</variable> \nImportant: <message>0,7010</message>",
    "project": 1,
    "prompt_conditions": [
      {
        "is_enabled": true,
        "type": "variable",
        "matching": "equal",
        "value": "example_value",
        "action": "skip"
      }
    ]
  }'

import requests

url = "https://scriptrun.ai/api/v1/prompts/"
headers = {
    "X-Api-Key": "<Your API Key>",
    "Content-Type": "application/json"
}
data = {
    "key": "api_key_prompt",
    "role": "user",
    "content": "Please enter your API key: <variable>-1,40330,274261</variable> \nImportant: <message>0,7010</message>",
    "project": 1,
    "prompt_conditions": [
      {
        "is_enabled": True,
        "type": "variable",
        "matching": "equal",
        "value": "example_value",
        "action": "skip"
      }
    ]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

Summary: Creates a new prompt.

Request Body

About prompt_conditions

prompt_conditions is an optional array of conditions that define when the prompt will be executed or rendered. Each condition is an object that can contain the following fields:

• is_enabled: Boolean that determines if the condition is active.
• type: The type of condition. Available types:
  • variable – compares a variable to a value.
  • inserted_variable – compares an inserted variable to a value.
• matching: The type of comparison. Available options:
  • equal – the variable or inserted variable must be equal to the specified value.
  • contains – checks if the value contains a specific string.
  • not_equal – checks that the value is not equal to the specified value.
  • not_contains – checks that the value does not contain the specified string.
• value: The value to compare the variable or inserted variable with.
• action: Action to take if the condition is met. Default action is skip (skips the prompt if the condition is met).

Embedding Variables and Messages

To enhance the interactivity of your prompts, you can embed variables and messages within the content field using specific placeholders. These placeholders allow dynamic insertion of values and display of conditional messages.

Variable Placeholder

Use the <variable> tag to insert a variable into your prompt content. The format is:

<variable>-1,{variable_id},{variable_name_id}</variable>

• -1: Indicates the creation of a new variable. Must be a negative and unique value.
• <variable_id>: The ID of the variable.
• <variable_name_id>: The ID of the associated variable_names.

Please enter your API key: <variable>-1,40330,274261</variable>

Message Placeholder

Use the <message> tag to insert a message into your prompt content. The format is:

<message>0,{message_id}</message>

• 0: Indicates the creation of a new message.
• <message_id>: The ID of the message.

Important: <message>0,7010</message>

Update a Prompt

curl -X PATCH "https://scriptrun.ai/api/v1/prompts/1/" \
  -H "X-Api-Key: <Your API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Updated content"
  }'

import requests

url = "https://scriptrun.ai/api/v1/prompts/1/"
headers = {
    "X-Api-Key": "<Your API Key>",
    "Content-Type": "application/json"
}
data = {
    "content": "Updated content"
}

response = requests.patch(url, headers=headers, json=data)
print(response.json())

PATCH /api/v1/prompts/{id}/

Summary: Updates the details of an existing prompt.

Parameters:

• Path Parameters:

Request Body (partial):

Responses:

• 200 OK:

  • Content-Type: application/json
  • Schema: Updated prompt object.

Delete a Prompt

curl -X DELETE "https://scriptrun.ai/api/v1/prompts/1/" \
  -H "X-Api-Key: <Your API Key>"

import requests

url = "https://scriptrun.ai/api/v1/prompts/1/"
headers = {
    "X-Api-Key": "<Your API Key>"
}

response = requests.delete(url, headers=headers)
print(response.status_code)

DELETE /api/v1/prompts/{id}/

Summary: Deletes a specific prompt by its ID.

Parameters:

• Path Parameters:

Responses:

• 204 No Content:

  • The prompt has been successfully deleted.

• 404 Not Found:

  • The prompt does not exist or is not accessible to the user.

Reorder a Prompt

curl -X POST "https://scriptrun.ai/api/v1/prompts/1/reorder/" \
  -H "X-Api-Key: <Your API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "sort_id": 2
  }'

import requests

url = "https://scriptrun.ai/api/v1/prompts/1/reorder/"
headers = {
    "X-Api-Key": "<Your API Key>",
    "Content-Type": "application/json"
}
data = {
    "sort_id": 2
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

POST /api/v1/prompts/{id}/reorder/

Summary: Reorders the specified prompt by updating its sort_id.

Parameters:

• Path Parameters:

Request Body:

Responses:

• 200 OK:

  • Content-Type: application/json
  • Schema: Updated prompt object.

Variables API

The Variables API is used to create and manage variables that store keyword data. These variables can be integrated into system prompts dynamically, adapting their content based on keywords or clusters generated from Keywordrun.

List of Variables

curl -X GET "https://scriptrun.ai/api/v1/variables/" \
  -H "X-Api-Key: <Your API Key>"

import requests

url = "https://scriptrun.ai/api/v1/variables/"
headers = {
    "X-Api-Key": "<Your API Key>"
}

response = requests.get(url, headers=headers)
print(response.json())

GET /api/v1/variables/

Summary: Retrieves a list of all variables accessible to the authenticated user.

Responses:

• 200 OK: A paginated list of variable objects.

Create a Variable

curl -X POST "https://scriptrun.ai/api/v1/variables/" \
  -H "X-Api-Key: <Your API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "example_keyword_variable",
    "project": 1,
    "variable_names": [
      {
        "name": "Keyword Cluster 1",
        "value": "example keyword 1, example keyword 2",
        "is_active": true
      },
      {
        "name": "Keyword Cluster 2",
        "value": "example keyword 3",
        "is_active": false
      }
    ]
  }'

import requests

url = "https://scriptrun.ai/api/v1/variables/"
headers = {
    "X-Api-Key": "<Your API Key>",
    "Content-Type": "application/json"
}
data = {
    "key": "example_keyword_variable",
    "project": 1,
    "variable_names": [
        {
            "name": "Keyword Cluster 1",
            "value": "example keyword 1, example keyword 2",
            "is_active": True
        },
        {
            "name": "Keyword Cluster 2",
            "value": "example keyword 3",
            "is_active": False
        }
    ]
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

POST /api/v1/variables/

Summary: Creates a new variable to store keyword or cluster data, which can be used in prompts.

Request Body:

Responses:

• 201 Created: Created variable object.

Update a Variable

curl -X PATCH "https://scriptrun.ai/api/v1/variables/1/" \
  -H "X-Api-Key: <Your API Key>" \
  -H "Content-Type: application/json" \
  -d '{
            "key": "test",
            "keywordrun": None,
            "keywordrun_mode": "",
            "variable_names": [
                {
                    "name": "test",
                    "value": "",
                    "is_active": True,
                },
            ],
            "project": project.id,
        }'

import requests

url = "https://scriptrun.ai/api/v1/variables/1/"
headers = {
    "X-Api-Key": "<Your API Key>",
    "Content-Type": "application/json"
}
data = {
    "key": "test",
    "keywordrun": None,
    "keywordrun_mode": "",
    "variable_names": [
        {
            "name": "test",
            "value": "",
            "is_active": True,
        },
    ],
    "project": project.id,
}

response = requests.patch(url, headers=headers, json=data)
print(response.json())

PATCH /api/v1/variables/{id}/

Summary: Updates a specific variable.

Parameters:

Request Body:

Responses:

• 200 OK: Updated variable object.

Delete a Variable

curl -X DELETE "https://scriptrun.ai/api/v1/variables/1/" \
  -H "X-Api-Key: <Your API Key>"

import requests

url = "https://scriptrun.ai/api/v1/variables/1/"
headers = {
    "X-Api-Key": "<Your API Key>"
}

response = requests.delete(url, headers=headers)
print(response.status_code)

DELETE /api/v1/variables/{id}/

Summary: Deletes a specific variable by its ID.

Parameters:

Responses:

• 204 No Content: Variable successfully deleted.

Reorder a Variable

curl -X POST "https://scriptrun.ai/api/v1/variables/1/reorder/" \
  -H "X-Api-Key: <Your API Key>" \
  -H "Content-Type: application/json" \
  -d '{
    "sort_id": 5
  }'

import requests

url = "https://scriptrun.ai/api/v1/variables/1/reorder/"
headers = {
    "X-Api-Key": "<Your API Key>",
    "Content-Type": "application/json"
}
data = {"sort_id": 5}

response = requests.post(url, headers=headers, json=data)
print(response.status_code)

POST /api/v1/variables/{id}/reorder/

Summary: Updates the order of a specific variable.

Parameters:

Request Body:

Responses:

• 200 OK: Variable successfully reordered.

Retrieve Project Stopwords

curl -X GET "https://scriptrun.ai/api/v1/projects/123/get-stopwords/" \
  -H "X-Api-Key: <Your API Key>"

import requests

url = "https://scriptrun.ai/api/v1/projects/123/get-stopwords/"
headers = {"X-Api-Key": "<Your API Key>"}

response = requests.get(url, headers=headers)
print(response.json())

GET /api/v1/projects/{id}/get-stopwords/

Summary: Retrieves the stopwords associated with a specific project.

Parameters:

Responses:

• 200 OK:
  • Content-Type: application/json
  • Schema:
    • stopwords (array) Required: List of stopwords used in the project.

Set Project Stopwords

curl -X POST "https://scriptrun.ai/api/v1/projects/123/set-stopwords/" \
  -H "X-Api-Key: <Your API Key>" \
  -H "Content-Type: application/json" \
  -d '{"stopwords": ["stopword1", "stopword2"]}'

import requests

url = "https://scriptrun.ai/api/v1/projects/123/set-stopwords/"
headers = {
    "X-Api-Key": "<Your API Key>",
    "Content-Type": "application/json"
}
data = {"stopwords": ["stopword1", "stopword2"]}

response = requests.post(url, headers=headers, json=data)
print(response.json())

POST /api/v1/projects/{id}/set-stopwords/

Summary: Updates the list of stopwords associated with a specific project.

Parameters:

Request Body:

• Content-Type: application/json
• Schema:
  • stopwords (array) Required: A list of stopwords to set for the project.

Responses:

• 200 OK:
  • Content-Type: application/json
  • Schema:
    • stopwords (array) Required: Updated list of stopwords.
    • stopwords (array) Required: Updated list of stopwords.

Keywords API

The Keywords API allows you to manage and retrieve individual keywords that are used in the system for content extraction, search engine optimization, or any other automated keyword-based operations.

List of Keywords

curl -X GET "https://scriptrun.ai/api/v1/keywords/" \
  -H "X-Api-Key: <Your API Key>"

import requests

url = "https://scriptrun.ai/api/v1/keywords/"
headers = {
    "X-Api-Key": "<Your API Key>"
}

response = requests.get(url, headers=headers)
print(response.json())