Interactions

An Interaction is a reusable function that can be invoked to perform a specific task. It is defined by a set of prompts and a model. The prompts are used to provide context to the model, and the model is used to generate a response.

The /interactions endpoint allows you to manage your Interactions and the /execute endpoint allows you to execute Interactions by name.

Create Interaction

Endpoint: /interactions

Method: POST

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`
`Content-Type`	`application/json`

Input Parameters

Parameter	Data Type	Description
`name`	`string`	The name of the Interaction.
`description`	`string`	The description of the Interaction.
`status`	`InteractionStatus`	The status of the Interaction.
`tags`	`string[]`	The tags of the Interaction.
`test_data`	`JSONObject`	The test data of the Interaction.
`result_schema`	`JSONSchema4`	The result schema of the Interaction.
`cache_policy`	`CachePolicy`	The cache policy of the Interaction.
`model`	`string`	The model of the Interaction.
`temperature`	`number`	The temperature of the Interaction.
`prompts`	`PromptSegmentDef[]`	The prompts of the Interaction.
`max_tokens`	`number`	The maximum number of tokens of the Interaction.
`environment`	`string`	The environment of the Interaction.
`restriction`	`RunDataStorageLevel`	The level of information to store for an Interaction Run.

Example Request

{
  "name": "My Interaction",
  "description": "This is my interaction",
  "status": "draft",
  "tags": ["tag1", "tag2"],
  "test_data": {
    "key": "value"
  },
  "result_schema": {
    "type": "object",
    "properties": {
      "key": {
        "type": "string"
      }
    }
  },
  "cache_policy": {
    "type": "cache",
    "refresh_probability": 0.1,
    "varies_on": ["key"],
    "ttl": 3600
  },
  "model": "text-davinci-003",
  "temperature": 0.7,
  "prompts": [
    {
      "type": "chat",
      "configuration": {
        "role": "user",
        "content": "This is a chat prompt"
      }
    },
    {
      "type": "template",
      "template": "<PROMPT_TEMPLATE_ID>"
    }
  ],
  "max_tokens": 1024,
  "environment": "<ENVIRONMENT_ID>",
  "restriction": "STANDARD"
}

Example Response

{
    "id": "<INTERACTION_ID>",
    "name": "My Interaction",
    "description": "This is my interaction",
    "status": "draft",
    "tags": [
        "tag1",
        "tag2"
    ],
    "test_data": {
        "key": "value"
    },
    "result_schema": {
        "type": "object",
        "properties": {
            "key": {
                "type": "string"
            }
        }
    },
    "cache_policy": {
        "type": "cache",
        "refresh_probability": 0.1,
        "varies_on": [
            "key"
        ],
        "ttl": 3600
    },
    "model": "text-davinci-003",
    "temperature": 0.7,
    "prompts": [
        {
            "type": "chat",
            "configuration": {
                "role": "user",
                "content": "This is a chat prompt"
            }
        },
        {
            "type": "template",
            "template": {
                "id": "<PROMPT_TEMPLATE_ID>",
                "name": "My Prompt Template",
                "role": "user",
                "status": "draft",
                "version": 1,
                "description": "This is my prompt template",
                "content_type": "text",
                "content": "This is the content of my prompt template",
                "test_data": {
                    "key": "value"
                },
                "script": null,
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "key": {
                            "type": "string"
                        }
                    }
                },
                "project": "<PROJECT_ID>",
                "tags": [],
                "last_published_at": "2023-10-26T22:01:02.178Z",
                "created_by": "user:64c4312a464139a5876f3d3a",
                "updated_by": "user:64c4312a464139a5876f3d3a",
                "created_at": "2023-10-26T22:01:02.178Z",
                "updated_at": "2023-10-26T22:01:02.178Z"
            }
        }
    ],
    "max_tokens": 1024,
    "environment": "<ENVIRONMENT_ID>",
    "restriction": "STANDARD",
    "project": "<PROJECT_ID>",
    "last_published_at": null,
    "created_by": "user:64c4312a464139a5876f3d3a",
    "updated_by": "user:64c4312a464139a5876f3d3a",
    "created_at": "2023-10-26T22:02:48.268Z",
    "updated_at": "2023-10-26T22:02:48.268Z"
}

Code Examples

Create Interaction

curl --location 'https://api.vertesia.io/api/v1/interactions' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "My Interaction",
  "description": "This is my interaction",
  "status": "draft",
  "tags": ["tag1", "tag2"],
  "test_data": {
    "key": "value"
  },
  "result_schema": {
    "type": "object",
    "properties": {
      "key": {
        "type": "string"
      }
    }
  },
  "cache_policy": {
    "type": "cache",
    "refresh_probability": 0.1,
    "varies_on": ["key"],
    "ttl": 3600
  },
  "model": "text-davinci-003",
  "temperature": 0.7,
  "prompts": [
    {
      "type": "chat",
      "configuration": {
        "role": "user",
        "content": "This is a chat prompt"
      }
    },
    {
      "type": "template",
      "template": "<PROMPT_TEMPLATE_ID>"
    }
  ],
  "max_tokens": 1024,
  "environment": "<ENVIRONMENT_ID>",
  "restriction": "STANDARD"
}'

Retrieve Interaction

Endpoint: /interactions/<INTERACTION_ID>

Method: GET

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Description
`<INTERACTION_ID>`	The ID of the Interaction to retrieve.

Example Request

There is no JSON body with this request.

Example Response

{
    "id": "<INTERACTION_ID>",
    "name": "My Interaction",
    "description": "This is my interaction",
    "status": "draft",
    "tags": [
        "tag1",
        "tag2"
    ],
    "test_data": {
        "key": "value"
    },
    "result_schema": {
        "type": "object",
        "properties": {
            "key": {
                "type": "string"
            }
        }
    },
    "cache_policy": {
        "type": "cache",
        "refresh_probability": 0.1,
        "varies_on": [
            "key"
        ],
        "ttl": 3600
    },
    "model": "text-davinci-003",
    "temperature": 0.7,
    "prompts": [
        {
            "type": "chat",
            "configuration": {
                "role": "user",
                "content": "This is a chat prompt"
            }
        },
        {
            "type": "template",
            "template": {
                "id": "<PROMPT_TEMPLATE_ID>",
                "name": "My Prompt Template",
                "role": "user",
                "status": "draft",
                "version": 1,
                "description": "This is my prompt template",
                "content_type": "text",
                "content": "This is the content of my prompt template",
                "test_data": {
                    "key": "value"
                },
                "script": null,
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "key": {
                            "type": "string"
                        }
                    }
                },
                "project": "<PROJECT_ID>",
                "tags": [],
                "last_published_at": "2023-10-26T22:01:02.178Z",
                "created_by": "user:64c4312a464139a5876f3d3a",
                "updated_by": "user:64c4312a464139a5876f3d3a",
                "created_at": "2023-10-26T22:01:02.178Z",
                "updated_at": "2023-10-26T22:01:02.178Z"
            }
        }
    ],
    "max_tokens": 1024,
    "environment": "<ENVIRONMENT_ID>",
    "restriction": "STANDARD",
    "project": "<PROJECT_ID>",
    "last_published_at": null,
    "created_by": "user:64c4312a464139a5876f3d3a",
    "updated_by": "user:64c4312a464139a5876f3d3a",
    "created_at": "2023-10-26T22:02:48.268Z",
    "updated_at": "2023-10-26T22:02:48.268Z"
}

Code Examples

Retrieve Interaction

curl --location 'https://api.vertesia.io/api/v1/interactions/<INTERACTION_ID>' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Update Interaction

Endpoint: /interactions/<INTERACTION_ID>

Method: PUT

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`
`Content-Type`	`application/json`

