Interactions
The endpoints managing interactions resources are located under the /interactions
path.
Interactions define tasks for the generative model to perform and are exposed as APIs to be consumed by your applications.
The interaction object
An Interaction is composed of Prompt Segments, a Schema (optional), and Configuration Parameters.
Properties
- Name
id
- Type
- string
- Description
Unique identifier for the interaction definition.
- Name
name
- Type
- string
- Description
Display name of the interaction.
- Name
description
- Type
- string
- Description
Detailed description of the interaction.
- Name
status
- Type
- InteractionStatus
- Description
Current status of the interaction.
- Name
test_data
- Type
- JSONObject
- Description
Test data used for checking the interaction's functionality.
- Name
schema
- Type
- JSONSchema4
- Description
JSON Schema to validate the interaction's output.
- Name
cache_policy
- Type
- CachePolicy
- Description
Policy determining how the results are cached.
- Name
model
- Type
- string
- Description
Identifier of the generative AI model to be used.
- Name
temperature
- Type
- number
- Description
Sampling temperature to control randomness of the model's output.
- Name
prompts
- Type
- PromptSegment[]
- Description
Array of segments used to construct the full prompt for the model.
- Name
max_tokens
- Type
- number
- Description
Maximum number of tokens (words/characters) for the model to generate in the output.
- Name
environment
- Type
- string | ExecutionEnvironmentRef
- Description
Execution environment where the interaction runs. Can be a string identifier or a reference to an execution environment.
- Name
project
- Type
- string | ProjectRef
- Description
Project associated with the interaction. Can be a string identifier or a reference to a project.
- Name
created_at
- Type
- Date
- Description
Date and time when the interaction was created.
- Name
updated_at
- Type
- Date
- Description
Date and time when the interaction was last updated.
{
"name": "Update API Documentation",
"status": "draft",
"prompts": [
{
"type": "template",
"template": {
"role": "system",
"name": "App Context",
"content_type": "jst",
"id": "6534dd4b9f9ba90d2dadbeb2"
},
"id": "6534eed79f9ba90d2dadbf4b"
},
{
"type": "template",
"template": {
"role": "system",
"name": "TypeScript Interface",
"content_type": "jst",
"id": "6534ddc09f9ba90d2dadbebc"
},
"id": "6534eed79f9ba90d2dadbf4c"
},
{
"type": "template",
"template": {
"role": "system",
"name": "Client API Resource",
"content_type": "jst",
"id": "6534ece59f9ba90d2dadbf07"
},
"id": "6534eed79f9ba90d2dadbf4d"
},
{
"type": "template",
"template": {
"role": "system",
"name": "Existing Documentation",
"content_type": "jst",
"id": "6534dd879f9ba90d2dadbeb7"
},
"id": "6534eed79f9ba90d2dadbf4e"
}
],
"updated_at": "2023-10-22T12:29:14.072Z",
"id": "6534ec0c9f9ba90d2dadbecc"
}
Execute an InteractionPOST /interactions/:interactionId/execute
This endpoint is similar to /runs/execute
but, for convenience, it is exposed on the interaction resource path.
This endpoint is creating an execution run by starting the execution of an interaction. There are 2 modes of execution:
- blocking: the execution is started and the response is returned when the execution is completed.
- streaming: the execution is started and the response is returned immediately as an execution run in
created
state.
The client must then start the execution by requesting an event strean as specified by the Server-Sent-Events.
In the browser you can do this by using theEventSource
API. InNode.js
you can use a sevrer side implementation of theEventSource
API like eventsource.
The event stream will sent the following events:
message
- a new chunk of the result data is available. The eventdata
property is the chunk as a string.close
- the execution is completed. The eventdata
property is the final execution reuslt object which can either has a status ofcompleted
orfailed
.
To start streaming the execution you should perform a GET request on /runs/:runId/stream
.
Parameters
- Name
stream
- Type
- boolean
- Modifier
- optional
- Description
Wheter or not to stream the execution. Default is
false
.
- Name
data
- Type
- object
- Modifier
- optional
- Description
The input data to use top generate the prompt.
- Name
tags
- Type
- string
- Modifier
- optional
- Description
The tags to add to the execution run.
- Name
config
- Type
- object
- Modifier
- optional
- Description
A configuration object to customize the execution.
- Name
environment
- Type
- string
- Modifier
- optional
- Description
An execution evnvironemnt ID to be used to generate the test data. If not specified the default interaction environment will be used.
- Name
model
- Type
- string
- Modifier
- optional
- Description
The model to be used to execute the interaction. If not specified the default model of the environment is used.
- Name
temperature
- Type
- number
- Modifier
- optional
- Description
The temperature to be used to execute the data. Defaults to 0.7.
- Name
max_tokens
- Type
- number
- Modifier
- optional
- Description
The maximum number of tokens to be used when generating the result.
- Name
formatter
- Type
- number
- Modifier
- optional
- Description
A custom formatter to use.
Returns
An execution run object.
Request
curl https://api.composableprompts.com/api/v1/interactions/{interaction_id}/execute \
-H "Accept: application/json"
-H "Authorization: Bearer {token}"
-X POST
-d {...}
Response
{
result: {
color: "blue"
},
parameters: {
object: "car"
},
tags: [],
environment: "654dfa3109676ad3b8631e24",
interaction: "6554cf617eae1c28ef5f3d40",
modelId: "gpt-4",
status: "completed",
ttl: 3600,
source: {
type: "api",
label: "Key Created On 2023-10-24 16:31:28 via API",
principal_type: "apikey",
principal_id: "653772d5d73c5ac92045df97",
client_ip: "::1"
},
account: "652d77895674c387e105948c",
project: "654df9de09676ad3b8631dc3",
config: {
environment: "654dfa3109676ad3b8631e24",
model: "gpt-4",
id: "656486b6958d9210bae70291"
},
input_embedding: [],
result_embedding: [],
created_at: "2023-11-27T12:08:22.691Z",
updated_at: "2023-11-27T12:08:23.925Z",
execution_time: 1100,
token_use: {
prompt: 51,
result: 9,
total: 60
},
prompt: [
{
content: "\n What color is the car?\n",
role: "user"
}
],
id: "656486b6958d9210bae70290"
}
List interactionsGET /interactions
Get the list of interactions in the current project. \
Parameters
- Name
status
- Type
- InteractionStatus
- Modifier
- optional
- Description
Filter by interaction status. Possible values are: "draft" | "published" | "archived"
- Name
name
- Type
- string
- Modifier
- optional
- Description
Filter by interaction name. Can be used to get the versions of a specific interaction.
- Name
version
- Type
- number
- Modifier
- optional
- Description
Filter by a specific version number.
- Name
tags
- Type
- string
- Modifier
- optional
- Description
A comma separated list of tags to filter by
Returns
A list of interaction references. An interaction reference is a subset of the interaction object.
Request
curl https://api.composableprompts.com/api/v1/interactions \
-H "Accept: application/json"
-H "Authorization: Bearer {token}"
Response
[
{
"name": "What Color",
"status": "draft",
"prompts": [
{
"type": "template",
"template": {
"role": "user",
"name": "WhatColor",
"content_type": "jst",
"id": "65577641108a03f326f30d94"
},
"id": "65577647108a03f326f30d9c"
}
],
"updated_at": "2023-11-17T14:23:18.122Z",
"description": "reply with what is the color of the object requested ",
"id": "655775f9108a03f326f30d89"
},
...
]
Retrieve an interactionGET /interactions/:interactionId
Get an interaction object given its ID.
Parameters
No parameters.
Returns
An interaction object.
Request
curl https://api.composableprompts.com/api/v1/interactions/655775f9108a03f326f30d89 \
-H "Accept: application/json"
-H "Authorization: Bearer {token}"
Response
{
"name": "What Color",
"status": "draft",
"latest": false,
"visibility": "private",
"version": 1,
"tags": [],
"model": "gpt-4-1106-preview",
"temperature": 0.7,
"environment": "654dfa3109676ad3b8631e24",
"project": "654df9de09676ad3b8631dc3",
"prompts": [
{
"type": "template",
"template": {
"role": "user",
"name": "WhatColor",
"status": "draft",
"latest": false,
"version": 1,
"content_type": "jst",
"content": "return `\n What is the color of the following entity: ${object}.\n`",
"test_data": {
"object": "sky"
},
"inputSchema": {
"type": "object",
"properties": {
"object": {
"type": "string"
}
},
"required": [
"object"
]
},
"project": "654df9de09676ad3b8631dc3",
"created_at": "2023-11-17T14:18:41.016Z",
"updated_at": "2023-11-18T09:42:37.736Z",
"id": "65577641108a03f326f30d94"
},
"id": "65577647108a03f326f30d9c"
}
],
"created_at": "2023-11-17T14:17:29.062Z",
"updated_at": "2023-11-17T14:23:18.122Z",
"description": "reply with what is the color of the object requested ",
"max_tokens": 100,
"resultSchema": {
"type": "object",
"properties": {
"color": {
"type": "string"
}
},
"required": [
"color"
]
},
"test_data": {
"object": "sky"
},
"id": "655775f9108a03f326f30d89"
}
List interaction versionsGET /interactions/:interactionId/versions
List the interaction versions for a given interaction ID.
Parameters
No parameters.
Returns
An list of version references. A version reference is a subset of an interaction object cotn aining only the information related to the version.
Request
curl https://api.composableprompts.com/api/v1/interactions/654dfa4d09676ad3b8631e39/versions \
-H "Accept: application/json"
-H "Authorization: Bearer {token}"
Response
[
{
"name": "Review Contract",
"status": "published",
"latest": true,
"version": 1,
"created_at": "2023-11-10T16:24:15.452Z",
"updated_at": "2023-11-10T16:24:15.452Z",
"id": "654e592f1501f6d3e4f97a22"
},
...
]
Publish a versionPOST /interactions/:interactionId/publish
Create a new interaction version.
Parameters
- Name
visibility
- Type
- string
- Modifier
- optional
- Description
Whether the interaction version should be visible to other orgamizations. Can be one of "private" or "public". Defaults to "private".
- Name
tags
- Type
- string[]
- Modifier
- optional
- Description
An array of tags to associate with the interaction version.
Returns
The interaction version object.
Request
curl https://api.composableprompts.com/api/v1/interactions/6554cf617eae1c28ef5f3d40/publish \
-X POST
-H "Accept: application/json"
-H "Authorization: Bearer {token}"
-d '{"visibility": "public", "tags": ["v2"]}'
Response
{
"name": "WhatName",
"status": "published",
"parent": "6554cf617eae1c28ef5f3d40",
"latest": true,
"visibility": "public",
"version": 2,
"tags": [
"v2"
],
"model": "cohere.command-text-v14",
"temperature": 0.7,
"environment": "655660c9f19a49a47106075a",
"project": "654df9de09676ad3b8631dc3",
"prompts": [
{
"type": "template",
"template": "656080ad7cf620dc659cf395",
"id": "656080ad7cf620dc659cf39a"
}
],
"test_data": {
"object": "sky"
},
"resultSchema": {
"type": "object",
"properties": {
"color": {
"type": "string"
}
},
"required": [
"color"
]
},
"formatter": "openai",
"max_tokens": 700,
"created_at": "2023-11-24T10:53:33.939Z",
"updated_at": "2023-11-24T10:53:33.939Z",
"id": "656080ad7cf620dc659cf399"
}
List interaction versionsGET /interactions/:interactionId/versions
List the interaction versions for a given interaction ID.
Parameters
No parameters.
Returns
An list of version references. A version reference is a subset of an interaction object cotn aining only the information related to the version.
Request
curl https://api.composableprompts.com/api/v1/interactions/654dfa4d09676ad3b8631e39/versions \
-H "Accept: application/json"
-H "Authorization: Bearer {token}"
Response
[
{
"name": "Review Contract",
"status": "published",
"latest": true,
"version": 1,
"created_at": "2023-11-10T16:24:15.452Z",
"updated_at": "2023-11-10T16:24:15.452Z",
"id": "654e592f1501f6d3e4f97a22"
},
...
]
Publish a versionPOST /interactions/:interactionId/publish
Create a new interaction version.
Parameters
- Name
visibility
- Type
- string
- Modifier
- optional
- Description
Whether the interaction version should be visible to other orgamizations. Can be one of "private" or "public". Defaults to "private".
- Name
tags
- Type
- string[]
- Modifier
- optional
- Description
An array of tags to associate with the interaction version.
Returns
The interaction version object.
Request
curl https://api.composableprompts.com/api/v1/interactions/6554cf617eae1c28ef5f3d40/publish \
-X POST
-H "Accept: application/json"
-H "Authorization: Bearer {token}"
-d '{"visibility": "public", "tags": ["v2"]}'
Response
{
"name": "WhatName",
"status": "published",
"parent": "6554cf617eae1c28ef5f3d40",
"latest": true,
"visibility": "public",
"version": 2,
"tags": [
"v2"
],
"model": "cohere.command-text-v14",
"temperature": 0.7,
"environment": "655660c9f19a49a47106075a",
"project": "654df9de09676ad3b8631dc3",
"prompts": [
{
"type": "template",
"template": "656080ad7cf620dc659cf395",
"id": "656080ad7cf620dc659cf39a"
}
],
"test_data": {
"object": "sky"
},
"resultSchema": {
"type": "object",
"properties": {
"color": {
"type": "string"
}
},
"required": [
"color"
]
},
"formatter": "openai",
"max_tokens": 700,
"created_at": "2023-11-24T10:53:33.939Z",
"updated_at": "2023-11-24T10:53:33.939Z",
"id": "656080ad7cf620dc659cf399"
}
Generate Test DataPOST /interactions/:interactionId/generate-test-data
Generate test data from the input schema of an interaction.
Parameters
- Name
count
- Type
- number
- Modifier
- optional
- Description
How many test data samples to generate. Defaults to 1.
- Name
message
- Type
- string
- Modifier
- optional
- Description
An optional hint for the generator.
- Name
config
- Type
- object
- Modifier
- required
- Description
- Name
environment
- Type
- string
- Modifier
- required
- Description
An execution evnvironemnt ID to be used to generate the test data.
- Name
model
- Type
- string
- Modifier
- optional
- Description
The model to be used to generate the test data. If not specified the default model of the environment is used.
- Name
temperature
- Type
- number
- Modifier
- optional
- Description
The temperture to be used to generate the test data. Defaults to 0.7.
- Name
max_tokens
- Type
- number
- Modifier
- optional
- Description
The maximum number of tokens to be used when generating the test data.
- Name
formatter
- Type
- number
- Modifier
- optional
- Description
A custom formatter to use.
Returns
An array of generated objects or strings
Request
curl https://api.composableprompts.com/api/v1/interactions/6554cf617eae1c28ef5f3d40/generate-test-data \
-X POST
-H "Accept: application/json"
-H "Authorization: Bearer {token}"
-d '{...}'
Response
[
{
object: "sky"
}, {
object: "banana"
}, {
object: "grass"
}, {
object: "cherry"
}
]