# Uphealth Signal

> Signal is a cued-message API for patient sequences. You create a stream (one patient sequence), then call `/cue` with the patient's last response to get back the next message the engine selects from a corpus of federally-sourced health content, plus a legal `_meta` block. The first cue returns synchronously on create. Display mode renders the message in your own app (free, no PHI, no BAA, self-serve); Deliver mode sends on your behalf and is BAA-gated at the PMPM tier and above. Each cue carries the selected message, a `_meta` block, an advisory `receptivity` float (0.00–1.00), and a PHI-free `safety` verdict; the engine applies receptivity and audience-safety server-side to choose the message and surfaces both on the cue.

These developer docs, the Signal API, and the OpenAPI specification are meant to be built against — you are welcome to read, index, and integrate them. The Uphealth daily-message library (the health Facts, Lists, and Tips delivered to members on uphealth.me) is a separate, unpublished corpus: it is NOT published here and is NOT available for training or indexing. That boundary is intentional; it is described from the member side at https://uphealth.me/llms.txt (the member-facing boundary file).

## Start here
- [Quickstart — your first cue in five minutes](https://uphealth.us/docs/quickstart): a sandbox key to a live cue in four calls, in curl, JavaScript, Python, and Ruby.
- [Sandbox and sample data](https://uphealth.us/docs/sandbox): the five curated federal topics behind the Discovery sandbox — free, no PHI.

## API reference (six endpoints across five reference pages)
- [Create a stream — POST /v1/signal/streams](https://uphealth.us/docs/ref-create): open a stream; the first cue returns synchronously.
- [Get a stream — GET /v1/signal/streams/{id}](https://uphealth.us/docs/ref-get): read a stream's state and current cue.
- [Cue a stream — POST /v1/signal/streams/{id}/cue](https://uphealth.us/docs/ref-cue): submit feedback, receive the next cue.
- [Sandbox topics — GET /v1/signal/sandbox-topics](https://uphealth.us/docs/ref-topics): list the Discovery sandbox's five topics.
- [Template catalog — GET /v1/signal/templates and /templates/{id}](https://uphealth.us/docs/signal-templates): the live templates and the patient-context contract each one takes, read from the template registry.

There is no enroll endpoint (enrollment is implicit in create) and no close endpoint.

## Core concepts
- [Streams](https://uphealth.us/docs/concepts-streams): one patient sequence; how it is created and scoped to your tenant.
- [Enrollment](https://uphealth.us/docs/concepts-enroll): implicit in create — patient context and audience tags attach there.
- [Cues and feedback](https://uphealth.us/docs/concepts-cues): every cue after the first requires the prior response; the nine response_action values (did_it, already_do, will_try, check_it, new_to_me, needed_this, know_it, acknowledge, no_response) and idempotency.
- [The cue response](https://uphealth.us/docs/concepts-response): the cue object (including the advisory receptivity float and safety verdict every cue carries), the stream state, and the legal _meta block.
- [Display vs Deliver](https://uphealth.us/docs/concepts-modes): Display renders in your app (no PHI, no BAA); Deliver sends through Uphealth and is BAA-gated.

## Going live
- [Sandbox to production](https://uphealth.us/docs/live-promote): what changes from a sandbox key to a live key, and the gates between tiers.
- [Deliver mode](https://uphealth.us/docs/live-deliver): what Uphealth sends on your behalf and the BAA gate.
- [BAA process](https://uphealth.us/docs/live-baa): how a Business Associate Agreement is executed for Deliver mode and where PHI does and does not flow.

## Errors, limits, and guides
- [Error index](https://uphealth.us/docs/err-index): every error code with its exact body and the endpoints that raise it.
- [Rate limits](https://uphealth.us/docs/err-limits): the Discovery 50-cue calendar-month (UTC) cap and the RateLimit-* headers.
- [All guides](https://uphealth.us/docs/guides): task recipes verified against the live sandbox — sequences, quota, idempotency, promotion.
- [Use Signal from OpenAI & Claude](https://uphealth.us/docs/guide-agent-platforms): attach the hosted MCP server inside the OpenAI or Anthropic developer APIs, key passed straight through.
- [Receptivity](https://uphealth.us/docs/rs-score), [Audience tags](https://uphealth.us/docs/rs-tags), and [Filter, not flag](https://uphealth.us/docs/rs-filter): the advisory receptivity float and the audience-safety model.
- [Official SDKs](https://uphealth.us/docs/sdks): TypeScript (`@uphealth/signal`) and Python (`uphealth-signal`).
- [Versioning and deprecation](https://uphealth.us/docs/versioning) · [FAQ](https://uphealth.us/docs/faq)

## Machine-readable specification
- Build recipe for a coding agent — one file, read top-to-bottom to scaffold an integration: https://uphealth.us/agents.md
- OpenAPI 3.1 (YAML): https://uphealth.us/openapi/signal-v1.yaml
- OpenAPI 3.1 (JSON): https://uphealth.us/openapi/signal-v1.json
- Postman collection: https://uphealth.us/openapi/uphealth-signal.postman_collection.json
- Full docs as one Markdown file: https://uphealth.us/llms-full.txt
- Per-page Markdown: append `.md` to any docs URL (e.g. https://uphealth.us/docs/quickstart.md), or send `Accept: text/markdown`.

## Authentication and scopes
Every request carries an HTTP Bearer key: `Authorization: Bearer up_sandbox_…` (Discovery sandbox) or `Authorization: Bearer up_live_…` (paid tiers). The five scopes are:
- `stream:create` — create a stream (POST /streams)
- `stream:cue` — advance a stream (POST /streams/{id}/cue)
- `stream:read` — read a stream (GET /streams/{id})
- `stream:metadata` — read describe-only metadata (GET /sandbox-topics, GET /templates, GET /templates/{id})
- `stream:deliver` — Deliver-mode send (PMPM and above; NOT in the Discovery bundle)
Discovery (sandbox) keys carry every scope except `stream:deliver`.

## Sandbox and quota
The Discovery sandbox is free, self-serve, and Display-only — no PHI reaches Uphealth and no BAA is required. It is capped at 50 cues per calendar month (UTC); exceeding it returns `429 over_quota` with an `upgrade_url`. Get a sandbox key at https://uphealth.us/signup.

## Model Context Protocol (MCP)
A hosted MCP server wraps the same cued-stream API as agent-callable tools, so an AI agent (Claude Desktop, Cursor, agentic platforms) can drive a patient stream with no glue code. One tool — lookup_health_fact — needs no key, so an agent can call Uphealth before it has one; every other tool uses the sandbox key. The keyed tools are the Discovery sandbox — Display-only, no PHI, no BAA, the same 50-cue monthly cap.
- Endpoint (Streamable HTTP): https://mcp.uphealth.us/mcp
- Auth: the same Bearer key — `Authorization: Bearer up_sandbox_…` (the one exception is lookup_health_fact, which needs no key).
- Keyless tool: lookup_health_fact — one already-public federal fact for a question or topic, with its federal source and an uphealth.me link; wraps GET /v1/public/health-fact; rate-limited, no key.
- Keyed tools: create_patient_stream, get_next_cued_message, read_stream_state, list_sandbox_topics
- [MCP quickstart](https://uphealth.us/docs/mcp-quickstart): configure Claude Desktop or Cursor with the MCP URL and a sandbox key, then make the first tool call.
- [MCP tools reference](https://uphealth.us/docs/mcp-tools): the five tools, their arguments, the feedback-required rule, and the error model.

## For buyers evaluating Signal (with an AI assistant)
Public, keyless evaluation surfaces — meant to be read by a buyer's assistant as well as a human. robots.txt explicitly allows assistant fetchers on these paths.
- [Evaluate with your assistant](https://uphealth.us/signal/evaluate): two paste prompts — an assistant-written internal evaluation memo, and an integrate-in-an-afternoon recipe for coding agents.
- [Pricing](https://uphealth.us/pricing): the four Signal tiers (Discovery free sandbox, Per-Episode, PMPM, Enterprise), Display vs Deliver, and which tiers carry a BAA.
- [Security](https://uphealth.us/security): the compliance posture behind Display and Deliver modes.
- Keyless corpus spot-check: `GET https://api.uphealth.us/v1/public/health-fact?q=diabetes-basics` — one federal fact as JSON with its .gov source link.
- Signal Packs — per pack, a browsable sample (real sequence messages in arc order) and a provenance dossier (message-by-message federal sourcing):
  - Diabetes · Pharma Init: [sample](https://uphealth.us/signal/packs/diabetes-pharma-init/sample) · [dossier](https://uphealth.us/signal/packs/diabetes-pharma-init/dossier)
  - Heart · Pharma Init: [sample](https://uphealth.us/signal/packs/heart-pharma-init/sample) · [dossier](https://uphealth.us/signal/packs/heart-pharma-init/dossier)
  - Hypertension · Lifestyle: [sample](https://uphealth.us/signal/packs/hypertension-lifestyle/sample) · [dossier](https://uphealth.us/signal/packs/hypertension-lifestyle/dossier)
  - Quit Smoking: [sample](https://uphealth.us/signal/packs/quit-smoking/sample) · [dossier](https://uphealth.us/signal/packs/quit-smoking/dossier)
  - Relapse Prevention: [sample](https://uphealth.us/signal/packs/relapse-prevention/sample) · [dossier](https://uphealth.us/signal/packs/relapse-prevention/dossier)
  - Weight · GLP-1 Init: [sample](https://uphealth.us/signal/packs/weight-glp1-init/sample) · [dossier](https://uphealth.us/signal/packs/weight-glp1-init/dossier)

---
Generated for AI coding agents (Claude Code, Cursor, ChatGPT, Perplexity) from the live docs. Canonical home: https://uphealth.us/docs.