Path Parameters

Parameter	Description
`<INTERACTION_ID>`	The ID of the Interaction to update.

Input Parameters

Parameter	Data Type	Description
`name`	`string`	The name of the Interaction.
`description`	`string`	The description of the Interaction.
`status`	`InteractionStatus`	The status of the Interaction.
`tags`	`string[]`	The tags of the Interaction.
`test_data`	`JSONObject`	The test data of the Interaction.
`result_schema`	`JSONSchema4`	The result schema of the Interaction.
`cache_policy`	`CachePolicy`	The cache policy of the Interaction.
`model`	`string`	The model of the Interaction.
`temperature`	`number`	The temperature of the Interaction.
`prompts`	`PromptSegmentDef[]`	The prompts of the Interaction.
`max_tokens`	`number`	The maximum number of tokens of the Interaction.
`environment`	`string`	The environment of the Interaction.
`restriction`	`RunDataStorageLevel`	The level of information to store for an Interaction Run.

Example Request

{
  "name": "My Updated Interaction",
  "description": "This is my updated interaction"
}

Example Response

{
    "id": "<INTERACTION_ID>",
    "name": "My Updated Interaction",
    "description": "This is my updated interaction",
    "status": "draft",
    "tags": [
        "tag1",
        "tag2"
    ],
    "test_data": {
        "key": "value"
    },
    "result_schema": {
        "type": "object",
        "properties": {
            "key": {
                "type": "string"
            }
        }
    },
    "cache_policy": {
        "type": "cache",
        "refresh_probability": 0.1,
        "varies_on": [
            "key"
        ],
        "ttl": 3600
    },
    "model": "text-davinci-003",
    "temperature": 0.7,
    "prompts": [
        {
            "type": "chat",
            "configuration": {
                "role": "user",
                "content": "This is a chat prompt"
            }
        },
        {
            "type": "template",
            "template": {
                "id": "<PROMPT_TEMPLATE_ID>",
                "name": "My Prompt Template",
                "role": "user",
                "status": "draft",
                "version": 1,
                "description": "This is my prompt template",
                "content_type": "text",
                "content": "This is the content of my prompt template",
                "test_data": {
                    "key": "value"
                },
                "script": null,
                "inputSchema": {
                    "type": "object",
                    "properties": {
                        "key": {
                            "type": "string"
                        }
                    }
                },
                "project": "<PROJECT_ID>",
                "tags": [],
                "last_published_at": "2023-10-26T22:01:02.178Z",
                "created_by": "user:64c4312a464139a5876f3d3a",
                "updated_by": "user:64c4312a464139a5876f3d3a",
                "created_at": "2023-10-26T22:01:02.178Z",
                "updated_at": "2023-10-26T22:01:02.178Z"
            }
        }
    ],
    "max_tokens": 1024,
    "environment": "<ENVIRONMENT_ID>",
    "restriction": "STANDARD",
    "project": "<PROJECT_ID>",
    "last_published_at": null,
    "created_by": "user:64c4312a464139a5876f3d3a",
    "updated_by": "user:64c4312a464139a5876f3d3a",
    "created_at": "2023-10-26T22:02:48.268Z",
    "updated_at": "2023-10-26T22:06:07.520Z"
}

