VAO PUSH / GUIDES

Developers / API

Send events as messages and changing values as state.

Send a message

Save default recipients in the Web console and copy the unified push URL, or use a device-specific URL. Temporarily choosing recipients for a manual send does not change the defaults.

shell

curl -X POST 'https://push.example.com/v1/push/YOUR_SEND_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"title":"Album ready","body":"Your weekend photos are ready to view."}'

Each message is saved to history. A 202 response means saved and queued, not displayed on a device. Automatic message credentials cannot expand recipients through the request body or write card data.

Update a source’s current state

Copy the dedicated URL for an externally updated source in Card Studio. Its write credential updates only that source; it cannot read history or manage devices.

shell

curl -X PUT 'https://push.example.com/v1/card-data/YOUR_SOURCE_KEY' \
  -H 'Content-Type: application/json' \
  --data '{"fields":{"progress":{"type":"percent","value":"68"},"status":{"type":"text","value":"In progress"}}}'

Each request replaces the complete current state without adding ordinary message history or changing the design. Send a separate message when a completion alert is useful. Existing device state endpoints remain compatible; new functional cards use studio data-source URLs.

Endpoints and permissions

Endpoint	Purpose
`POST /v1/push/{key}`	Send messages to a device or saved recipient list
`PUT /v1/card-data/{source_key}`	Update one fixed data source
`PUT /v1/state/{key}/{data_id}`	Compatibility endpoint for existing device cards

An import code lets a device subscribe to a published card; it is not a write credential. Web administration, message delivery, source updates, and device reads use separate authorizations.

When integrating

Sending URLs contain secrets. Keep them out of public logs, frontend source, and screenshots.
Reuse an Idempotency-Key when retrying the same logical message.
Use decimal strings for numeric values and include all state fields you want to retain.
Collection, queueing, push acceptance, and device display are separate stages.

Source and full protocol

The public repository includes the full API protocol, card descriptions, and connection guides. Requests above illustrate format only; the domain and credentials are placeholders. Copy real URLs from your own console.

Full API protocol Cards and subscriptions