Authentication quickstart

Four steps from a client-credentials pair to your first authenticated read.

POST {{OAUTH_TOKEN_URL}}
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials
&client_id={{CLIENT_ID}}
&client_secret={{CLIENT_SECRET}}

GET {{API_BASE_URL}}/api/capabilities
Authorization: Bearer <token>

# 200
{
  "capabilities": [
    "patients:read",
    "slots:read",
    "appointments:book"
  ]
}

The confirmation protocol 428

Every mutation is two-phase: the API returns a challenge, then an identical confirming request commits it.

This is a safety gate between your agent and the API — it forces a mutation to be committed deliberately, in two steps, so a booking, cancel, or patient write can never fire on a single (possibly mistaken) call. Because writes on your client require confirmation, your first attempt returns 428 with a confirmationToken and a readBack instead of performing the action. You resend the identical body to the same URL with that token, and the phase flips from challenge to commit. No separate endpoint, no state to negotiate — the token's presence is the only thing that changes. Getting the caller's go-ahead happens before this and is your responsibility; the API neither sees nor verifies that conversation.

The dance, end to end

Two steps

The token, threaded verbatim

The token is bound to a fingerprint of your exact fields. Watch the highlighted value — it is minted in the 428 response and carried, character for character, into the confirming request.

POST /api/appointments
Authorization: Bearer <token>

{ "patientId": "pat_5GIQx5wzI0jX1waDkKNbfv", "slotId": "slt_5ilAAt7KAbWjrAw8rDXHzb" }

{
  "code": "confirmation_required",
  "confirmationToken": "9f8c2a1b4d6e4f0a8c1e2b3d4a5f6071",
  "expiresAt": "2026-07-05T18:05:00Z",
  "readBack": { "patientId": "pat_5GIQx5wzI0jX1waDkKNbfv", "slotId": "slt_5ilAAt7KAbWjrAw8rDXHzb" }
}

POST /api/appointments
Authorization: Bearer <token>

{ "patientId": "pat_5GIQx5wzI0jX1waDkKNbfv", "slotId": "slt_5ilAAt7KAbWjrAw8rDXHzb",
  "confirmationToken": "9f8c2a1b4d6e4f0a8c1e2b3d4a5f6071" }

# 201 → { "appointmentId": "apt_0AYXEZeALa6T4t9NAfrufC" }

Edge cases

Codes link to their page in the problem registry.

Booking playbook

The scripted, test-verified call flow — turning a caller's words into four ids and a confirmed slot.

Slot search needs all four of providerId, locationId, visitTypeId, and procedureId — none is optional — plus a date window of 14 days or less. So most of the work is resolving the caller's phrases ("Dr Smith, Downtown, for acne") into those numeric ids against the directory endpoints, by name. Never speak any of these ids to the caller.

Parameters — the match request

Confirm the caller's identity before disclosing anything. All four fields are required; phone needs at least four digits.

A match with items confirms the caller; no items means you have not verified them — offer to create a new patient or take a message, never read back records.

For LLM agents

A single self-contained contract you can hand to a LLM-agent runtime — the source of truth behind these docs.

SKILL.md is the machine-facing guide for an LLM agent in a live patient conversation, acting for one medical practice. It packs the whole flow — OAuth setup, the id-acquisition the slot search requires, the mandatory two-phase 428 dance, the full endpoint surface, every error code with recovery steps, and the HIPAA and conversational rules — into one document written to be read by the model itself.

Two rules dominate everything

What it covers

• Setup — base URL, OAuth2 client-credentials, and the /api/capabilities trust check.
• The conversation playbook — the canonical 8-step booking dialogue, plus cancel, one-shot attendance confirm, and patient create/update.
• Endpoint reference — every path, scope, parameter, and response shape, all camelCase JSON with null fields omitted.
• The 428 protocol — the dance and all its edge cases: byte-identical resend, safe replay, expiry, confirmation_incomplete recovery.
• Error handling — the full code table with per-code recovery steps.
• Conversational & HIPAA rules — identity-first, never speak ids, read back before every commit, one clarifying question at a time.

Error handling

Every error is an RFC 7807 problem+json body with a stable machine code. Match on the code, never the prose.

Errors carry a type URL, a title, an HTTP status, a stable code, and a requestId, alongside an X-RSI-TRACE-ID response header. The title and detail are human strings and may carry no PHI by design — branch on code. On any escalation, quote the trace id so support can trace it; never read it to the patient.

{
  "type": "https://docs.redspotinteractive.com/api/problems/validation",
  "title": "One or more parameters are invalid.",
  "status": 422,
  "code": "validation",
  "errors": [ { "field": "to", "rule": "maxWindow", "message": "Window must be ≤ 14 days." } ],
  "requestId": "req_5f2c9a"
}

Problem registry

Every error body carries a type URL that resolves to one of these pages.

Branch your handling on the stable code, not on the HTTP status alone — several codes share a status (three distinct 409s, two 403s). The recovery column is the action a LLM agent should take on the call.

No codes match that filter.

confirmation_mismatch 409

The confirming request's body differs from the intent that was challenged, so nothing executes.

{
  "type": "https://docs.redspotinteractive.com/api/problems/confirmation_mismatch",
  "title": "The confirmation does not match the challenged request.",
  "status": 409,
  "code": "confirmation_mismatch",
  "requestId": "req_5f2c9a1b"
}

Why this happens

• A business field changed between the challenge and the confirm — the token is bound to a fingerprint of your exact fields, so any drift invalidates it.
• A second, different intent reused a token that was minted for the first one.

Nothing executes, and the original challenged intent stays valid until its expiresAt passes.

How to resolve

Related

• The 428 confirmation protocol — the full dance and its edge cases.
• confirmation_incomplete — token consumed, outcome unknown (a different 409).
• slot_unavailable — the slot was taken between search and book.

API reference

The full v1 endpoint surface — providers, patients, slots, appointments, and the directory.

{
  "items": [
    {
      "id": "slt_5ilAAt7KAbWjrAw8rDXHzb",
      "start": "2026-07-07T10:30:00-05:00",
      "end": "2026-07-07T11:00:00-05:00",
      "providerId": 201,
      "locationId": 101,
      "visitTypeId": 401,
      "procedureId": 301
    }
  ],
  "limit": 20
}

Read it back with GET /api/slots/{slotId} for the provider and location names — its available answers live (open slots are re-checked in the scheduling system inside the read) — then book via POST /api/appointments. See the booking playbook for the full sequence.

Downloads

Everything you need to wire an integration or brief a LLM-agent vendor.