cueyou API guide

Every request needs an API key in the Authorization header:

Authorization: Bearer att_xxxxxxxxxxxxxxxxxxxxxxxx

Keys are minted in the dashboard. They start with att_ and are shown only once at creation — store them as secrets. A revoked or unknown key produces 401 {"error":"unauthorized"}. Firebase ID tokens are also accepted by the same handlers but are intended for the first-party app, not for integrations.

All bodies are JSON. All responses are JSON. All timestamps are ISO 8601 strings.

Both /api/alert and /api/prompt accept the same optional fields for shaping how the takeover looks and feels.

Urgency

urgency is one of "info", "normal", or "critical". Defaults to "normal". It drives the takeover surface palette.

Source

source is a free-form string up to 80 chars, shown as a chip at the top of the takeover. Use it to identify the caller, e.g. "claude-code · pre-commit" or "github-actions · deploy".

Description & markdown

description is 0–2000 chars and rendered as markdown on the device. The supported subset is: bold, italic, inline code, ordered and unordered lists, fenced code blocks, and links. Images, tables, and raw HTML are not supported inside description. If you need richer layout or interactive buttons, use the separate html field (see Rich HTML content below); description is still shown as the plain-text fallback. Long descriptions scroll inside the takeover with a fade gradient signalling that there's more.

Alerts and prompts accept an optional html field. When present and allowed, the phone renders it inside the takeover instead of the Markdown description, so you can lay out a status card, a table, a chart made of CSS, or a set of custom buttons.

Availability: the API key must have Allow HTML content switched on. It is off by default and can only be changed by the account owner inside the cueyou app (an API key cannot change it). A request with html from a key that isn't allowed is rejected with 403 {"error":"html_not_allowed"} and nothing is sent.

description is still required and is always your fallback: it is shown on older app versions, if the phone is offline when the HTML is fetched, and if the web view can't be shown.

How it appears. The takeover shows a fixed header — "Custom content from <your key's label>" — above your HTML. The label comes from the API key's name in the dashboard, not from anything you send, so recipients can always tell where the content came from. Your page cannot cover or restyle that header.

What your page can and can't do

Your HTML runs in a locked-down, sandboxed web view:

Because remote resources are blocked, embed everything you need (use data: URIs for images) and keep the page small.

On the lock screen, JavaScript is switched off and a note "Unlock to use buttons" is shown. Static HTML and CSS still render. Scripts and buttons work once the user unlocks the phone.

Buttons that answer a prompt

Inside your page, call the cueyou message channel to answer the prompt. The value comes back to your API call exactly like a text or option answer (status: "answered", answer: <your value>).

<div style="font-family: sans-serif; padding: 16px">
  <h2>Deploy v2.18.0 to production?</h2>
  <p>3 services · 12 commits · all checks green</p>

  <button onclick="answer('approve')">Approve</button>
  <button onclick="answer('reject')">Reject</button>
</div>

<script>
  function answer(value) {
    // `cueyou` exists once the phone is unlocked and the bridge is available.
    if (window.cueyou) {
      cueyou.postMessage(JSON.stringify({ type: "answer", value: value }));
    }
  }
</script>

Message format:

Messages must be JSON and under 2 KB; anything else is ignored. On alerts (which take no answer) HTML renders normally and answer messages are ignored.

Full-screen pages (fullscreen)

Add "fullscreen": true (per message, next to html) and your page becomes the whole screen: edge-to-edge, with the status and navigation bars hidden, and nothing of cueyou's drawn around it — no title, source chip, option buttons, "Dismiss" button or "Custom content from …" header. Your page is responsible for everything the user sees, including its own close button.

Because nothing identifies the sender on screen, only switch Allow HTML content on for API keys you fully trust.

What still works, invisibly, so a full-screen page can never trap the user:

Layout notes:

• The page has no default padding (margin: 0). Use env(safe-area-inset-top), env(safe-area-inset-bottom) etc. to stay clear of camera cut-outs and gesture bars.
• The background is transparent by default and shows the urgency colour; set your own background on html, body for a designed look.
• On the lock screen scripts are off (as for all HTML): static HTML and CSS still render, but buttons and dismiss only work after unlock — the user can still swipe Back. You can detect this: window.cueyou is undefined when scripts can't reach the app.
• If the page can't be shown (for example the phone is offline when it tries to fetch it), the normal cueyou takeover is shown instead, using your description.
• Older app versions ignore fullscreen and show the normal layout.

