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

Requirements: User must have interaction:write permission.

Headers

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

Input Parameters

Parameter	Data Type	Description
`name` (Required)	`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` (Required)	`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 --request POST 'https://api.vertesia.io/api/v1/interactions' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "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

Requirements: User must have interaction:read permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Data Type	Description
`<INTERACTION_ID>` (Required)	`string`	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 --request GET 'https://api.vertesia.io/api/v1/interactions/<INTERACTION_ID>' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Update Interaction

Endpoint: /interactions/<INTERACTION_ID>

Method: PUT

Requirements: User must have interaction:write permission.

Headers

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

Path Parameters

Parameter	Data Type	Description
`<INTERACTION_ID>` (Required)	`string`	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 --request PUT 'https://api.vertesia.io/api/v1/interactions/<INTERACTION_ID>' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "name": "My Updated Interaction",
  "description": "This is my updated interaction"
}'

Delete an Interaction

Endpoint: /interactions/<INTERACTION_ID>

Method: DELETE

Requirements: User must have interaction:delete permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Data Type	Description
`<INTERACTION_ID>` (Required)	`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

Requirements: User must have interaction:execute permission.

Headers

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

Path Parameters

Parameter	Data Type	Description
`<INTERACTION_ID>` (Required)	`string`	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

Requirements: User must have interaction:execute permission.

Headers

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

Input Parameters

Parameter	Data Type	Description
`interaction` (Required)	`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

Requirements: User must have interaction:execute permission.

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` (Required)	`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 \| WebHookSpec)[]`	Optional array of webhook URLs or webhook specifications to notify when the execution completes. Can be simple URL strings or objects with `url`, `headers`, `data`, and `result_path` fields for enhanced control.

WebHookSpec Object

