API

A small REST API over the same things the dashboard does: upload a manifest, list apps, read alerts, change an alert's status. JSON in, JSON out.

Base URL and auth

Every call goes to https://vibebeacon.app/api/v1 and carries a bearer token.

header

Authorization: Bearer vb_live_your_key_here

Keys belong to a user, not an app, so one key covers everything you own.
Keys are shown once. We store a SHA-256 hash and the first 14 characters for display.
API access is included on every account, including the free app. Creating an app beyond your free one needs a subscription, so that call answers with 402 until you have added a card.

Rate limit

Sixty requests a minute per key. Going over returns 429 with a Retry-After header in seconds. There is no burst allowance worth relying on, so back off rather than retrying immediately.

Endpoints

Method	Path	Body	Response
POST	/manifests	manifest v1	appId, appSlug, componentCount, newAlerts, openAlerts, dashboardUrl
GET	/apps	none	apps: id, slug, name, lastManifestAt, openAlerts, plan
GET	/apps/:id/alerts	none	alerts: id, severity, title, advisoryId, component, fixedIn, status, publishedAt, url
POST	/apps/:id/alerts/:alertId	status, snoozeUntil	the updated alert
GET	/me	none	email, plan, appCount, appLimit

Upload a manifest

The upload creates the app if the slug of app.name is new to you, and updates it otherwise. Matching runs synchronously, so the counts in the response are real, not queued.

bash

curl -X POST https://vibebeacon.app/api/v1/manifests \
  -H "Authorization: Bearer vb_live_your_key_here" \
  -H "Content-Type: application/json" \
  --data @vibebeacon.json

200 response

{
  "appId": "0f2c9a1e-6d1b-4a5f-9c3e-2b7d8a4f1c05",
  "appSlug": "my-coffee-shop-pos",
  "componentCount": 214,
  "newAlerts": 3,
  "openAlerts": 5,
  "dashboardUrl": "https://vibebeacon.app/apps/my-coffee-shop-pos"
}

Past your free app with no subscription, this returns 402 with a checkout URL rather than silently dropping the app.

List your apps

bash

curl https://vibebeacon.app/api/v1/apps \
  -H "Authorization: Bearer vb_live_your_key_here"

Read alerts for an app

Filter with ?status=open, acknowledged, resolved or snoozed. Leave it off to get everything.

bash

curl "https://vibebeacon.app/api/v1/apps/$APP_ID/alerts?status=open" \
  -H "Authorization: Bearer vb_live_your_key_here"

Change an alert

Set the status to acknowledged, resolved or snoozed. Snoozing takes a snoozeUntil timestamp. A resolved alert reopens if a later manifest still shows the affected version.

bash

curl -X POST https://vibebeacon.app/api/v1/apps/$APP_ID/alerts/$ALERT_ID \
  -H "Authorization: Bearer vb_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"status":"snoozed","snoozeUntil":"2026-10-01T00:00:00Z"}'

Who am I

Useful for checking a key works and for seeing how close you are to your app limit.

bash

curl https://vibebeacon.app/api/v1/me \
  -H "Authorization: Bearer vb_live_your_key_here"

Errors

Every error uses the same envelope.

error

{ "error": { "code": "invalid_manifest", "message": "dependencies[12].version is required" } }

Status	Code	Meaning
400	invalid_manifest	The manifest failed validation. The message names the field.
401	unauthorized	Missing, malformed or revoked API key.
402	plan_limit	Past the free app with no subscription. The response carries a checkout URL.
404	not_found	No app or alert with that id belongs to this key's owner.
413	too_large	Over 512 KB or over 2000 dependencies.
429	rate_limited	More than 60 requests a minute. Honour the Retry-After header.
500	server_error	Our fault. Safe to retry with backoff.

Notes worth knowing

Uploading the same manifest twice is safe. Alerts are keyed on app, advisory and component, so nothing duplicates.
Ids are uuids. Slugs are stable for the life of the app and are what the dashboard URLs use.
Timestamps are ISO 8601 in UTC.
The manifest shape is documented on the manifest format page.