Board Run API Endpoint Protocol

Describes how to use the Board Run API Endpoint. This API endpoint is different from the invoke BSE endpoint in that it follows the "Run" mode semantics.

Link

Endpoint

POST {API_URL}

When using Board Server, it will be the URL of the board, with the json extension replaced by api/run. For example a board at this location:

http://mycoolboardserver.example.com/boards/@pluto/chat-agent.bgl.json

Will have the API endpoint at:

http://mycoolboardserver.example.com/boards/@pluto/chat-agent.bgl.api/run

Link

Authentication

Authentication is performed using an API key.

• Include the API key in the request body with the key $key.

Link

Request

Link

Headers

• Content-Type: application/json

Link

Body

The request body should be a JSON object with the following structure:

{
  "$key": "YOUR_API_KEY",
  "$next": "OPTIONAL_RESUMPTION_STATE",
  ...inputs
}

• $key (string, required): The API key. When accessing this endpoint on a Board Server, the Board Server API Key.
• $next (string, optional): The state to resume from, if continuing a previous interaction.
• ...inputs (object, required): The inputs to the board. The structure of this object depends on the specific board being run and must match the schema supplied in the input request.

Example input for initiating request:

{
  "$key": "YOUR_API_KEY",
  "context": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Hello, my name is Pluto! When talking with me, please start by addressing me by name"
        }
      ]
    }
  ]
}

Example input for continuing request:

{
  "$key": "YOUR_API_KEY",
  "$next": "RESUME_FROM_THIS_STATE",
  "text": {
    "role": "user",
    "parts": [{ "text": "What is Breadboard?" }]
  }
}

You can also initiate request with no inputs. In this case, the response will contain the input type response and supply the schema:

{
  "$key": "YOUR_API_KEY"
}

Link

Response

The response is a Server-Sent Events (SSE) stream. Each event in the stream is a serialized JSON object prefixed by data: and separated by \n\n.

Link

Event Format

Each event is an array with two elements: [type, data]

The type can be one of the following:

1. "input"
2. "output"
3. "error"

Link

Event Types

1. Input Event

["input", {
  "schema": { ... },
  "next": "RESUMPTION_STATE"
}]

• schema (object): Describes the expected input schema.
• next (string): A token representing the state to use when resuming the interaction.

2. Output Event

["output", {
  "output": [ ... ]
}]

• output (array): Contains the output data from the board.

3. Error Event

["error", "ERROR_MESSAGE"]

• The second element is a string describing the error that occurred.

Link

Error Handling

• If an error occurs during processing, an error event will be sent in the SSE stream.
• HTTP status codes are used to indicate request-level errors (e.g., 400 for bad requests, 401 for authentication errors).

Link

Resuming Interactions

To continue an interaction:

1. Extract the next value from the most recent input event.
2. Include this value as $next in your next request body.

Link

Examples

Link

Initiating a conversation

Request:

POST {API_URL} HTTP/1.1
Content-Type: application/json

{
  "$key": "YOUR_API_KEY",
  "context": [
    {
      "role": "user",
      "parts": [{ "text": "Hello, my name is Dimitri! When talking with me, please start by addressing me by name" }]
    }
  ]
}

Link

Continuing a conversation

Request:

POST {API_URL} HTTP/1.1
Content-Type: application/json

{
  "$key": "YOUR_API_KEY",
  "$next": "PREVIOUS_NEXT_VALUE",
  "text": {
    "role": "user",
    "parts": [{ "text": "What is Breadboard?" }]
  }
}

Link

Notes

• The specific structure of inputs and outputs may vary depending on the board being run.
• Always handle the SSE stream properly, parsing each event and acting accordingly based on its type.
• Store the next value from input events to enable conversation continuity.