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://studio-server-production.api.becomposable.com/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://studio-server-production.api.becomposable.com/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://studio-server-production.api.becomposable.com/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"
}'

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

curl --location --request POST 'https://studio-server-production.api.becomposable.com/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 Interactions 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 name and suffixed by an optional tag or version separated from the name using a `@` character. If no version/tag part 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

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

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",
    "latest": true,
    "description": "This is my interaction",
    "schema": null,
    "status": "draft",
    "prompts": [
      {
        "id": "<OBJECT_ID>",
        "type": "chat",
        "template": {
          "id": "<PROMPT_TEMPLATE_ID>",
          "name": "My Prompt Template",
          "role": "user",
          "content_type": "text"
        }
      }
    ],
    "updated_at": "2023-10-26T22:06:07.520Z",
    "tags": [
      "tag1",
      "tag2"
    ],
    "version": 1
  }
]

Code Examples

List Interactions

curl --location 'https://studio-server-production.api.becomposable.com/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://studio-server-production.api.becomposable.com/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://studio-server-production.api.becomposable.com/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://studio-server-production.api.becomposable.com/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://studio-server-production.api.becomposable.com/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://studio-server-production.api.becomposable.com/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://studio-server-production.api.becomposable.com/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 Composable interaction definition. This endpoint is used by the UI to generate an interaction definition from a description.

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://studio-server-production.api.becomposable.com/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://studio-server-production.api.becomposable.com/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://studio-server-production.api.becomposable.com/api/v1/interactions/<INTERACTION_ID>/suggest-prompt-improvements' \
--header 'Authorization: Bearer <YOUR_JWT_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "config": {}
}'