Code Examples

Update Interaction

curl --location 'https://api.vertesia.io/api/v1/interactions/<INTERACTION_ID>' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "My Updated Interaction",
  "description": "This is my updated interaction"
}'

Delete an Interaction

Endpoint: /interactions/<INTERACTION_ID>

Method: DELETE

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Data Type	Description
INTERACTION_ID	string	The ID of the Interaction to delete.

Example Request

curl --location --request DELETE 'https://api.vertesia.io/api/v1/interactions/<INTERACTION_ID>' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Example Response

{
    "id": "<INTERACTION_ID>"
}

Code Examples

Delete an Interaction

curl --location --request DELETE 'https://api.vertesia.io/api/v1/interactions/<INTERACTION_ID>' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Execute Interaction by ID

Execute an interaction by its ID.

Endpoint: /interactions/<INTERACTION_ID>/execute

Method: POST

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`
`Content-Type`	`application/json`

Path Parameters

Parameter	Description
`<INTERACTION_ID>`	The ID of the interaction to execute

Example Request

{
  "data": {
    "text": "Your text to summarize"
  }
}

Example Response

{
  "id": "64fc927ed21e296148a4a2a1",
  "result": {
    "summary": "This is a sample summary."
  },
  "parameters": {
    "text": "Your text to summarize"
  },
  "interaction": {
    "id": "64fc91b9d21e296148a4a28b",
    "name": "Summarize Text",
    "description": "Generate a summary of the given text.",
    "status": "draft",
    "version": 1,
    "latest": false,
    "tags": [],
    "prompts": [
      {
        "id": "64fc91b9d21e296148a4a289",
        "type": "template",
        "template": {
          "id": "64fc91b9d21e296148a4a288",
          "name": "Summarize Text",
          "role": "user",
          "content_type": "text"
        }
      }
    ],
    "updated_at": "2023-09-07T16:20:30.957Z"
  },
  "environment": {
    "id": "64fc91b9d21e296148a4a28a",
    "name": "OpenAI",
    "provider": "openai",
    "enabled_models": [],
    "default_model": "gpt-3.5-turbo"
  },
  "modelId": "gpt-3.5-turbo",
  "result_schema": {},
  "ttl": 3600,
  "status": "completed",
  "prompt": "Please provide a concise summary of the following text:\n\nYour text to summarize",
  "execution_time": 0.413,
  "created_at": "2023-09-07T16:20:30.545Z",
  "updated_at": "2023-09-07T16:20:30.958Z",
  "account": {
    "id": "64fc910bd21e296148a4a284",
    "name": "My Account"
  },
  "project": {
    "id": "64fc91b9d21e296148a4a287",
    "name": "My Project",
    "account": "64fc910bd21e296148a4a284"
  },
  "config": {},
  "source": {
    "type": "api",
    "label": "SDK Request",
    "principal_type": "user",
    "principal_id": "auth0|64fc910bd21e296148a4a283",
    "client_ip": "::ffff:172.17.0.1"
  },
  "created_by": "user:auth0|64fc910bd21e296148a4a283",
  "updated_by": "user:auth0|64fc910bd21e296148a4a283"
}

Code Examples

Execute Interaction by ID

curl --location --request POST 'https://api.vertesia.io/api/v1/interactions/<INTERACTION_ID>/execute' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "data": {
    "text": "Your text to summarize"
  }
}'

Execute Interaction by Name

The /execute endpoint allows you to execute an Interaction by name.

Endpoint: /execute

Method: POST

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`
`Content-Type`	`application/json`

