Create a clinical summary for a given patient

curl --request POST \
  --url https://api.{workspaceId}.clinia.cloud/ai/v1/summaries \
  --header 'Content-Type: application/json' \
  --data '
{
  "patientId": "<string>",
  "summaryTemplateId": "<string>"
}
'

import requests

url = "https://api.{workspaceId}.clinia.cloud/ai/v1/summaries"

payload = {
    "patientId": "<string>",
    "summaryTemplateId": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({patientId: '<string>', summaryTemplateId: '<string>'})
};

fetch('https://api.{workspaceId}.clinia.cloud/ai/v1/summaries', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.{workspaceId}.clinia.cloud/ai/v1/summaries",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'patientId' => '<string>',
    'summaryTemplateId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.{workspaceId}.clinia.cloud/ai/v1/summaries"

	payload := strings.NewReader("{\n  \"patientId\": \"<string>\",\n  \"summaryTemplateId\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.{workspaceId}.clinia.cloud/ai/v1/summaries")
  .header("Content-Type", "application/json")
  .body("{\n  \"patientId\": \"<string>\",\n  \"summaryTemplateId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.{workspaceId}.clinia.cloud/ai/v1/summaries")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"patientId\": \"<string>\",\n  \"summaryTemplateId\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "type": "text-delta",
    "payload": {
      "text": "<string>",
      "sectionTitle": "<string>",
      "sectionIndex": 1
    }
  },
  "id": "<string>",
  "event": "<string>"
}

{
  "code": 400,
  "type": "INVALID_ARGUMENT",
  "message": "Invalid request parameters"
}

{
  "code": 401,
  "type": "UNAUTHENTICATED",
  "message": "Unauthenticated"
}

{
  "code": 403,
  "type": "PERMISSION_DENIED",
  "message": "Permission denied"
}

{
  "code": 404,
  "type": "NOT_FOUND",
  "message": "Resource not found"
}

{
  "code": 500,
  "type": "INTERNAL",
  "message": "Internal Server Error"
}

POST

summaries

Create a clinical summary for a given patient

curl --request POST \
  --url https://api.{workspaceId}.clinia.cloud/ai/v1/summaries \
  --header 'Content-Type: application/json' \
  --data '
{
  "patientId": "<string>",
  "summaryTemplateId": "<string>"
}
'

import requests

url = "https://api.{workspaceId}.clinia.cloud/ai/v1/summaries"

payload = {
    "patientId": "<string>",
    "summaryTemplateId": "<string>"
}
headers = {"Content-Type": "application/json"}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({patientId: '<string>', summaryTemplateId: '<string>'})
};