Parameter	Data Type	Description
`url` (Required)	`string`	The webhook URL to call.
`version`	`number`	API version for the webhook payload format.
`headers`	`Record<string, string>`	Custom HTTP headers to include in the webhook request.
`data`	`Record<string, any>`	Custom data to include in the webhook payload. When provided, the workflow result is nested at `result_path` (defaults to `"result"`) to prevent field collisions.
`result_path`	`string`	Custom path where the workflow result should be nested when custom data is provided. Defaults to `"result"`.

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 1000, Maximum is 1000, Minimum is 50.
`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://simple-webhook.com/notify",
    {
      "url": "https://advanced-webhook.com/notify",
      "headers": {
        "Authorization": "Bearer token123",
        "X-Custom-Header": "custom-value"
      },
      "data": {
        "customer_id": "12345",
        "priority": "high"
      },
      "result_path": "workflow_result"
    }
  ]
}

Example Response

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

Code Examples

Execute Interaction Asynchronously

curl --location --request POST '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

Requirements: User must have interaction:read permission.

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 --request GET '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

Requirements: User must have interaction:read permission.

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 --request GET 'https://api.vertesia.io/api/v1/interactions/names' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Resolve Interaction Execution Info

Resolve an interaction by ID or name and return the execution info with the resolved environment and model that would be used at execution time. This is useful when you need to know which environment and model will be used before executing an interaction, especially when multiple fallback sources exist (interaction settings, project defaults, environment defaults).

Endpoint: /interactions/resolve/<NAME_OR_ID>

Method: GET

Requirements: User must have interaction:read permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Data Type	Description
`<NAME_OR_ID>` (Required)	`string`	The interaction ID (MongoDB ObjectId) or endpoint name. Can include version/tag suffix (e.g., `ReviewContract@1`, `ReviewContract@draft`). The `@` character should be URL-encoded as `%40`.

Query Parameters

Parameter	Data Type	Description
`environment`	`string`	Optional environment ID to use for resolution. If provided, this environment will be used instead of the default resolution cascade.
`model`	`string`	Optional model to use for resolution. If provided, this model will be used and `model_source` will be `config`.

Name Resolution Formats

The <NAME_OR_ID> parameter accepts multiple formats:

Format	Example	Description
MongoDB ObjectId	`66b9149c26dc74d6b5187d27`	Direct interaction ID lookup
Endpoint name	`ReviewContract`	Resolves to the latest published version
Name with version	`ReviewContract%401`	Resolves to specific version number (URL-encoded `@`)
Name with tag	`ReviewContract%40draft`	Resolves to draft or tagged version

ModelSource Values

The model_source field indicates where the resolved model configuration came from:

Value	Description
`config`	Model was explicitly provided in execution config
`interaction`	Model comes from the interaction definition
`environmentDefault`	Model comes from environment's `default_model`
`projectSystemDefault`	Model comes from project system interaction defaults
`projectBaseDefault`	Model comes from project base defaults
`projectModalityDefault`	Model comes from project modality-specific defaults
`projectLegacyDefault`	Model comes from legacy project defaults

Example Request

There is no JSON body with this request.

Example Response

{
  "id": "66b9149c26dc74d6b5187d27",
  "name": "ReviewContract",
  "version": 3,
  "status": "published",
  "tags": ["production", "legal"],
  "resolved": {
    "environment": {
      "id": "66fc9249d21e296148a4a298",
      "name": "Production OpenAI",
      "provider": "openai"
    },
    "model": "gpt-4-turbo",
    "model_source": "interaction"
  }
}

Code Examples

Resolve Interaction Execution Info

# Resolve by ID
curl --location --request GET 'https://api.vertesia.io/api/v1/interactions/resolve/66b9149c26dc74d6b5187d27' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

# Resolve by name (latest version)
curl --location --request GET 'https://api.vertesia.io/api/v1/interactions/resolve/ReviewContract' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

# Resolve by name with version (note: @ is URL-encoded as %40)
curl --location --request GET 'https://api.vertesia.io/api/v1/interactions/resolve/ReviewContract%40draft' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

# Resolve with specific environment and model
curl --location --request GET 'https://api.vertesia.io/api/v1/interactions/resolve/ReviewContract?environment=<ENV_ID>&model=gpt-4-turbo' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>'

Publish Interaction Version

Endpoint: /interactions/<INTERACTION_ID>/publish

Method: POST

Requirements: User must have interaction:write permission.

Headers

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

Path Parameters

Parameter	Data Type	Description
`<INTERACTION_ID>` (Required)	`string`	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 --request POST 'https://api.vertesia.io/api/v1/interactions/<INTERACTION_ID>/publish' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "visibility": "private",
  "tags": [
    "tag1",
    "tag2"
  ]
}'

List Interaction Versions

List all published versions of an interaction.

Endpoint: /interactions/<INTERACTION_ID>/versions

Method: GET

Requirements: User must have interaction:read permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Data Type	Description
`<INTERACTION_ID>` (Required)	`string`	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

Requirements: User must have interaction:write permission.

Headers

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

Path Parameters

Parameter	Data Type	Description
`<INTERACTION_ID>` (Required)	`string`	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

Requirements: User must have interaction:read permission.

Headers

Header	Value
`Authorization`	`Bearer <YOUR_JWT_TOKEN>`

Path Parameters

Parameter	Data Type	Description
`<INTERACTION_ID>` (Required)	`string`	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

Requirements: User must have interaction:read permission.

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 --request POST 'https://api.vertesia.io/api/v1/interactions/export' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "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

Requirements: User must have interaction:write permission.

Headers

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

Input Parameters

Parameter	Data Type	Description
`description` (Required)	`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

Requirements: User must have interaction:write permission.

Headers

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

Path Parameters

Parameter	Data Type	Description
`<INTERACTION_ID>` (Required)	`string`	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.
`count`	`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

Requirements: User must have interaction:write permission.

Headers

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

Path Parameters

Parameter	Data Type	Description
`<INTERACTION_ID>` (Required)	`string`	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": {}
}'