Input Parameters

Parameter	Data Type	Description
`interaction`	`string`	The interaction endpoint name, optionally appended by an `@` character and a version or tag. If no version or tag is specified, then the latest version is used. Example: `ReviewContract`, `ReviewContract@draft`, `ReviewContract@1`, `ReviewContract@some-tag`.
`data`	`Record<string, any> \| 'memory:${string}'`	The input data for the interaction. If a `@memory` property exists on the input data then the value will be used as the value of a memory pack location and the other properties of the data will contain the memory pack mapping.
`config`	`InteractionExecutionConfiguration`	The configuration for the interaction execution.
`result_schema`	`JSONSchema4`	The JSON schema for the interaction result.
`stream`	`boolean`	Whether to stream the interaction result.
`do_validate`	`boolean`	Whether to validate the interaction input and output.
`tags`	`string \| string[]`	Tags to be added to the execution run.

Example Request

{
  "interaction": "MyInteraction",
  "data": {
    "myVar": "myValue"
  }
}

Example Response

{
  "id": "<INTERACTION_ID>",
  "status": "created"
}

Code Examples

Execute Interaction by Name

curl --location --request POST 'https://api.vertesia.io/api/v1/execute' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "interaction": "MyInteraction",
  "data": {
    "myVar": "myValue"
  }
}'

Execute Interaction Asynchronously

The /execute/async endpoint allows you to asynchronously execute an Interaction by name. You can include an optional callback to webhooks, or run an Interaction as an agent. The payload format extends the one used by the /execute endpoint to seamlessly switch from synchronous to asynchronous execution.

Endpoint: /execute/async

