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:

  1. blocking: the execution is started and the response is returned when the execution is completed.
  2. 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"
  }
]

Was this page helpful?