curl https://api.cueyou.app/api/alert \
  -H "Authorization: Bearer $CUEYOU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Build failed",
    "description": "main is red: 3 tests failing",
    "urgency": "critical",
    "fullscreen": true,
    "html": "<div style=\"min-height:100vh;display:flex;flex-direction:column;justify-content:center;align-items:center;background:#7f1d1d;color:#fff;font-family:sans-serif;text-align:center;padding:env(safe-area-inset-top) 24px env(safe-area-inset-bottom)\"><h1 style=\"font-size:48px;margin:0\">main is red</h1><p>3 tests failing</p><button style=\"margin-top:32px;padding:16px 32px;font-size:18px\" onclick=\"cueyou.postMessage(JSON.stringify({type:\\\"dismiss\\\"}))\">Got it</button></div>"
  }'

Example — prompt with HTML buttons

curl https://api.cueyou.app/api/prompt \
  -H "Authorization: Bearer $CUEYOU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Deploy v2.18.0?",
    "description": "Approve the production deploy (plain-text fallback)",
    "source": "ci · deploy/production",
    "html": "<h2>Deploy v2.18.0?</h2><button onclick=\"cueyou.postMessage(JSON.stringify({type:\\\"answer\\\",value:\\\"approve\\\"}))\">Approve</button> <button onclick=\"cueyou.postMessage(JSON.stringify({type:\\\"answer\\\",value:\\\"reject\\\"}))\">Reject</button>",
    "timeoutMs": 60000
  }' \
  --max-time 70

Example — alert with a styled status card

curl https://api.cueyou.app/api/alert \
  -H "Authorization: Bearer $CUEYOU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Latency spike",
    "description": "p99 latency 4.2s on /checkout",
    "urgency": "critical",
    "html": "<div style=\"font-family:sans-serif\"><h1 style=\"color:#ff5252;margin:0\">4.2s</h1><p>p99 latency on <b>/checkout</b></p></div>"
  }'

Errors added by html

Tips

• Design for a dark, narrow phone screen; use relative units and avoid fixed widths.
• Don't rely on colours alone — recipients may see the content in bright sunlight or with a colour-vision difference.
• Keep the plain description meaningful; it is what shows if the HTML can't.

Security and trust

What recipients see and control. HTML content always appears under a header naming the API key that sent it (except in fullscreen mode, where the page is the whole screen and nothing of cueyou's is shown — so only enable HTML for keys you fully trust), runs without network access, and can't navigate away or open other apps. Account owners decide, per API key, whether HTML is allowed at all. Treat your API keys as secrets: a leaked key that is allowed to send HTML could show misleading content on your users' phones, so revoke it immediately if it's exposed.

• Use /api/alert when you only need to grab attention — a build failed, an error spiked, a long task finished. Returns immediately.
• Use /api/prompt when you need a decision — gating a destructive operation, asking for an override, collecting a free-form note. Blocks until the user responds.

A common pattern is a Claude Code (or CI) hook that calls /api/alert on notifications and /api/prompt on PreToolUse for risky tools so the user can approve from their phone.

• The user controls delivery. In the app each user chooses one delivery mode — Disabled (drop everything), Muted (full-screen takeover, silent), Vibration (vibrates, no sound) or Sounds (rings) — and can override it per device or per API key. They can also set quiet hours (a daily window during which alerts are dropped) and pause everything for 1, 2, 8 or 24 hours. When delivery is switched off — Disabled, inside quiet hours, or during a pause — alerts come back with delivered: false, reason: "blocked_by_settings" and prompts come back with status: "blocked". Muted and Vibration still deliver. In every case the call returns 200 — handle these as non-errors.
• Idempotency. There is no idempotency key. Retrying a 5xx may produce duplicate phone alarms. Prefer surfacing the failure to the caller over blind retries.
• Rate limits. Not enforced server-side today. Treat the phone as the rate limiter — repeated alarms are noisy and will train the user to ignore them.
• API key hygiene. Each integration should have its own key labelled in the dashboard. Revoke on leak; the next request with that key will get 401.
• Urgency is visual-only today. urgency drives the takeover palette but does not currently change the sound. Per-tier ringing is a known follow-up.