Method: POST

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`
`Content-Type`	`application/json`

Input Parameters

Parameter	Data Type	Description
`type`	`"conversation" \| "interaction"`	Type of execution. Default is `"interaction"`. Use `"conversation"` for running as an agent.
`interaction`	`string`	The interaction endpoint name, optionally appended by an `@` character and a version or tag. If no version or tag is specified, then the latest version is used. Example: `ReviewContract`, `ReviewContract@draft`, `ReviewContract@1`, `ReviewContract@some-tag`.
`data`	`Record<string, any> \| 'memory:${string}'`	The input data for the interaction. If a `@memory` property exists on the input data then the value will be used as the value of a memory pack location and the other properties of the data will contain the memory pack mapping.
`config`	`InteractionExecutionConfiguration`	The configuration for the interaction execution.
`result_schema`	`JSONSchema4`	The JSON schema for the interaction result.
`do_validate`	`boolean`	Whether to validate the interaction input and output.
`tags`	`string \| string[]`	Tags to be added to the execution run.
`notify_endpoints`	`string[]`	Optional array of webhook URLs to notify when the execution completes.

Additional Parameters For Conversation Type (type: "conversation")

Parameter	Data Type	Description
`visibility`	`"private" \| "project"`	Visibility scope. Default is `"project"`.
`interactive`	`boolean`	Whether the conversation should be interactive.
`tool_names`	`string[]`	Tools to use. Use `+` and `-` to add or remove from default.
`disable_interaction_tools`	`boolean`	Whether to disable interaction tools generation.
`max_iterations`	`number`	Maximum iterations. Default is 20 if ≤0.
`search_scope`	`string`	Scope for search tool (`collection` or `null`).
`collection_id`	`string`	Collection ID to use in conjunction with `search_scope`.
`checkpoint_tokens`	`number`	Token threshold in thousands (K) for checkpoints. Default is 150K.
`debug_mode`	`boolean`	Whether to enable debug mode.

Example Request

{
  "type": "interaction",
  "interaction": "MyInteraction",
  "data": {
    "myVar": "myValue"
  },
  "config": {
    "environment": "<ENVIRONMENT_ID>",
    "model": "<MODEL_ID>"
  },
  "notify_endpoints": [
    "https://my-webhook.com/notify"
  ]
}

Example Response

{
    "runId": "<RUN_ID>",
    "workflowId": "<WORKFLOW_ID>"
}

Code Examples

Execute Interaction Asynchronously

curl --location 'https://api.vertesia.io/api/v1/execute/async' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "type": "interaction",
  "interaction": "<INTERACTION_ENDPOINT>",
  "data": {
      "my-param": "my-value"
  },
  "config": {
    "environment": "<ENVIRONMENT_ID>",
    "model": "<MODEL_ID>",
  },
  "notify_endpoints": [
    "https://my-webhook.com/notify"
  ]
}'

List Interactions

Endpoint: /interactions

Method: GET

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Query Parameters

Parameter	Data Type	Description
`name`	`string`	The name of the Interaction.
`version`	`string`	The version of the Interaction.
`tags`	`string`	The tags of the Interaction.
`status`	`InteractionStatus`	The status of the Interaction.
`prompt`	`string`	The prompt of the Interaction.

Example Request

There is no JSON body with this request.

Example Response

[
  {
    "id": "<INTERACTION_ID>",
    "name": "My Interaction",
    "endpoint": "MyInteraction",
    "description": "This is my interaction",
    "status": "draft",
    "version": 1,
    "prompts": [
      {
        "id": "<OBJECT_ID>",
        "type": "chat",
        "template": {
          "id": "<PROMPT_TEMPLATE_ID>",
          "name": "My Prompt Template",
          "role": "user",
          "content_type": "text"
        }
      }
    ],
    "tags": [
      "tag1",
      "tag2"
    ],
    "updated_at": "2023-10-26T22:06:07.520Z"
  }
]

Code Examples

List Interactions

curl --location 'https://api.vertesia.io/api/v1/interactions?name=My%20Interaction&status=draft' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

List Interaction Names

Endpoint: /interactions/names

Method: GET

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Example Request

There is no JSON body with this request.

Example Response

[
  {
    "id": "<INTERACTION_ID>",
    "name": "My Interaction"
  }
]

Code Examples

List Interaction Names

curl --location 'https://api.vertesia.io/api/v1/interactions/names' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Publish Interaction Version

Endpoint: /interactions/<INTERACTION_ID>/publish

Method: POST

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`
`Content-Type`	`application/json`

