Integrate Signal

Zero to first cue in 20 minutes.

Create a stream, cue it, read the webhook. Display + Deliver modes, idempotency keys, four endpoints.

Display mode never touches PHI — no BAA required. Start in 5 minutes.

$ curl -X POST https://api.uphealth.us/v1/signal/streams/:id/cue \ -H "Authorization: Bearer $KEY" \ -H "Content-Type: application/json" \ -d '{"patient_ref":"p_001","last_response":"did_it"}' # → 200 OK · ~47ms # → { "message": "...", "safety": { "ok": true } }

1 Sign up 2 Get sandbox key 3 Pick a template 4 Make first POST 5 First cue back

20 min

First cue

30 sec

Sandbox key

<50ms

Median cue latency

MCP tools live

Onboarding · 0 → first cue

Self-serve through Discovery. Manual review at Deliver.

Display-mode buyers go from signup to first cue inside 20 minutes — no waiting on humans. Deliver-mode buyers (the API sends on the patient's behalf) get same-day manual review and a BAA before keys activate. The boundary is the channel, not the use case.

The first cue · curl

$ curl -X POST https://api.uphealth.us/v1/signal/streams/abc_124/cue \
  -H "Authorization: Bearer $UPHEALTH_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "patient_ref": "p_001", "last_response": "did_it", "day": 31 }'
↓ 47ms ↓
{
  "message": "Today is day 31 — what’s one craving you handled?",
  "safety": { "verdict": "included" },
  "receptivity": 0.74
}

Anatomy of the response

message what to render or send
safety.verdict audience-tag verdict · included/filtered
receptivity 0-to-1 advisory float
~47ms p50 round-trip latency

The four contracts

Display mode

You render the message

Deliver mode

Uphealth + Reach send

Patient context in

Every cue carries the prior last_response. Signal cannot reason about progression without it; the value lands in your client's stored state.

Same contract — last_response flows in on each cue. Engagement events fire back via webhook so your record stays in sync with what was actually sent and opened.

One stream, one template

A stream is bound to one template at create-time. Switching templates means a new stream; the patient's history splits at the boundary.

Same binding. Mid-arc template version migrations follow the strategies on /signal/changelog (in-place / drain / forklift) — no impromptu template swaps.

Audience safety gate

Every cue is filtered against include/exclude tags before it returns. Filter, not flag — silent drops, no PHI seen on our side.

Same filter, plus the safety verdict is recorded in the BAA-bound audit log. Filtered cues never enter the send queue.

Receptivity score

Returned advisory. Your routing logic decides whether to render, defer, or hold based on the value.

Returned advisory AND consumed by Reach's send-time decision. Your routing logic still gets the score for downstream telemetry.

Discovery tier · Display vs Deliver

Every account starts at Discovery tier with Display mode; Per-Episode removes the cap, still Display-only. Deliver mode unlocks at the PMPM tier and above and requires a signed BAA. The two columns below describe what is gated on what.

Discovery · Display only

Self-serve sandbox · up_sandbox_ keys

Sign up at uphealth.us/signup with email + password. The first key (up_sandbox_ prefix) is issued on signup. Four of five scopes (create, cue, read, metadata) are granted; stream:deliver is held until tier upgrade. Discovery quota: 50 cue calls per calendar month. No BAA. No PHI. Mock patient_ref values only.

PMPM + · Display + Deliver

Manual review · BAA · up_live_ keys

Talk to sales with intended use, expected volume, and patient context. BAA executed. up_live_ keys issued with the fifth scope (stream:deliver) granted. Production quota matched to contract. Real PHI permitted under the BAA.

§2 · 20-minute quickstart

Five calls from signup to first cue.

Sign up, create a stream, browse the curated pool, cue it, then render the response — each call takes 2 to 4 minutes. Run it end-to-end once with a mock patient_ref before talking to sales about Deliver mode.

1 Sign up 2 Create stream 3 Browse pool 4 Cue 5 Render

Full quickstart with code samples →

Run a cue live in the Overview playground →

§3 · Sandbox → production

From up_sandbox_ to up_live_.

Discovery sandbox keys (up_sandbox_ prefix) are self-serve. Production live keys (up_live_ prefix) carry the stream:deliver scope + the BAA-bound PHI permission, and they need a same-day manual review before activation. The promotion ceremony is 5 short steps.

1 Pilot 2 Sales 3 Legal 4 Provision 5 Cutover

Full promotion guide →

What the ceremony is NOT

Production access is gated on legal + security review for a real reason — PHI handling has a different liability profile than mock data. We do not auto-promote based on usage thresholds, do not skip BAA at any tier where Deliver mode is available, and do not let production keys flow without webhook URL verification. The 5 steps usually fit inside one business day; the contract is what they protect.

§4 · SDKs + MCP

Use the raw API. Or call it from your agent.

The /v1/signal/streams API is the canonical surface. We do not block any client choice — curl, fetch, requests, faraday, axios all work today. Two integration shapes beyond raw HTTP are formalized: language SDKs (planned, customer-driven) and the MCP server (live, for AI agent integrators).

Calling surfaces

Five shapes, one API.

Sample-language snippets for curl + Node.js + Python + Ruby live on the docs page today (covers ~95% of the calling surface). First-party SDKs with full type signatures + retries + circuit-breakers land when paying customers in that language ask.

The MCP server is a thin protocol wrapper — no separate auth flow, no separate quota. An agent in MCP-Deliver mode still requires up_live_ keys + BAA; cue calls made via MCP count the same as cue calls made via curl.

Read the SDK docs →

curl

Sample on /docs

Node.js

Sample on /docs

Python

Sample on /docs

Ruby

Sample on /docs

MCP

mcp.uphealth.us · live · 4 tools

§5 · Display vs Deliver

Onboarding speed and BAA shape differ by mode.

Discovery → Per-Episode is Display-mode-only on the cheap side of the ladder. PMPM + Enterprise unlock Deliver mode + the BAA. The table below is the same one on /signal/safety + /signal/receptivity — update propagates.

Who sends the message

Your application

Uphealth (email + push)

PHI permitted

No — mock patient_ref only

Yes — real PHI under BAA

BAA required

Not required

Required before keys activate

Tier

Discovery and above

PMPM and above

API scopes granted

create · cue · read · metadata

+ stream:deliver

Onboarding speed

20 minutes (self-serve)

Same-day (manual review + BAA)

Webhook required

Optional (your channel reports its own engagement)

Required (engagement reported back to you)

Receptivity score

Returned — your routing logic uses it

Returned + composed with Reach for routing

Zero to first cue in 20 minutes.

Self-serve through Discovery. Manual review at Deliver.

Discovery tier · Display vs Deliver

Self-serve sandbox · up_sandbox_ keys

Manual review · BAA · up_live_ keys

Five calls from signup to first cue.

From up_sandbox_ to up_live_.

Use the raw API. Or call it from your agent.

Five shapes, one API.

Onboarding speed and BAA shape differ by mode.

Sandbox key in 30 seconds. Five calls to first cue.