# Human Context API Turn a structured description of a workflow step into structured **Human Middle** reasoning that helps an AI agent act with greater clarity, empathy, and effectiveness. ## Description This is a REST API for AI agents, not a chatbot. You send JSON describing one step of an operational workflow (who is involved, the setting, the stage) and receive a single `human_middle` object describing how the people involved are likely to perceive, interpret, and respond at that step: a summary, persona mindsets, whether the person can notice/understand/do what's required, and leveled assessments of first-time burden, stakes asymmetry, psychological safety, cognitive load, trust risk, and human readiness — each with an explanation — plus recommended agent behavior, communication guidance, and design considerations. Use it before your agent drafts a message, makes a decision, or recommends an action that a real person will experience. **This service is intended to be called before an AI agent acts — not after.** ## Base URL ``` https://humancontextapi.com ``` All endpoints are served at the root — there is no `/api` prefix. ## Quick start Call `POST /analyze` with: - `workflow_step` - `primary_persona` - `affected_persona` Add optional context when known. Use the returned Human Middle analysis to modify your communication, recommendation, decision, or workflow behavior — not simply display it. ## Success criteria A successful use of this API results in an AI agent changing its behavior based on the returned Human Middle analysis. The goal is not to repeat the analysis. The goal is to produce a better decision, recommendation, workflow, or communication. ## Authentication None. The API is stateless and unauthenticated. ## Endpoints The operational endpoints an agent uses at runtime are `GET /health`, `POST /analyze`, and `GET /skill.md`. ### GET /health Checks whether the service is available. ```bash curl "https://humancontextapi.com/health" ``` Response (`200`): ```json { "status": "ok", "service": "Human Context API", "version": "1.0.0" } ``` ### POST /analyze Generates the structured human context (`human_middle`) for a single workflow step. Send a JSON body with `Content-Type: application/json`. The request is strict: unknown fields are rejected (`additionalProperties: false`). You can call `/analyze` with **only the three required fields** and add optional context as it becomes available. Missing optional context does not fail the request — the engine infers only reasonable operational context, never demographic, clinical, financial, or other protected characteristics, and lists any material assumptions it made in `human_middle.assumptions`. **Required (only these three):** - `workflow_step` (string) — the single step being analyzed - `primary_persona` (string) — the person carrying out or driving this step (e.g. clinician, coordinator, support agent) - `affected_persona` (string) — the person whose experience or ability to act is being evaluated (e.g. patient, member, customer, caregiver) **Optional (add when known):** - `workflow_description` (string) — the overall workflow this step belongs to - `care_setting` (string) — the setting or environment where it happens - `first_time_experience` (boolean) — whether the affected persona is doing this for the first time - `workflow_stage` (string) — the stage of the broader workflow (e.g. onboarding, decision, resolution) - `touchpoint_type` — one of `intake` | `decision` | `handoff` | `escalation` | `closure` | `communication` | `other` - `expected_action` (string) — the action the affected persona is expected to take - `expected_outcome` (string) — the outcome expected from this step - `additional_context` (string) — any additional free-form context Minimal request — only the three required fields: ```bash curl -X POST "https://humancontextapi.com/analyze" \ -H "Content-Type: application/json" \ -d '{ "workflow_step": "Patient receives a prior-authorization denial letter for an MRI", "primary_persona": "Referring physician", "affected_persona": "Patient with worsening back pain" }' ``` Complete request — all optional context supplied: ```bash curl -X POST "https://humancontextapi.com/analyze" \ -H "Content-Type: application/json" \ -d '{ "workflow_step": "Patient receives a prior-authorization denial letter for an MRI", "workflow_description": "Insurance prior-authorization review for advanced imaging", "primary_persona": "Referring physician", "affected_persona": "Patient with worsening back pain", "care_setting": "Home, reading mail", "first_time_experience": true, "workflow_stage": "decision", "touchpoint_type": "communication", "expected_action": "Understand the decision and next options", "expected_outcome": "Patient knows whether and how to appeal", "additional_context": "The patient'\''s symptoms have been worsening for several weeks." }' ``` Response (`200`): ```json { "api_version": "1.0", "request_id": "b3f1c2a4-9d7e-4a2b-8c11-0f2a6d5e4c31", "human_middle": { "summary": "The step is designed as a formal coverage decision in insurer language, but the patient experiences it as a painful interruption in care during worsening symptoms.", "assumptions": [ "Assumed the denial letter uses standard insurer language, since the exact wording was not provided.", "Assumed the patient is managing the appeal without professional help unless stated otherwise." ], "primary_persona_mindset": "The referring physician is frustrated but familiar with denials as routine. They may see it as something that can sometimes be overturned with more documentation, but they are balancing that against limited staff time. They may assume the patient will call if confused, while the patient assumes the office is already handling it.", "affected_persona_mindset": "The patient is likely opening the letter already worried because their back pain is getting worse and they are waiting for help. A denial for an MRI feels personal and threatening: it can read as 'my pain is not being taken seriously' or 'care is being blocked.' Because this is their first time dealing with prior authorization, they are unlikely to know the difference between a denial, an appeal, or whether the test can still happen later.", "notice": "strained", "understand": "breaks", "do": "strained", "first_time_burden": { "present": true, "explanation": "Because this is the patient's first denial, they do not know the workflow, timelines, roles, or terms. They must learn the process while in pain and under stress." }, "stakes_asymmetry": { "level": "high", "explanation": "For the patient the denial affects pain, anxiety, diagnosis, and trust; for the physician it is one of many administrative barriers. The patient bears the immediate consequences of delay." }, "psychological_safety": { "level": "low", "explanation": "A formal denial letter offers no obvious, low-stakes way to ask questions or admit confusion, so the patient may stay silent rather than seek help." }, "cognitive_load": { "level": "high", "explanation": "The letter mixes a decision, policy rationale, and next steps in unfamiliar insurance language while the patient is distressed and in pain." }, "trust_risk": { "level": "high", "explanation": "A denial during worsening symptoms can read as care being blocked, eroding trust in both the insurer and the care team." }, "human_readiness": { "level": "low", "explanation": "In pain, anxious, and unfamiliar with appeals, the patient is not practically or emotionally ready to act on the denial without help." }, "narrative_context": "At home the patient opens a letter expecting progress and instead finds a denial in technical language. Their pain is worsening, so the message lands as both bureaucratic and urgent, and they may not know whether they, the doctor, or the insurer acts next.", "action": "Make ownership and next steps explicit immediately: tell the patient in plain language what the denial means, who does what next, and the exact first action to take to appeal or get help.", "expected_outcome": "The patient interprets the denial as a coverage decision rather than the end of care, knows whether the office will pursue review or whether they must act, and knows the concrete next step and timeline.", "recommended_agent_behavior": [ "Do not deliver the raw denial verbatim; reframe it as a coverage decision with a path forward before anything else.", "Explicitly assign ownership of the next step so the patient is not left assuming someone else is handling it.", "Escalate to a human when the patient signals distress or urgent symptoms rather than continuing to automate." ], "communication_guidance": [ "Start with a plain-language summary: 'Your insurance denied coverage for the MRI right now. This does not always mean you cannot get it — there may be ways to appeal.'", "State role ownership clearly: who submits more information or requests a peer-to-peer review, versus what the patient must do themselves.", "List next steps in order with deadlines, phone numbers, and required documents, defining jargon when unavoidable.", "Acknowledge worsening pain and include guidance on what to do if urgent symptoms appear." ], "design_considerations": [ "Use a layered format: a short plain-language decision summary first, detailed policy rationale after.", "Separate 'why this was denied' from 'what happens next' so patients don't miss the action they need to take.", "Add a visible responsibility box naming the owner of the next step and expected turnaround time.", "Design for distressed readers: large headings, short sentences, minimal acronyms." ] } } ``` ### GET /skill.md Returns this document (the single source of truth for how to use the API). ```bash curl "https://humancontextapi.com/skill.md" ``` Response (`200`, opening lines): ```markdown # Human Context API Turn a structured description of a workflow step into structured Human Middle reasoning... ``` ## Developer resources These endpoints are for exploring and integrating the API, not for the runtime request loop. ### GET /openapi.json Returns the OpenAPI 3.1 specification. ```bash curl "https://humancontextapi.com/openapi.json" ``` ### GET /docs Interactive API documentation (Swagger UI). Open in a browser: ``` https://humancontextapi.com/docs ``` ### GET /stats Aggregate usage statistics for `/analyze`: total calls, success/error breakdown, recent-window counts, and a per-day series for the last 30 days. Only call counts, status codes, and timestamps are tracked — request contents are never stored, so this does not weaken the stateless-analysis guarantee. **Protected.** This endpoint is private. Send the shared stats access key in the `x-stats-key` header (returns `401` if missing/invalid, `503` if the server has no key configured): ```bash curl -H "x-stats-key: $STATS_ACCESS_KEY" "https://humancontextapi.com/stats" ``` Response (`200`): ```json { "total_calls": 128, "successful_calls": 121, "failed_calls": 7, "calls_last_24h": 14, "calls_last_7d": 96, "first_call_at": "2026-01-04T12:00:00.000Z", "last_call_at": "2026-01-11T09:41:22.000Z", "daily": [ { "date": "2026-06-12", "total": 3, "successful": 3, "failed": 0 } ] } ``` ## When to call it Call Human Context API **immediately before** your agent: 1. **Makes a consequential decision** that affects a person. 2. **Generates a sensitive communication** (denials, escalations, bad news, requests for personal information). 3. **Recommends an action** a person will have to carry out. 4. **Automates a human workflow step** that a person previously handled. 5. **Redesigns an interaction, form, message, or flow** a person will experience. ## How to use the response 1. Decide the single workflow step you want analyzed (this API reasons about one step per call). 2. Build the request body from the fields above and `POST` it to `https://humancontextapi.com/analyze`. 3. On success you get `200` and a `HumanContext` object. All context is under the top-level `human_middle` object. 4. Read `human_middle.summary`, `human_middle.narrative_context`, and `human_middle.action` first for a fast picture. 5. Branch on the signals. `notice` / `understand` / `do` are each `ok` | `strained` | `breaks`. `first_time_burden` is `{ present, explanation }`. `stakes_asymmetry`, `psychological_safety`, `cognitive_load`, `trust_risk`, and `human_readiness` are each `{ level, explanation }` where `level` is `low` | `moderate` | `high`. Treat any `breaks`, or any `high` on `stakes_asymmetry` / `cognitive_load` / `trust_risk`, or any `low` on `psychological_safety` / `human_readiness`, as a signal to slow down and intervene. 6. **Adjust your behavior — do not merely display the analysis.** Apply `recommended_agent_behavior` to change what you do next, use `communication_guidance` to shape any message you send, and use `design_considerations` if you are designing or redesigning the interaction. 7. Handle errors: `422` means your request was invalid (see `message`); `429` means you are being rate limited — back off and retry after the `Retry-After` header (seconds); `502` means a valid result could not be generated — retry once. Every error is `{ "error_code", "message", "request_id" }`. ## Limitations and appropriate use - **Adjust behavior, don't just display.** The response is meant to change what your agent does, says, or builds next — not to be shown to the end user as an analysis. - **Not medical, legal, regulatory, or psychological advice.** Despite the healthcare-style examples, outputs are not professional advice in any domain and must not be used as the sole basis for such decisions. - **Does not replace qualified human review.** For consequential, sensitive, or high-stakes steps, route to a qualified human; treat this API as decision support, not a decision-maker. - **Does not infer protected traits.** It reasons only from the workflow information you provide and does not infer race, health status, disability, religion, sexual orientation, or other protected characteristics that were not given. - **Do not use to manipulate, deceive, discriminate, or exploit vulnerability.** The guidance exists to make interactions clearer and more humane, not to pressure or take advantage of people. - **One step per call.** Each request analyzes a single workflow step. Send separate requests for separate steps. - **Inference, not ground truth.** Responses are model-generated inferences about human experience — decision support, not verified facts about any specific individual. - **No memory.** The service is stateless; it does not retain requests or learn across calls. Include everything relevant in `additional_context`. - **Non-deterministic.** The same input can yield differently-worded results. The enum/`level` fields (`low`/`moderate`/`high`, `ok`/`strained`/`breaks`) are the stable signals to branch on. - **Do not send sensitive personal data.** Describe personas by role and situation (e.g. "patient with worsening back pain"), not by real names or identifiers. ## Full specification - Interactive docs: `https://humancontextapi.com/docs` - OpenAPI 3.1 spec: `https://humancontextapi.com/openapi.json`