fetch('https://api.{workspaceId}.clinia.cloud/ai/v1/summaries', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.{workspaceId}.clinia.cloud/ai/v1/summaries",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'patientId' => '<string>',
    'summaryTemplateId' => '<string>'
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.{workspaceId}.clinia.cloud/ai/v1/summaries"

	payload := strings.NewReader("{\n  \"patientId\": \"<string>\",\n  \"summaryTemplateId\": \"<string>\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.{workspaceId}.clinia.cloud/ai/v1/summaries")
  .header("Content-Type", "application/json")
  .body("{\n  \"patientId\": \"<string>\",\n  \"summaryTemplateId\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.{workspaceId}.clinia.cloud/ai/v1/summaries")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"patientId\": \"<string>\",\n  \"summaryTemplateId\": \"<string>\"\n}"

response = http.request(request)
puts response.read_body

{
  "data": {
    "type": "text-delta",
    "payload": {
      "text": "<string>",
      "sectionTitle": "<string>",
      "sectionIndex": 1
    }
  },
  "id": "<string>",
  "event": "<string>"
}

{
  "code": 400,
  "type": "INVALID_ARGUMENT",
  "message": "Invalid request parameters"
}

{
  "code": 401,
  "type": "UNAUTHENTICATED",
  "message": "Unauthenticated"
}

{
  "code": 403,
  "type": "PERMISSION_DENIED",
  "message": "Permission denied"
}

{
  "code": 404,
  "type": "NOT_FOUND",
  "message": "Resource not found"
}

{
  "code": 500,
  "type": "INTERNAL",
  "message": "Internal Server Error"
}

Streaming results are forwarded as Server-Sent Events (SSE) with each event containing a JSON payload.

{
  "data": {
    "type": "text-delta",
    "payload": {
      "sectionTitle": "History of Present Illness",
      "sectionIndex": 0,
      "text": "Patient presents..."
    }
  },
  "id": "5"
}

In this implementation, the SSE event field is omitted. Differentiate event kinds using data.type. Raw SSE framing over the wire looks like:

id: 5
data: {"type":"text-delta","payload":{"sectionTitle":"History of Present Illness","sectionIndex":0,"text":"Patient presents..."}}

Possible Payload shapes

There can be multiple text-start events, one per section of the summary template. Each text-start event will be followed by one or more text-delta events with the same sectionTitle and sectionIndex, and eventually a text-end event.

{
  "type": "text-start",
  "payload": {
    "sectionTitle": string,
    "sectionIndex": number,
  }
}

{
  "type": "text-delta",
  "payload": {
    "sectionTitle": string,
    "sectionIndex": number,
    "text": string, // this is a delta, so you should append it to the previous text for this section
  }
}

{
  "type": "text-end",
  "payload": {
    "sectionTitle": string,
    "sectionIndex": number,
  }
}

After all sections have been streamed, there will be a summary-end event indicating that the summary generation workflow has completed. If the status field in the payload is success, the summary has been persisted and can be retrieved with the provided summaryId. If the status is error, the summary generation has failed and the error message will be included in the payload.

{
  "type": "summary-end",
  "payload": {
    "status": "success",
    "summaryId": string,
  }
}

OR

{
  "type": "summary-end",
  "payload": {
    "status": "error",
    "error": string,
  }
}

Example SSE Stream

id: 1
data: {"type":"text-start","payload":{"sectionTitle":"History of Present Illness","sectionIndex":0}}

id: 2
data: {"type":"text-delta","payload":{"text":"Patient reports progressive shortness of breath over 3 days.","sectionTitle":"History of Present Illness","sectionIndex":0}}

id: 3
data: {"type":"text-start","payload":{"sectionTitle":"Medications","sectionIndex":1}}

id: 4
data: {"type":"text-delta","payload":{"text":"Lisinopril 10 mg once daily.","sectionTitle":"Medications","sectionIndex":1}}

id: 5
data: {"type":"text-delta","payload":{"text":"No chest pain, fever, or recent travel were reported.","sectionTitle":"History of Present Illness","sectionIndex":0}}

id: 6
data: {"type":"text-delta","payload":{"text":"Metformin 500 mg twice daily with meals.","sectionTitle":"Medications","sectionIndex":1}}

id: 7
data: {"type":"text-end","payload":{"sectionTitle":"History of Present Illness","sectionIndex":0}}

id: 8
data: {"type":"text-end","payload":{"sectionTitle":"Medications","sectionIndex":1}}

id: 9
data: {"type":"summary-end","payload":{"status":"success","summaryId":"sum_01JABZX3V4Q2P2M41ME6E3FQ7R"}}

Headers

x-user-id

string

The ID of the user making the request. Used to associate the request with a specific user.

Body

application/json

patientId

string

required

The patient id that we want to create a clinical summary for. This should be the same patient id used during ingestion.

summaryTemplateId

string

required

ID of a summary template. This can be retrieved via GET /summary-templates.

Response

Summary workflow event stream

Option 1
Option 2
Option 3
Option 4

data

object

required

Show child attributes

string

event

string

Data Catalog Endpoints

Data Partition Endpoints

MDM Endpoints

Registry Endpoints

Terminology Endpoints

Operations Endpoints

AI Engine

Create a clinical summary for a given patient

Possible Payload shapes

Example SSE Stream

Headers

Body

Response

​Possible Payload shapes

​Example SSE Stream

Headers

Body

Response

Possible Payload shapes

Example SSE Stream