Endpoints

Read Current Message

Once you have a Cloud API key, you can use it to get the current message. The size of the array in the layout will depend on what type of board you are using, or whether your API key is for a Note Array.

Path

https://cloud.vestaboard.com/

Method

GET

Headers

X-Vestaboard-Token
Content-Type : "application/json"

Example Request

CURL
Javascript

curl -H "X-Vestaboard-Token: YOUR_API_KEY" -H "Content-Type: application/json" https://cloud.vestaboard.com/

await fetch("https://cloud.vestaboard.com/", {
  headers: {
    "Content-Type": "application/json",
    "X-Vestaboard-Token": "YOUR_API_KEY",
  },
  method: "GET",
}).then((res) => res.json());

Example Response

Flagship:

{
  "currentMessage": {
    "layout": "[[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],[0,0,0,0,0,8,5,12,12,15,0,23,15,18,12,4,0,0,0,0,0,0],[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]]",
    "id": "172c7808-52db-4eb9-9ecf-505bd00436bc"
  }
}

Vestaboard Note:

{
  "currentMessage": {
    "layout": "[[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]]",
    "id": "172c7808-52db-4eb9-9ecf-505bd00436bc"
  }
}

Send Message

With your Cloud API key, you can also send a new message. Please note that the Cloud API does not accept blank messages. Also note that if you send more than 1 message every 15 seconds, you are likely to have messages dropped as we rate-limit the volume of messages sent to the board.

If you are sending messages to a Note Array, the message will be split up into pieces and distributed to each board in the Note Array. For example, if you have a 2x2 Note Array of Vestaboard Notes, you are expected to send a 30x6 array of arrays.

Path

https://cloud.vestaboard.com/

Method

POST

Headers

X-Vestaboard-Token
Content-Type : "application/json"

Body

You can provide text or an array of array with numbers each representing the new state of the board.

Text Input:

{
  "text": "Hello World"
}

Character Codes (using characters key):

{
  "characters": [
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 8, 5, 12, 12, 15, 0, 23, 15, 18, 12, 4, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
  ]
}

Override Quiet Hours (using forced boolean):

{
  "text": "Hello World",
  "forced": true
}

When forced is set to true, the message will be sent even during configured quiet hours.

Flagship characters:

