> ## Documentation Index
> Fetch the complete documentation index at: https://developer.suki.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Patient Summary APIs Overview

> Upload FHIR data, generate CKG-powered patient summaries asynchronously, and retrieve structured clinical sections with the Patient Summary APIs

export const ClientSdkLibrary = ({variant = "ambient"}) => {
  const IconGlobe = () => <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
      <circle cx="12" cy="12" r="10" />
      <path d="M12 2a14.5 14.5 0 0 0 0 20 14.5 14.5 0 0 0 0-20" />
      <path d="M2 12h20" />
    </svg>;
  const IconMobile = () => <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
      <rect width="14" height="20" x="5" y="2" rx="2" ry="2" />
      <path d="M12 18h.01" />
    </svg>;
  const IconReact = () => <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
      <path d="M16.5 9.4 7.55 4.24" />
      <path d="M21 16V8a2 2 0 0 0-1-1.73l-7-4a2 2 0 0 0-2 0l-7 4A2 2 0 0 0 2 8v8a2 2 0 0 0 1 1.73l7 4a2 2 0 0 0 2 0l7-4A2 2 0 0 0 21 16z" />
      <path d="M3.3 7 12 12l8.7-5" />
      <path d="M12 22V12" />
    </svg>;
  const IconMic = () => <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
      <path d="M12 2a3 3 0 0 0-3 3v7a3 3 0 0 0 6 0V5a3 3 0 0 0-3-3Z" />
      <path d="M19 10v2a7 7 0 0 1-14 0v-2" />
      <line x1="12" x2="12" y1="19" y2="22" />
    </svg>;
  const IconForm = () => <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
      <rect width="8" height="4" x="8" y="2" rx="1" ry="1" />
      <path d="M16 4h2a2 2 0 0 1 2 2v14a2 2 0 0 1-2 2H6a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h2" />
      <path d="M12 11h4" />
      <path d="M12 16h4" />
      <path d="M8 11h.01" />
      <path d="M8 16h.01" />
    </svg>;
  const IconSummary = () => <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true">
      <path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8Z" />
      <path d="M14 2v6h6" />
      <path d="M16 13H8" />
      <path d="M16 17H8" />
      <path d="M10 9H8" />
    </svg>;
  const icons = {
    web: <IconGlobe />,
    mobile: <IconMobile />,
    headless: <IconReact />,
    dictation: <IconMic />,
    form: <IconForm />,
    summary: <IconSummary />
  };
  const catalogs = {
    ambient: [{
      title: "Web SDK",
      desc: "Hosted ambient UI in the browser with JavaScript and React packages.",
      href: "/web-sdk/overview",
      icon: "web",
      iconClass: "hp-io-popular-item-icon--form-templates"
    }, {
      title: "Mobile SDK",
      desc: "Native iOS ambient capture with Swift for in-clinic and mobile workflows.",
      href: "/mobile-sdk/overview",
      icon: "mobile",
      iconClass: "hp-io-popular-item-icon--specialties"
    }, {
      title: "Headless Web SDK",
      desc: "Build a custom ambient UI with React hooks and PlatformClient.",
      href: "/headless-web-sdk/introduction",
      icon: "headless",
      iconClass: "hp-io-popular-item-icon--pbc"
    }, {
      title: "Dictation SDK",
      desc: "Hosted in-field or scratchpad Dictation for JavaScript and React.",
      href: "/dictation-sdk/introduction",
      icon: "dictation",
      iconClass: "hp-io-popular-item-icon--visit-prep"
    }],
    "form-filling": [{
      title: "Form Filling SDK",
      desc: "Standalone hosted Form filling UI for JavaScript and React apps.",
      href: "/form-filling-sdk/index",
      icon: "form",
      iconClass: "hp-io-popular-item-icon--form-templates"
    }, {
      title: "Web SDK",
      desc: "Use Form filling inside the headed Web SDK when you already embed it.",
      href: "/web-sdk/form-filling-overview",
      icon: "web",
      iconClass: "hp-io-popular-item-icon--specialties"
    }],
    "patient-summary": [{
      title: "Web SDK",
      desc: "Show pre-visit Patient Summary on the headed patient profile.",
      href: "/web-sdk/guides/patient-summary",
      icon: "summary",
      iconClass: "hp-io-popular-item-icon--visit-prep"
    }]
  };
  const items = catalogs[variant] || catalogs.ambient;
  return <div className="client-sdk-available" data-variant={variant}>
      <p className="client-sdk-available__label">Available SDKs for this Workflow:</p>
      <div className="client-sdk-available__grid">
        {items.map(item => <a key={item.href + item.title} href={item.href} className="hp-io-popular-item client-sdk-available__item">
            <span className={`hp-io-popular-item-icon ${item.iconClass}`} aria-hidden="true">
              {icons[item.icon]}
            </span>
            <span className="hp-io-popular-item-copy">
              <span className="hp-io-popular-item-title">{item.title}</span>
              <span className="hp-io-popular-item-desc">{item.desc}</span>
            </span>
            <span className="hp-io-popular-item-chevron" aria-hidden="true">
              ›
            </span>
          </a>)}
      </div>
    </div>;
};