Path Parameters

Parameter	Description
`<INTERACTION_ID>`	The ID of the Interaction to publish.

Input Parameters

Parameter	Data Type	Description
`visibility`	`InteractionVisibility`	The visibility of the Interaction.
`tags`	`string[]`	The tags of the Interaction.

Example Request

{
  "visibility": "private",
  "tags": [
    "tag1",
    "tag2"
  ]
}

Example Response

{
    "id": "<INTERACTION_ID>",
    "name": "My Interaction",
    "description": "This is my interaction",
    "status": "published",
    "tags": [
        "tag1",
        "tag2"
    ],
    "test_data": {
        "key": "value"
    },
    "result_schema": {
        "type": "object",
        "properties": {
            "key": {
                "type": "string"
            }
        }
    },
    "cache_policy": {
        "type": "cache",
        "refresh_probability": 0.1,
        "varies_on": [
            "key"
        ],
        "ttl": 3600
    },
    "model": "text-davinci-003",
    "temperature": 0.7,
    "prompts": [
        {
            "type": "chat",
            "configuration": {
                "role": "user",
                "content": "This is a chat prompt"
            }
        },
        {
            "type": "template",
            "template": "<PROMPT_TEMPLATE_ID>"
        }
    ],
    "max_tokens": 1024,
    "environment": "<ENVIRONMENT_ID>",
    "restriction": "STANDARD",
    "project": "<PROJECT_ID>",
    "last_published_at": "2023-10-26T22:11:21.131Z",
    "created_by": "user:64c4312a464139a5876f3d3a",
    "updated_by": "user:64c4312a464139a5876f3d3a",
    "created_at": "2023-10-26T22:02:48.268Z",
    "updated_at": "2023-10-26T22:11:21.131Z"
}

Code Examples

Publish Interaction

curl --location 'https://api.vertesia.io/api/v1/interactions/<INTERACTION_ID>/publish' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "visibility": "private",
  "tags": [
    "tag1",
    "tag2"
  ]
}'

List Interaction Versions

List all published versions of an interaction.

Endpoint: /interactions/<INTERACTION_ID>/versions

Method: GET

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Description
`<INTERACTION_ID>`	The ID of the Interaction to fork.

Example Request

There is no JSON body with this request.

Example Response

[
  {
    "id": "64fc9218d21e296148a4a293",
    "name": "Summarize Text",
    "description": "Generate a summary of the given text.",
    "status": "published",
    "version": 1,
    "latest": true,
    "tags": [],
    "prompts": [
      {
        "id": "64fc9218d21e296148a4a291",
        "type": "template",
        "template": {
          "id": "64fc9218d21e296148a4a290",
          "name": "Summarize Text",
          "role": "user",
          "content_type": "text"
        }
      }
    ],
    "updated_at": "2023-09-07T16:19:04.901Z"
  }
]

Code Examples

List the Versions of an Interaction

curl --location --request GET 'https://api.vertesia.io/api/v1/interactions/<INTERACTION_ID>/versions' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Fork Interaction

Endpoint: /interactions/<INTERACTION_ID>/fork