[
  [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
  [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
  [0, 0, 0, 0, 0, 8, 5, 12, 12, 15, 0, 23, 15, 18, 12, 4, 0, 0, 0, 0, 0, 0],
  [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
  [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
  [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
]

Vestaboard Note characters:

[
  [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
  [0, 0, 0, 0, 0, 0, 0, 62, 0, 0, 0, 0, 0, 0, 0],
  [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
]

Vestaboard Note Array characters can vary depending on how many Vestaboard Notes you are grouping together. The Cloud API will accept larger nested arrays to handle these configurations.

Example Request

CURL
CURL Windows
Javascript

curl -X POST -H "X-Vestaboard-Token: YOUR_API_KEY" -H "Content-Type: application/json" -d '{"text": "Hello World"}' https://cloud.vestaboard.com/

curl -X POST -H "X-Vestaboard-Token: YOUR_API_KEY" -H "Content-Type: application/json" -d "{\"text\": \"Hello World\"}" https://cloud.vestaboard.com/

await fetch("https://cloud.vestaboard.com/", {
  body: JSON.stringify({ text: "Hello World" }),
  headers: {
    "Content-Type": "application/json",
    "X-Vestaboard-Token": "YOUR_API_KEY",
  },
  method: "POST",
});

Example Request with Character Codes (Array Format)

CURL
Javascript

curl -X POST -H "X-Vestaboard-Token: YOUR_API_KEY" -H "Content-Type: application/json" -d "[[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],[0,0,0,0,0,8,5,12,12,15,0,23,15,18,12,4,0,0,0,0,0,0],[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]]" https://cloud.vestaboard.com/

await fetch("https://cloud.vestaboard.com/", {
  body: JSON.stringify([
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 8, 5, 12, 12, 15, 0, 23, 15, 18, 12, 4, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
  ]),
  headers: {
    "Content-Type": "application/json",
    "X-Vestaboard-Token": "YOUR_API_KEY",
  },
  method: "POST",
}).then((res) => res.json());

Example Request with Character Codes (Object Format with `characters` key)

CURL
Javascript

curl -X POST -H "X-Vestaboard-Token: YOUR_API_KEY" -H "Content-Type: application/json" -d '{"characters": [[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],[0,0,0,0,0,8,5,12,12,15,0,23,15,18,12,4,0,0,0,0,0,0],[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0],[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0]]}' https://cloud.vestaboard.com/

await fetch("https://cloud.vestaboard.com/", {
  body: JSON.stringify({
    characters: [
      [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
      [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
      [0, 0, 0, 0, 0, 8, 5, 12, 12, 15, 0, 23, 15, 18, 12, 4, 0, 0, 0, 0, 0, 0],
      [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
      [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
      [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
    ],
  }),
  headers: {
    "Content-Type": "application/json",
    "X-Vestaboard-Token": "YOUR_API_KEY",
  },
  method: "POST",
}).then((res) => res.json());

Example Request with Forced Override (Quiet Hours)

CURL
Javascript

curl -X POST -H "X-Vestaboard-Token: YOUR_API_KEY" -H "Content-Type: application/json" -d '{"text": "Hello World", "forced": true}' https://cloud.vestaboard.com/

await fetch("https://cloud.vestaboard.com/", {
  body: JSON.stringify({
    text: "Hello World",
    forced: true,
  }),
  headers: {
    "Content-Type": "application/json",
    "X-Vestaboard-Token": "YOUR_API_KEY",
  },
  method: "POST",
}).then((res) => res.json());

Example Response

{
  "status": "ok",
  "id": "9b4f13f0-4623-4fb9-8fbf-09ae13350da1",
  "created": 1681154452865
}

Get Transition

You can retrieve the current transition settings for your device. Transitions are currently supported on Flagship and Vestaboard Note devices and will not work on Note Arrays.

Path

https://cloud.vestaboard.com/transition

Method

GET

Headers

X-Vestaboard-Token
Content-Type : "application/json"

Example Request

CURL
Javascript

curl -H "X-Vestaboard-Token: YOUR_API_KEY" -H "Content-Type: application/json" https://cloud.vestaboard.com/transition

await fetch("https://cloud.vestaboard.com/transition", {
  headers: {
    "Content-Type": "application/json",
    "X-Vestaboard-Token": "YOUR_API_KEY",
  },
  method: "GET",
}).then((res) => res.json());

Example Response

{
  "transition": "wave",
  "transitionSpeed": "gentle"
}

Transition Types

classic - Traditional flip-style transition
wave - Wave-style transition effect
drift - Drift-style transition effect
curtain - Curtain-style transition effect

Transition Speeds

gentle - Slower, smoother transition
fast - Quicker transition

Set Transition

You can update the transition settings for your device. Transitions are currently supported on Flagship and Vestaboard Note devices and will not work on Note Arrays.

Path

https://cloud.vestaboard.com/transition

Method

PUT

Headers

X-Vestaboard-Token
Content-Type : "application/json"

Body

{
  "transition": "wave",
  "transitionSpeed": "gentle"
}

Both fields are required:

transition - One of: "classic", "wave", "drift", or "curtain"
transitionSpeed - One of: "gentle" or "fast"

Example Request

CURL
CURL Windows
Javascript

curl -X PUT -H "X-Vestaboard-Token: YOUR_API_KEY" -H "Content-Type: application/json" -d '{"transition": "wave", "transitionSpeed": "gentle"}' https://cloud.vestaboard.com/transition

curl -X PUT -H "X-Vestaboard-Token: YOUR_API_KEY" -H "Content-Type: application/json" -d "{\"transition\": \"wave\", \"transitionSpeed\": \"gentle\"}" https://cloud.vestaboard.com/transition

await fetch("https://cloud.vestaboard.com/transition", {
  body: JSON.stringify({
    transition: "wave",
    transitionSpeed: "gentle",
  }),
  headers: {
    "Content-Type": "application/json",
    "X-Vestaboard-Token": "YOUR_API_KEY",
  },
  method: "PUT",
}).then((res) => res.json());

Example Response

{
  "transition": "wave",
  "transitionSpeed": "gentle"
}

Format Message

This endpoint takes a string and formats it into an array of arrays with Vestaboard character codes. For more formatting options, see VBML

Path

https://cloud.vestaboard.com/vbml/format

Method

GET or POST

Parameters

These can be provided as a JSON POST body, or as query string parameters (works with either GET or POST).

message (required)
- A string you want to format
rows (optional)
- The number of rows to format the message for. Defaults to 6 (the standard Vestaboard board height) if not provided. Use this to format messages for a Vestaboard Note or other custom board size.
columns (optional)
- The number of columns to format the message for. Defaults to 22 (the standard Vestaboard board width) if not provided. Use this to format messages for a Vestaboard Note or other custom board size.

Example Request (POST Body)

CURL
CURL Windows
Javascript

curl \
     -X POST \
     -d '{"message": "Hello World"}' \
     -H "Content-Type: application/json" \
     https://cloud.vestaboard.com/vbml/format

curl \
     -X POST \
     -d "{\"message\": \"Hello World\"}" \
     -H "Content-Type: application/json" \
     https://cloud.vestaboard.com/vbml/format

await fetch("https://cloud.vestaboard.com/vbml/format", {
  headers: {
    "Content-Type": "application/json",
  },
  method: "POST",
  body: JSON.stringify({
    message: "Hello World",
  }),
}).then((res) => res.json());

Example Request with Custom Size (Vestaboard Note)

Pass rows and columns alongside message to format for a Vestaboard Note (15 columns x 3 rows) instead of the standard board size.

CURL
CURL Windows
Javascript

curl \
     -X POST \
     -d '{"message": "Hello World", "rows": 3, "columns": 15}' \
     -H "Content-Type: application/json" \
     https://cloud.vestaboard.com/vbml/format

curl \
     -X POST \
     -d "{\"message\": \"Hello World\", \"rows\": 3, \"columns\": 15}" \
     -H "Content-Type: application/json" \
     https://cloud.vestaboard.com/vbml/format

await fetch("https://cloud.vestaboard.com/vbml/format", {
  headers: {
    "Content-Type": "application/json",
  },
  method: "POST",
  body: JSON.stringify({
    message: "Hello World",
    rows: 3,
    columns: 15,
  }),
}).then((res) => res.json());

Example Request (GET with Query String)

GET requests pass message, rows, and columns as query string parameters instead of a body.

CURL
Javascript

curl "https://cloud.vestaboard.com/vbml/format?message=Hello%20World&rows=3&columns=15"

await fetch(
  "https://cloud.vestaboard.com/vbml/format?message=Hello%20World&rows=3&columns=15"
).then((res) => res.json());

Example Response

[
  [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
  [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
  [0, 0, 0, 0, 0, 8, 5, 12, 12, 15, 0, 23, 15, 18, 12, 4, 0, 0, 0, 0, 0, 0],
  [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
  [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0],
  [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
]

Endpoints

Read Current Message​

Path​

Method​

Headers​

Example Request​

Example Response​

Send Message​

Path​

Method​

Headers​

Body​

Example Request​

Example Request with Character Codes (Array Format)​

Example Request with Character Codes (Object Format with characters key)​

Example Request with Forced Override (Quiet Hours)​

Example Response​

Get Transition​

Path​

Method​

Headers​

Example Request​

Example Response​

Transition Types​

Transition Speeds​

Set Transition​

Path​

Method​

Headers​

Body​

Example Request​

Example Response​

Format Message​

Path​

Method​

Parameters​

Example Request (POST Body)​

Example Request with Custom Size (Vestaboard Note)​

Example Request (GET with Query String)​

Example Response​

Read Current Message

Path

Method

Headers

Example Request

Example Response

Send Message

Path

Method

Headers

Body

Example Request

Example Request with Character Codes (Array Format)

Example Request with Character Codes (Object Format with `characters` key)

Example Request with Forced Override (Quiet Hours)

Example Response

Get Transition

Path

Method

Headers

Example Request

Example Response

Transition Types

Transition Speeds

Set Transition

Path

Method

Headers

Body

Example Request

Example Response

Format Message

Path

Method

Parameters

Example Request (POST Body)

Example Request with Custom Size (Vestaboard Note)

Example Request (GET with Query String)

Example Response