🚪Portals

Your gateway to the full potential of Ai

Overview

Portal name & api

Portals are the entry points for your app into the world of Ai, and they empower you to make changes to your Ai stack with just a few clicks. Most of the time we recommend having one portal per Ai feature in your app.

Each portal can have multiple different versions, and can be thought of as the meta-data for an individual Ai feature. Each version of a portal will then contain the guts of the actual Ai feature, and is where you'll define the Ai provider, configuration, and most importantly the prompt that'll be used.

Version

Version detail card

The portal version is where data for how the Ai will process a request lives. Here you select the,

• Ai Provider (OpenAI, Anthropic, etc)

• Ai Provider settings (temperature, model, etc)

• Version Name (whatever your heart desires)

At the top left, you can see the status (see Publishing) and the score (see #score)

And most important of all, the prompt

Prompt

The prompt is the meat-and-potatoes of interacting with an Ai. This is how you phrase your request / system prompt to the Ai, and is the most important level you have in guiding the output that it produces.

Variables

Prompt's also include variables, which can be thought of as wild-card data. You'll eventually inject into the portal during each request via the easybeam api. Every time you use a variable it's stored in your team's variable list, which can be edited and accessed in team settings/variables.

Previewing

Version preview

We encourage you to test out your versions and play around with the Ai providers, settings, and prompt, so we built this helpful widget in order to test the response that the Ai. You can inject values for all the variables at the top, and get an idea of the output and the cost of a request.

It's important to note that we allow you to preview a version with all the Ai providers we list here, for free! But when eventually publish your version, you'll have to connect to your selected Ai service to Easybeam (more on that later).

Publishing

In order to make this version accessible to the Easybeam API, you'll have to first mark it as ready, and then publish it. This processes makes sure you've set everything up correctly before trying to connect to the API.

When you create a new version in the same portal, and realize you've made it even better than your last version, then publishing it will cause all API traffic to that portal to be rerouted to the newly published version. And just like that, you've updated your Ai without any code changed!

Important! You can't edit the version that's currently live! So we recommend creating a new version to test things out before trying to publish it any new content.

Access Tokens

You'll need an access token in order to integrate Easybeam into your app. You can generate one (or as many as you like) in settings / access tokens.

Reviews / Score

Your users also have the option to review the responses they receive from the Ai. This would usually take the form of a star rating or thumbs up/down after an Ai feature and/or free-text dialogue box. The score for each version is calculated on the averaged based on the reviews it receives. You can see all reviews by clicking on the star that displays the version's score in the version detail card.

See more Reviews / Score

Get a chat completion from a portal

This endpoint processes a chat interaction within a specified portal. It can handle both streaming and non-streaming requests based on the input parameters. For demo purposes, use the portal ID "LZS15".

POSThttps://api.easybeam.ai/v1/portal/{id}

Authorization

BearerAuth

Path parameters

id*string

Unique identifier for the portal. Use "LZS15" for demo testing.

Example: "LZS15"

Body

application/json

Payload containing the chat details and parameters for processing

variablesobject

Variables for the Portal. These will be used to replace the placeholders in your portal's prompt.

chatIdnullable string

Identifier for the chat session. Start an interaction with this endpoint with this as null, and we'll respond with a new ChatId in the response, which you can then use in future requests if a user's adding messages in the same session (i.e. if it's a chat-feature). This ChatId is also used when using the Reviews API.

Example: "chat-67890"

messagesarray of ChatMessage (object)

List of messages in the chat

streamboolean

Whether to stream the response. If this is true then the response will come back as a SSE stream.

Example: false

userIdnullable string

ID of the user interacting with the portal. This comes from your application, and can be used to identify users in our logs.

Example: "user-54321"

consolidateStreamnullable boolean

Whether to consolidate the stream (only valid if used in a streaming request). If this is true then we'll automatically append the content of the new message streaming together, so you don't have to deal with appending the new message together yourself.

Example: false

Response

200400401

Portal interaction successful

Body

application/json

newMessageChatMessage (object)

chatIdstring

Identifier for the chat session.

Example: "chat-67890"

streamFinishednullable boolean

Indicates if the streaming has finished.

Example: false

Request

JavaScriptCurlPython

const response = await fetch('https://api.easybeam.ai/v1/portal/{id}', {
    method: 'POST',
    headers: {
      "Authorization": "Bearer JWT",
      "Content-Type": "application/json"
    },
    body: JSON.stringify({
      "variables": {
        "animal": "aardvark"
      },
      "chatId": null,
      "messages": [],
      "stream": false,
      "userId": "demo-user-123",
      "consolidateStream": false
    }),
});
const data = await response.json();

Response

200400401

{
  "newMessage": {
    "content": "Hello, how can I assist you today?",
    "role": "USER",
    "providerId": "openai",
    "createdAt": "2024-04-27T12:34:56Z",
    "id": "msg-1",
    "inputTokens": 150.5,
    "outputTokens": 200.75
  },
  "chatId": "chat-67890",
  "streamFinished": false
}