Skip to main content

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 -H "X-Vestaboard-Token: YOUR_API_KEY" -H "Content-Type: application/json" https://cloud.vestaboard.com/

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 and Mute (using forced boolean):

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

When forced is set to true, the message will be sent even during configured quiet hours or while your Vestaboard is muted.

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 -X POST -H "X-Vestaboard-Token: YOUR_API_KEY" -H "Content-Type: application/json" -d '{"text": "Hello World"}' https://cloud.vestaboard.com/

Example Request with Character Codes (Array Format)​

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/

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

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/

Example Request with Forced Override (Quiet Hours and Mute)​

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/

Example Response​

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

Example Response While Muted​

If your Vestaboard is muted, the message is rejected with a 423 status unless forced is true. Send with forced, call Unmute, or wait for the mute to end.

{
  "status": "error",
  "message": "This Vestaboard's installables are paused.",
  "type": "SubscriptionMuted"
}

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 -H "X-Vestaboard-Token: YOUR_API_KEY" -H "Content-Type: application/json" https://cloud.vestaboard.com/transition

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 -X PUT -H "X-Vestaboard-Token: YOUR_API_KEY" -H "Content-Type: application/json" -d '{"transition": "wave", "transitionSpeed": "gentle"}' https://cloud.vestaboard.com/transition

Example Response​

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

Mute​

Mutes your Vestaboard for a set time. While muted, Vestaboard+ Channels won't send new messages, messages sent through the Cloud API are rejected unless they are forced (see Send Message), and your Vestaboard keeps whatever it is currently displaying.

Muting through the Cloud API and pausing Channels in the Vestaboard app share the same state, so pausing Channels in the app also mutes the Cloud API, and unmuting through the Cloud API resumes Channels in the app.

Path​

https://cloud.vestaboard.com/mute

Method​

PUT

Headers​

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

Body​

{
  "duration": "one-hour"
}

The body is optional:

  • duration - One of: "half-hour", "one-hour", "rest-of-day", or "one-year". Defaults to "one-hour". "rest-of-day" mutes until midnight in your Vestaboard's timezone, and "one-year" mutes for 365 days or until you unmute.

Example Request​

curl -X PUT -H "X-Vestaboard-Token: YOUR_API_KEY" -H "Content-Type: application/json" -d '{"duration": "one-hour"}' https://cloud.vestaboard.com/mute

Example Response​

mutedUntil is the time the mute ends, in milliseconds since the Unix epoch.

{
  "muted": true,
  "duration": "one-hour",
  "mutedUntil": 1792170000000
}

Unmute​

Unmutes your Vestaboard right away, so Vestaboard+ Channels and the Cloud API can send messages again.

Path​

https://cloud.vestaboard.com/mute

Method​

DELETE

Headers​

  • X-Vestaboard-Token

Example Request​

curl -X DELETE -H "X-Vestaboard-Token: YOUR_API_KEY" https://cloud.vestaboard.com/mute

Example Response​

{
  "muted": false
}

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 \
     -X POST \
     -d '{"message": "Hello World"}' \
     -H "Content-Type: application/json" \
     https://cloud.vestaboard.com/vbml/format

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 \
     -X POST \
     -d '{"message": "Hello World", "rows": 3, "columns": 15}' \
     -H "Content-Type: application/json" \
     https://cloud.vestaboard.com/vbml/format

Example Request (GET with Query String)​

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

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

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]
]