Method: POST

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`
`Content-Type`	`application/json`

Path Parameters

Parameter	Description
`<INTERACTION_ID>`	The ID of the Interaction to fork.

Input Parameters

Parameter	Data Type	Description
`keepTags`	`boolean`	Whether to keep the tags of the original Interaction.
`forkPrompts`	`boolean`	Whether to fork the Prompt Templates used by the Interaction, or reuse the existing Prompt Templates.
`targetProject`	`string`	ID of the destination Project to store the forked interaction.

Example Request

{
  "keepTags": false,
  "forkPrompts": true,
  "targetProject": "64fc91b9d21e296148a4a287"
}

Example Response

{
  "id": "64fc9249d21e296148a4a299",
  "name": "Summarize Text (fork)",
  "endpoint": "SummarizeTextFork",
  "description": "Generate a summary of the given text.",
  "status": "draft",
  "parent": "64fc91b9d21e296148a4a28b",
  "version": 1,
  "tags": [],
  "model": "gpt-3.5-turbo",
  "temperature": 0.7,
  "prompts": [
    {
      "id": "64fc9249d21e296148a4a297",
      "type": "template",
      "template": "64fc9249d21e296148a4a296"
    }
  ],
  "max_tokens": 500,
  "project": "64fc91b9d21e296148a4a287",
  "created_by": "user:auth0|64fc910bd21e296148a4a283",
  "updated_by": "user:auth0|64fc910bd21e296148a4a283",
  "created_at": "2023-09-07T16:19:53.981Z",
  "updated_at": "2023-09-07T16:19:53.981Z"
}

Code Examples

Fork an Interaction

curl --location --request POST 'https://api.vertesia.io/api/v1/interactions/<INTERACTION_ID>/fork' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "keepTags": false,
  "forkPrompts": true,
  "targetProject": "projectId"
}'

List Interaction Forks

List all forks of an interaction.

Endpoint: /interactions/<INTERACTION_ID>/forks

Method: GET

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Description
`<INTERACTION_ID>`	The ID of the Interaction to fork.

Example Request

There is no JSON body with this request.

Example Response

[
  {
    "id": "64fc9249d21e296148a4a299",
    "name": "Summarize Text (fork)",
    "description": "Generate a summary of the given text.",
    "status": "draft",
    "version": 1,
    "latest": false,
    "created_at": "2023-09-07T16:19:53.993Z",
    "updated_at": "2023-09-07T16:19:53.993Z"
  }
]

Code Examples

List the Forks of an Interaction

curl --location --request GET 'https://api.vertesia.io/api/v1/interactions/<INTERACTION_ID>/forks' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Export Interaction

Endpoint: /interactions/export

Method: POST

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`
`Content-Type`	`application/json`

Input Parameters

Parameter	Data Type	Description
`name`	`string`	The name of the Interaction.
`tags`	`string[]`	The tags of the Interaction.
`versions`	`(number \| 'draft' \| 'latest')[]`	The versions of the Interaction.

Example Request

{
  "name": "My Interaction",
  "tags": [
    "tag1",
    "tag2"
  ],
  "versions": [
    1,
    "draft",
    "latest"
  ]
}

Example Response

[
  {
    "id": "<INTERACTION_ID>",
    "name": "My Interaction",
    "description": "This is my interaction",
    "status": "draft",
    "version": 1,
    "latest": true,
    "tags": [
      "tag1",
      "tag2"
    ],
    "prompts": [
      {
        "type": "chat",
        "configuration": {
          "role": "user",
          "content": "This is a chat prompt"
        }
      },
      {
        "type": "template",
        "template": {
          "id": "<PROMPT_TEMPLATE_ID>",
          "name": "My Prompt Template",
          "role": "user",
          "version": 1,
          "status": "draft",
          "content_type": "text",
          "inputSchema": {
            "type": "object",
            "properties": {
              "key": {
                "type": "string"
              }
            }
          }
        }
      }
    ],
    "result_schema": {
      "type": "object",
      "properties": {
        "key": {
          "type": "string"
        }
      }
    },
    "updated_at": "2023-10-26T22:06:07.520Z"
  }
]

Code Examples

Export Interactions

curl --location 'https://api.vertesia.io/api/v1/interactions/export' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
  "name": "My Interaction",
  "tags": [
    "tag1",
    "tag2"
  ],
  "versions": [
    1,
    "draft",
    "latest"
  ]
}'

Generate Interaction

Generate a new interaction based on the description of a task. This endpoint is used by the UI to generate an interaction definition from the description of a task.

Endpoint: /interactions/0/generate-interaction