export const AgentPrompt = ({id, collapseAfter = 2}) => {
  const [expanded, setExpanded] = useState(false);
  const [copied, setCopied] = useState(false);
  const __AGENT_PROMPT_DATA__ = {
    "DOCS_ORIGIN": "https://developer.suki.ai",
    "AGENT_PROMPTS": {
      "web-sdk": {
        "path": "web-sdk",
        "skillIds": ["suki-web-sdk"],
        "intro": "Help me add the Suki Web SDK to my web app so clinicians can run Ambient sessions with Suki's pre-built UI. I am a Suki partner with `partnerId` and `partnerToken`. Then:",
        "steps": ["Install `@suki-sdk/react` and `@suki-sdk/core` for React, or `@suki-sdk/js` and `@suki-sdk/core` for JavaScript.", "Create `SukiAuthManager` with `partnerId`, `partnerToken`, and provider fields, then initialize the SDK.", "Mount `SukiAssistant` (React) or the JS mount API with encounter context and run an Ambient session end to end.", "Handle note submission and write results back to my EHR when applicable."]
      },
      "headless-web-sdk": {
        "path": "headless-web-sdk",
        "skillIds": ["suki-headless-web-sdk"],
        "intro": "Help me add the Suki Headless Web SDK to my React app so I own the UI and use hooks for Ambient auth, sessions, and recording. I am a Suki partner with `partnerId` and `partnerToken`. Then:",
        "steps": ["Install `@suki-sdk/platform-react`.", "Create a `PlatformClient` and wrap the app with `PlatformClientProvider`.", "Authenticate with `useAuth`, create a session with `useAmbient`, then control recording with `useAmbientSession` (start, pause, resume, submit).", "Wire a minimal end-to-end Ambient flow and handle note retrieval or EHR write-back."]
      },
      "mobile-sdk": {
        "path": "mobile-sdk",
        "skillIds": ["suki-mobile-sdk"],
        "intro": "Help me add the Suki Mobile SDK to my native iOS app for Ambient documentation. I build the UI; the SDK manages sessions, recording, and note generation. I am a Suki partner with Partner credentials. Then:",
        "steps": ["Download `SukiAmbientCore.framework`, add it to Xcode, and set Embed and Sign.", "Add `NSMicrophoneUsageDescription` to `Info.plist`.", "Configure the SDK with Partner credentials and a `TokenProvider` that returns a valid Partner Token.", "Create an Ambient session, start and stop recording, then retrieve generated note content for EHR write-back."]
      },
      "dictation-sdk": {
        "path": "dictation-sdk",
        "skillIds": ["suki-dictation-sdk"],
        "intro": "Help me add the Suki Dictation SDK to my web app with Suki's hosted iframe UI for In-field or Scratchpad Dictation. I am a Suki partner with `partnerId` and `partnerToken`. Then:",
        "steps": ["Install `@suki-sdk/dictation` and `@suki-sdk/core` for JavaScript, or `@suki-sdk/dictation-react`, `@suki-sdk/dictation`, and `@suki-sdk/core` for React.", "Create a long-lived `SukiAuthManager` and one `DictationClient` per page scope (do not recreate on every render).", "Mount In-field or Scratchpad Dictation with encounter context and handle transcript callbacks into chart fields.", "Reuse the same client across fields; only change the target field or container."]
      },
      "form-filling-sdk": {
        "path": "form-filling-sdk",
        "skillIds": ["suki-form-filling-sdk"],
        "intro": "Help me add the Suki Form filling SDK to my web app so clinicians can complete Medical form templates by voice with Suki's hosted iframe UI. I am a Suki partner with `partnerId`, `partnerToken`, and `form_template_ids`. Then:",
        "steps": ["Install `@suki-sdk/form-filling` and `@suki-sdk/core` for JavaScript, or `@suki-sdk/form-filling-react` and `@suki-sdk/core` for React.", "Create `SukiAuthManager` and `FormFillingClient` with Partner credentials.", "Start a session with `form_template_ids` and my encounter ID as `correlation_id`.", "Handle submit callbacks or webhook results and map structured form data into my EHR."]
      },
      "ambient": {
        "path": "documentation/concepts/ambient-clinical-notes",
        "skillIds": ["suki-ambient"],
        "intro": "Help me integrate Suki Ambient clinical documentation so I can generate structured clinical notes from patient-provider conversations. I am a Suki partner. Choose the right path (Partner APIs or an SDK), then:",
        "steps": ["Confirm Partner onboarding, JWKS, and credentials for staging (`https://sdp.suki-stage.com`).", "Create an ambient session, optionally seed visit context, then stream audio over `/ws/stream`.", "End the session, wait for processing (poll status or webhook), then retrieve note content and transcript.", "If I need a headed UI, use the Web SDK; if I own the UI in React, use the Headless Web SDK; for iOS, use the Mobile SDK."]
      },
      "form-filling": {
        "path": "documentation/concepts/form-filling",
        "skillIds": ["suki-form-filling"],
        "intro": "Help me integrate Suki Form filling so I can capture structured medical form data from visit conversation. I am a Suki partner with Medical form template IDs (`form_template_id` UUIDs). Then:",
        "steps": ["Choose Partner APIs, the Form filling SDK, or Form filling inside the Web SDK based on whether I own the UI.", "Create a Form filling session and provide `form_template_id` values (or a partner dynamic form schema) before streaming.", "Stream audio over `/ws/stream` with the Form filling `ambient_session_id`, then end the session.", "Retrieve structured form output and map fields into my EHR."]
      },
      "dictation": {
        "path": "documentation/concepts/dictation",
        "skillIds": ["suki-dictation"],
        "intro": "Help me integrate Suki Audio Dictation so providers can convert speech into real-time text in my application. I am a Suki partner. Then:",
        "steps": ["Choose Partner APIs, the Dictation SDK, or Dictation inside the Web SDK based on whether I own the UI.", "Create a Dictation session, then stream audio over WebSocket.", "Handle partial and final transcript frames and place text into the target chart field or UI.", "Complete the stream cleanly and end the session with REST when finished."]
      },
      "patient-summary": {
        "path": "documentation/concepts/patient-summary",
        "skillIds": ["suki-patient-summary"],
        "intro": "Help me integrate Suki Patient Summary so I can generate pre-visit and full patient summaries from Clinical Knowledge Graph (CKG) data. I am a Suki partner. Then:",
        "steps": ["Authenticate and obtain an `sdp_suki_token`.", "Request a CKG upload URL, upload a FHIR R4 bundle, and poll ingestion status until complete.", "Trigger summary generation for an encounter and practitioner pair, then poll job status.", "Retrieve the full Patient Summary or pre-visit section (or show it on the Web SDK patient profile)."]
      },
      "audio-streaming": {
        "path": "documentation/how-to/audio-streaming",
        "skillIds": ["suki-audio-streaming"],
        "intro": "Help me implement Suki Partner API audio streaming so I can create a session, open a WebSocket, send live audio frames, and complete the session cleanly. I am a Suki partner. Then:",
        "steps": ["Authenticate and create an Ambient or Dictation session with REST to get the session ID.", "Open `wss://sdp.suki-stage.com/ws/stream` (or production) and send JSON text frames for that product's wire format.", "Send audio as required (for example LINEAR16 PCM for Ambient), plus control events for the product.", "End the stream cleanly, finish the session with REST, then retrieve results or wait for a webhook."]
      },
      "webhooks": {
        "path": "documentation/webhook",
        "skillIds": ["suki-webhooks"],
        "intro": "Help me add a Suki notification webhook so my app receives push events when Ambient sessions complete or fail. I am a Suki partner with a signing secret from onboarding. Then:",
        "steps": ["Provide Suki an HTTPS callback URL during partner onboarding (one URL per partner).", "Implement a POST endpoint that verifies the HMAC signature with my partner secret.", "Parse the event payload, process supported event types, and return a successful HTTP response.", "Test with a real Ambient session end-to-end and handle retries safely."]
      },
      "faqs": {
        "path": "documentation/references/faqs",
        "skillIds": [],
        "intro": "Help me answer common Suki for Partners integration questions using the published FAQ topics. Prefer official docs over guesses. Then:",
        "steps": ["Connect Documentation MCP: `https://developer.suki.ai/documentation/references/mcp`.", "Use `https://developer.suki.ai/llms.txt` to find the right FAQ or guide page.", "Start from this FAQs hub and open the matching topic (general, authentication, security, Ambient, Form filling, Dictation, SDKs, or webhooks).", "Cite the FAQ or guide URL in your answer, and escalate to partner support only when the docs do not cover the question."]
      },
      "api-reference": {
        "path": "api-reference/overview",
        "skillIds": ["suki-ambient-api", "suki-dictation-api"],
        "intro": "Help me integrate Suki Ambient and Dictation Partner APIs so I can create sessions, stream audio over WebSocket, and retrieve notes or transcripts. I am a Suki partner. Then:",
        "steps": ["Authenticate and obtain an `sdp_suki_token` on staging (`https://sdp.suki-stage.com`).", "For Ambient: create a session, stream over `/ws/stream`, end the session, then retrieve note content (or use a webhook).", "For Dictation: create a Dictation session, stream audio, and handle partial and final transcript frames.", "Follow the Ambient API quickstart for a complete staging script before production."]
      },
      "form-filling-api": {
        "path": "form-filling-api-reference/overview",
        "skillIds": ["suki-form-filling-api"],
        "intro": "Help me integrate Suki Form filling Partner APIs so I can create Form filling sessions, stream audio, and retrieve structured form output. I am a Suki partner with `form_template_id` values (or a dynamic form schema). Then:",
        "steps": ["Authenticate and obtain an `sdp_suki_token` on staging.", "Create a Form filling session and seed `form_template_id` (or partner schema) context.", "Stream audio over `/ws/stream` using the Form filling `ambient_session_id`, then end the session.", "Retrieve structured form output (or rely on a webhook) and map fields into my EHR."]
      },
      "patient-summary-api": {
        "path": "patient-summary-api-reference/overview",
        "skillIds": ["suki-patient-summary-api"],
        "intro": "Help me integrate Suki Patient Summary Partner APIs so I can ingest FHIR into CKG, generate summaries, and retrieve structured sections. I am a Suki partner. Then:",
        "steps": ["Authenticate and obtain an `sdp_suki_token`.", "Request a CKG upload URL, upload a FHIR R4 bundle, and poll ingestion status.", "Trigger summary generation for an encounter and practitioner pair, then poll the job.", "Retrieve the full Patient Summary or pre-visit section from the Summaries APIs."]
      }
    }
  };
  const entry = id ? __AGENT_PROMPT_DATA__.AGENT_PROMPTS[id] : null;
  if (!entry) {
    return <div className="suki-agent-prompt suki-agent-prompt--error" data-suki-agent-prompt>
        <div className="suki-agent-prompt__body">
          <p className="suki-agent-prompt__intro">
            Agent Prompt <code>{id || "(missing id)"}</code> is not in the registry. Run{" "}
            <code>npm run sync:agent-prompts</code>.
          </p>
        </div>
      </div>;
  }
  const docsOrigin = __AGENT_PROMPT_DATA__.DOCS_ORIGIN || "https://developer.suki.ai";
  const skillIds = Array.isArray(entry.skillIds) ? entry.skillIds : [];
  let skillCmd = `npx skills add ${docsOrigin}`;
  for (let i = 0; i < skillIds.length; i++) {
    skillCmd += ` --skill ${skillIds[i]}`;
  }
  const intro = entry.intro || "";
  const steps = [];
  if (skillIds.length > 0) {
    steps.push(`Run \`${skillCmd}\`.`);
  }
  if (Array.isArray(entry.steps)) {
    for (let i = 0; i < entry.steps.length; i++) steps.push(entry.steps[i]);
  }
  const reference = `${docsOrigin}/${entry.path}.md`;
  const renderInlineCode = text => {
    if (!text) return null;
    const parts = String(text).split(/(`[^`]+`)/g);
    return parts.map((part, i) => {
      if (part.startsWith("`") && part.endsWith("`") && part.length > 2) {
        return <code className="suki-agent-prompt__code" key={i}>
            {part.slice(1, -1)}
          </code>;
      }
      return part ? <span key={i}>{part}</span> : null;
    });
  };
  const copyText = (() => {
    const lines = [intro, ""];
    steps.forEach((step, i) => {
      lines.push(`${i + 1}. ${step}`);
    });
    if (reference) {
      lines.push("");
      lines.push("REFERENCE");
      lines.push(reference);
    }
    return lines.join("\n");
  })();
  const canCollapse = steps.length > collapseAfter;
  const visibleSteps = !canCollapse || expanded ? steps : steps.slice(0, collapseAfter);
  const handleCopy = () => {
    const done = () => {
      setCopied(true);
      setTimeout(() => setCopied(false), 2000);
    };
    if (navigator.clipboard && window.isSecureContext) {
      navigator.clipboard.writeText(copyText).then(done).catch(() => {});
      return;
    }
    const textarea = document.createElement("textarea");
    textarea.value = copyText;
    textarea.setAttribute("readonly", "");
    textarea.style.position = "fixed";
    textarea.style.left = "-9999px";
    document.body.appendChild(textarea);
    textarea.select();
    try {
      document.execCommand("copy");
      done();
    } catch (e) {} finally {
      document.body.removeChild(textarea);
    }
  };
  return <div className={`suki-agent-prompt${canCollapse && !expanded ? " is-collapsed" : ""}${copied ? " is-copied" : ""}`} data-suki-agent-prompt data-agent-prompt-id={id}>
      <div className="suki-agent-prompt__header">
        <span className="suki-agent-prompt__label">
          Using AI coding tools, Try Agent prompt
        </span>
        <button type="button" className="suki-agent-prompt__copy size-6.5 flex items-center justify-center rounded-md group/copy-button" onClick={handleCopy} aria-label={copied ? "Copied" : "Copy agent prompt"} data-tooltip={copied ? "Copied" : "Copy"}>
          {copied ? <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true" className="size-4 shrink-0 text-primary dark:text-primary-light">
              <path d="M2.75 9.5L6.5 13.25L15.25 4.5" />
            </svg> : <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 18 18" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round" strokeLinejoin="round" aria-hidden="true" className="size-4 shrink-0 text-gray-400 group-hover/copy-button:text-gray-500 dark:text-white/40 dark:group-hover/copy-button:text-white/60">
              <path d="M14.25 5.25H7.25C6.14543 5.25 5.25 6.14543 5.25 7.25V14.25C5.25 15.3546 6.14543 16.25 7.25 16.25H14.25C15.3546 16.25 16.25 15.3546 16.25 14.25V7.25C16.25 6.14543 15.3546 5.25 14.25 5.25Z" />
              <path d="M2.80103 11.998L1.77203 5.07397C1.61003 3.98097 2.36403 2.96397 3.45603 2.80197L10.38 1.77297C11.313 1.63397 12.19 2.16297 12.528 3.00097" />
            </svg>}
        </button>
      </div>

      <div className="suki-agent-prompt__body">
        <div className={`suki-agent-prompt__shimmer not-prose${canCollapse && !expanded ? " is-shimmering" : ""}`}>
          {intro ? <p className="suki-agent-prompt__intro">{renderInlineCode(intro)}</p> : null}
          {visibleSteps.length > 0 ? <ol className="suki-agent-prompt__steps">
              {visibleSteps.map((step, i) => <li key={i}>{renderInlineCode(step)}</li>)}
            </ol> : null}
        </div>
        {reference && (!canCollapse || expanded) ? <div className="suki-agent-prompt__reference">
            <div className="suki-agent-prompt__reference-label">REFERENCE</div>
            <a className="link" href={reference} target="_blank" rel="noopener noreferrer">
              {reference}
            </a>
          </div> : null}
        {canCollapse && !expanded ? <div className="suki-agent-prompt__fade" aria-hidden="true" /> : null}
      </div>

      {canCollapse ? <div className="suki-agent-prompt__footer">
          <button type="button" className="suki-agent-prompt__toggle" onClick={() => setExpanded(v => !v)} aria-expanded={expanded}>
            <span>{expanded ? "Show less" : "Show more"}</span>
            <svg className={`suki-agent-prompt__chevron${expanded ? " is-up" : ""}`} viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" aria-hidden="true">
              <polyline points="6 9 12 15 18 9" />
            </svg>
          </button>
        </div> : null}
    </div>;
};

<Callout icon="handshake" color="orange">
  **Are you a Suki partner?**

  To use any Suki API or SDK, you must be a Suki partner. Contact the partnership team to begin the onboarding process. They help you set up your authentication system and get started with the Suki APIs and SDKs.

  <div style={{ marginTop: '0.75rem' }}>
    <a className="doc-guide-btn partner-contact-cta" href="https://www.suki.ai/contact-us/" target="_blank" rel="noopener noreferrer">
      Contact Partnership Team
    </a>
  </div>
</Callout>

<AgentPrompt id="patient-summary-api" />

Suki Patient Summary APIs let you generate AI-powered summaries for patients from FHIR data. Upload FHIR data to Suki's <Tooltip tip="Suki's Clinical Knowledge Graph (CKG) processes and structures clinical data from FHIR bundles to generate Patient Summaries.">Clinical Knowledge Graph (CKG)</Tooltip>, start an asynchronous summary generation job, and retrieve the completed summary using Patient Summary REST APIs.

Patient summaries provide clinicians with a concise view of a patient's clinical information, explicitly returned as four structured sections: About Visit, Patient Summary, Previous Visit, and Problems. You can generate summaries for **completed patient encounters** or **future scheduled appointments**.

<Note>
  Patient Summaries are generated from data available in Suki's Clinical Knowledge Graph (CKG). Summary quality depends on the completeness, accuracy, and freshness of the **ingested clinical data**. Make sure to ingest the latest data for the best summary quality.
</Note>

## Available APIs

The following set of APIs are available for the Patient Summary generation workflow. View each card below to learn about the endpoints and how to use them.

<CardGroup cols={3}>
  <Card title="Authentication" icon="key" href="/patient-summary-api-reference/authentication" arrow={true}>
    Endpoints to authenticate and obtain tokens used to authorize Patient Summary API requests.
  </Card>

  <Card title="CKG Data Ingestion" icon="upload" href="/patient-summary-api-reference/ckg-data-ingestion" arrow={true}>
    Endpoints to upload FHIR bundles into CKG so summaries can be generated.
  </Card>

  <Card title="Summary Generation" icon="waveform" href="/patient-summary-api-reference/summary-generation" arrow={true}>
    Endpoints to trigger asynchronous summary generation jobs.
  </Card>

  <Card title="Patient Summaries" icon="file-lines" href="/patient-summary-api-reference/summaries" arrow={true}>
    Endpoints to retrieve full summaries and pre-visit summaries.
  </Card>

  <Card title="Summary Jobs" icon="clock" href="/patient-summary-api-reference/summary-jobs" arrow={true}>
    Endpoints to poll generation status and track job progress.
  </Card>
</CardGroup>

## Authentication

For an overview of Suki's supported authentication mechanisms refer to [Authentication mechanisms](/documentation/how-to/partner-authentication). We recommend using OAuth 2.0 with JWT tokens for your authentication system.

If you know what your authentication model is, refer to the following guides to get started:

<CardGroup cols={3}>
  <Card title="Single Auth Token Authentication" icon="Key" href="/api-reference/single-auth-token-authentication" horizontal />

  <Card title="Standard Provider Authentication" icon="User" href="/api-reference/provider-authentication" horizontal />

  <Card title="Bearer Partner Authentication" icon="Shield-Halved" href="/api-reference/bearer-partner-authentication" horizontal />
</CardGroup>

**For CKG Data Ingestion endpoints:**

* Use the same `sdp_suki_token` from the [Authentication](/patient-summary-api-reference/authentication) Login (or Register) endpoints.
* Pass `organization_id`: your own partner organization ID for your organization, chosen at onboarding. This can be a UUID or non-UUID string. But not a Suki UUID. See [Partner onboarding](/documentation/get-started/partner-onboarding) for more details.
* The token must be valid (not expired).

## Client SDKs

Suki provides a <Tooltip tip="An SDK that runs on the end-user device (browser or native app) rather than on your backend server. All Suki SDKs are Client SDKs." cta="View in Glossary" href="/Glossary/c">Client SDK</Tooltip> path for Patient Summary capabilities. The [Web SDK](/web-sdk/overview) shows a pre-visit Patient Summary on the headed patient profile when the capability is enabled for your organization and you pass matching encounter and practitioner FHIR identifiers.

<ClientSdkLibrary variant="patient-summary" />

<AccordionGroup>
  <Accordion title="Benefits" icon="star">
    * Hosted Patient Summary UI on the patient profile
    * Snippet preview with expand to the full summary
    * No client-side generate, status, or retrieve calls for the headed Web SDK path
    * Type-safe Web SDK APIs for initialize and mount configuration
  </Accordion>

  <Accordion title="Use the APIs for" icon="gear">
    * Uploading FHIR data to the Clinical Knowledge Graph (CKG)
    * Starting asynchronous Patient Summary generation jobs
    * Polling job status until generation completes
    * Retrieving full or pre-visit Patient Summaries
    * Building a custom Patient Summary UI outside the headed Web SDK

    You can use the Web SDK for display and the Patient Summary APIs for ingestion and generation, depending on how much of the workflow you want to control.
  </Accordion>
</AccordionGroup>

## Key capabilities

The Patient Summary APIs provide the following capabilities, so you can upload clinical data, generate AI-powered Patient Summaries, and retrieve structured insights for pre-visit preparation and clinical workflows.

<CardGroup cols={2}>
  <Card title="FHIR Data Ingestion" icon="upload">
    Upload FHIR bundles to Suki's Clinical Knowledge Graph (CKG) using pre-signed upload URLs, then poll ingestion status until processing completes.
  </Card>

  <Card title="AI-Generated Patient Summaries" icon="file-lines">
    Trigger asynchronous summary generation for encounters or scheduled appointments, then retrieve comprehensive Patient Summaries with clinical history, medications, and diagnoses.
  </Card>

  <Card title="Pre-Visit Summaries" icon="clock">
    Retrieve the pre-visit section of a Patient Summary using a dedicated endpoint, created specifically for the user interface (UI) to display a preview to the provider.
  </Card>

  <Card title="Encounter and Practitioner Scoping" icon="user">
    Retrieve summaries scoped to specific encounter and practitioner identifiers, so each clinician sees summaries relevant to their scheduled patients.
  </Card>

  <Card title="Asynchronous Processing" icon="waveform">
    Trigger summary generation jobs and poll job status until completion, allowing your application to handle long-running summary generation without blocking.
  </Card>

  <Card title="Structured Clinical Data" icon="table">
    Retrieve Patient Summaries with four specific sections: About Visit, Patient Summary, Previous Visit, and Problems, for EHR integration and review workflows.
  </Card>
</CardGroup>

## Requirements

Before you can use the Patient Summary APIs, you need to meet the following requirements:

* You must be a Suki partner. Learn more about how to become a Suki partner in the [Partner onboarding](/documentation/get-started/partner-onboarding) documentation.
* A standards-based authentication system (for example OAuth 2.0 or OpenID Connect with JWTs) for Patient Summary authentication.
* Ability to call Login (and Register when needed) to obtain an `sdp_suki_token` for CKG Data Ingestion and Patient Summary endpoints.
* FHIR R4 bundles containing patient clinical data (for example conditions, medications, encounters, observations).
* Patient, encounter, and practitioner identifiers that **remain consistent** across FHIR uploads and summary retrieval requests.

## What you can build

Use the Patient Summary APIs to build custom workflows for generating and displaying AI-powered Patient Summaries. Control when summaries are generated, how FHIR data is uploaded, and how summaries are presented or integrated into your product.

You can align Patient Summary workflows with:

* Pre-visit preparation and appointment scheduling.
* Clinical decision support and care coordination.
* Patient chart review and encounter preparation.
* EHR integration and clinical workflow optimization.

Implement your own logic for FHIR data upload, summary generation triggers, status polling, and downstream handoff, and connect to your EHR, scheduling system, or internal clinical workflows using the Patient Summary REST APIs.

### Common use cases

<CardGroup cols={3}>
  <Card title="Pre-Visit Patient Summaries" icon="clock">
    Upload FHIR data before scheduled appointments, generate summaries for upcoming encounters, then display the retrieved pre-visit section as a preview in the provider's schedule interface.
  </Card>

  <Card title="Encounter-Based Summary Generation" icon="waveform">
    Trigger summary generation for active encounters, poll job status until completion, then retrieve comprehensive Patient Summaries for clinical review before or during the visit.
  </Card>

  <Card title="EHR-Integrated Patient Summaries" icon="database">
    Map FHIR clinical data from your EHR, generate summaries through the API, then integrate retrieved summaries back into your EHR review workflows or clinician dashboards.
  </Card>
</CardGroup>

## API versioning

All endpoints use the `/api/v1/` prefix. **v1** is the stable version. Non-breaking changes may ship without a major version jump. For policies and migration, refer to [API guidelines](/api-reference/api-guidelines).

<Note>
  These APIs may include Early Access features. If you are unsure what is enabled for your account, contact your Suki representative.
</Note>

## Suki Patient Summary APIs workflow

To integrate with the Patient Summary APIs, you follow a CKG ingestion and summary generation workflow.

```mermaid actions={false} theme={"theme":{"light":"one-light","dark":"material-theme-darker"}}
flowchart TD
  Start([Start integration]) --> Auth[Authenticate and obtain tokens]
  Auth --> UploadURL[Request CKG upload URL]
  UploadURL --> Upload[Upload FHIR bundle PUT upload_url]
  Upload --> IngestPoll[Poll ingestion status]
  IngestPoll --> IngestDone{Ingestion complete?}
  IngestDone -->|No| IngestPoll
  IngestDone -->|Yes| Generate[Trigger summary generation]
  Generate --> StatusPoll[Poll summary job status]
  StatusPoll --> JobDone{Job complete?}
  JobDone -->|No| StatusPoll
  JobDone -->|Yes| RetrieveFull[Retrieve full Patient Summary]
  JobDone -->|Yes| RetrievePreVisit[Retrieve pre-visit summary]
  RetrieveFull --> Complete([Workflow complete])
  RetrievePreVisit --> Complete
  
  classDef authStyle fill:#FFE148,stroke:#D4A017,stroke-width:2px,color:#000000
  classDef highlightStyle fill:#FFD700,stroke:#D4A017,stroke-width:3px,color:#000000
  
  class Auth,Generate,Upload authStyle
  class RetrieveFull,RetrievePreVisit highlightStyle
```

### Developer workflow

<Steps>
  <Step title="Authenticate and Obtain Tokens" icon="key">
    Authenticate using Login or Register to obtain your `sdp_suki_token`. Use the same token for CKG Data Ingestion and Patient Summary endpoints.
  </Step>

  <Step title="Upload FHIR Data to CKG" icon="upload">
    Request a pre-signed upload URL from the CKG Data Ingestion API, upload your FHIR bundle JSON to the returned `upload_url`, and poll ingestion status until processing completes.
  </Step>

  <Step title="Trigger Patient Summary Generation" icon="waveform">
    Trigger asynchronous summary generation for an encounter or a provider's scheduled appointments using the Summary Generation endpoints.
  </Step>

  <Step title="Poll Summary Job Status" icon="clock">
    Poll the Summary Jobs endpoints to track generation progress until the job reaches a terminal status (completed, failed, or archived).
  </Step>

  <Step title="Retrieve Patient Summaries" icon="file-lines">
    Retrieve the full Patient Summary or the pre-visit section through the Patient Summaries endpoints when generation completes.
  </Step>
</Steps>

<Tip>
  **Best practices**

  * Store authentication credentials securely and rotate per your security policy.
  * Use consistent identifiers across FHIR uploads and summary retrieval requests.
  * Poll ingestion and generation status with appropriate intervals to avoid rate limits.
  * Handle error responses from terminal job statuses and retry failed uploads or generation requests when appropriate.
</Tip>

## Resources

Refer to the following resources to learn about security, HTTPS requirements, and API guidelines.

<CardGroup cols={3}>
  <Card title="Security & Best Practices" icon="shield-halved" href="/api-reference/security-best-practices" arrow={true}>
    Review token handling, transport security, and partner integration safeguards.
  </Card>

  <Card title="HTTPS Guidelines" icon="lock" href="/api-reference/https-guidelines" arrow={true}>
    Confirm TLS, headers, and HTTPS requirements for API and WebSocket traffic.
  </Card>

  <Card title="API Reference Guidelines" icon="book" href="/api-reference/api-guidelines" arrow={true}>
    Read versioning, error handling, and REST conventions for Suki APIs.
  </Card>
</CardGroup>

## Next steps

<Icon icon="file-lines" iconType="solid" /> Refer to the [Patient Summary API quickstart](/patient-summary-api-reference/quickstart) to get started.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.