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.

Interaction

  {
    "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 Interaction
POST /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 the EventSource API. In Node.js you can use a sevrer side implementation of the EventSource API like eventsource.
The event stream will sent the following events:

message - a new chunk of the result data is available. The event data property is the chunk as a string.
close - the execution is completed. The event data property is the final execution reuslt object which can either has a status of completed or failed.

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 interactions
GET /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 interaction
GET /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 versions
GET /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 version
POST /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 versions
GET /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 version
POST /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 Data
POST /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"
  }
]