Method: POST

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`
`Content-Type`	`application/json`

Input Parameters

Parameter	Data Type	Description
`description`	`string`	A functional description of the interaction, including what it will do, the inputs, and the outputs.
`config`	`object`	Execution configuration for running the Interaction, including the environment and model. Currently, this is only supported by Anthropic Claude 3.5 Sonnet

Example Request

{
  "description": "Generate a summary of the given text.",
  "config": {
    "environment": "66fc9249d21e296148a4a2988",
    "model": "arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-3-5-sonnet-20240620-v1:0"
	}
}

Example Response

[
  {
    "name": "Summarize Text",
    "description": "Generate a summary of the given text.",
    "model": "gpt-3.5-turbo-16k",
    "temperature": 0.7,
    "prompts": [
      {
        "type": "template",
        "template": {
          "name": "Summarize Text",
          "role": "user",
          "content_type": "text",
          "content": "Please provide a concise summary of the following text:\n\n{{text}}"
        }
      }
    ],
    "max_tokens": 500,
    "result_schema": {
      "type": "object",
      "properties": {
        "summary": {
          "type": "string"
        }
      },
      "required": [
        "summary"
      ]
    }
  }
]

Code Examples

Generate an Interaction

curl --location --request POST 'https://api.vertesia.io/api/v1/interactions/0/generate-interaction' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "description": "Generate a summary of the given text.",
  "config": {}
}'

Generate Test Data

Generate test data for an interaction. This endpoint is used by the UI to generate test data for an interaction.

Endpoint: /interactions/<INTERACTION_ID>/generate-test-data

Method: POST

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`
`Content-Type`	`application/json`

Path Parameters

Parameter	Description
`<INTERACTION_ID>`	The ID of the Interaction to fork.

Input Parameters

Parameter	Data Type	Description
`message`	`string`	A message providing a hint for what to include in the generated test data.
`message`	`integer`	The number of test data sets to generate.
`config`	`object`	Execution configuration for running the Interaction, including the environment and model.

Example Request

{
  "message": "Generate test data for the interaction",
  "count": 10,
  "config": {
    "environment": "66fc9249d21e296148a4a2988",
    "model": "arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-3-5-sonnet-20240620-v1:0"
	}
}

Example Response

[
  {
    "text": "This is a sample text."
  },
  {
    "text": "This is another sample text."
  },
  {
    "text": "This is yet another sample text."
  },
  {
    "text": "This is the fourth sample text."
  },
  {
    "text": "This is the fifth sample text."
  },
  {
    "text": "This is the sixth sample text."
  },
  {
    "text": "This is the seventh sample text."
  },
  {
    "text": "This is the eighth sample text."
  },
  {
    "text": "This is the ninth sample text."
  },
  {
    "text": "This is the tenth sample text."
  }
]

Code Example:

Generate Test Data for an Interaction

curl --location --request POST 'https://api.vertesia.io/api/v1/interactions/<INTERACTION_ID>/generate-test-data' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "message": "Generate test data for the interaction",
  "count": 10,
  "config": {}
}'

Suggest Prompt Improvements

Suggest improvements for a prompt. This endpoint is used by the UI to suggest improvements for a prompt.

Endpoint: /interactions/<INTERACTION_ID>/suggest-prompt-improvements

Method: POST

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`
`Content-Type`	`application/json`

Path Parameters

Parameter	Description
`<INTERACTION_ID>`	The ID of the Interaction to fork.

Input Parameters

Parameter	Data Type	Description
`config`	`object`	Execution configuration for running the Interaction, including the environment and model.

Example Request

{
  "config": {
    "environment": "66fc9249d21e296148a4a2988",
    "model": "arn:aws:bedrock:us-east-1::foundation-model/anthropic.claude-3-5-sonnet-20240620-v1:0"
	}
}

Example Response

{
  "result": "Here are some suggestions for improving your prompt:\n\n* Be more specific about what you want the model to do.\n* Provide more context for the model.\n* Use a more consistent tone and style."
}

Code Example:

Suggest Improvements to the Prompt

curl --location --request POST 'https://api.vertesia.io/api/v1/interactions/<INTERACTION_ID>/suggest-prompt-improvements' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "config": {}
}'