> ## 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

> Introduction to the Suki Patient Summary APIs: FHIR ingestion, CKG-powered summary generation, and structured patient data retrieval

<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/suki-partners/" target="_blank" rel="noopener noreferrer">
      Contact Partnership Team
    </a>
  </div>
</Callout>

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**.
</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 same `sdp_suki_token` by calling the [Authentication](/patient-summary-api-reference/authentication) endpoints.
* Obtain `organization_id` during the [Partner onboarding](/documentation/get-started/partner-onboarding) process.
* Must be a RS256 signed JWT token with the `sdp_partner_id` claim.
* The token must be valid (not expired) and include required method scopes for the endpoint being called.

## 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 generate and sign SDP JWT bearer tokens for CKG Data Ingestion 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":"github-dark","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` for Patient Summary endpoints. Generate your SDP JWT bearer token for CKG Data Ingestion 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>

## Next steps

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