Use this endpoint to partially update the
for Form filling sessions. Providing detailed context helps Suki generate more accurate structured form output.
This is a PATCH operation that allows partial updates to the session context.
The body of this request is optional. However, if you decide to provide context, you must provide valid values for the properties. When you send form_filling, each values[] entry must use exactly one of form_template_id or schema. Refer to Dynamic Form filling.
Python
TypeScript
from typing import Any, NotRequired, Optional, TypedDict, Union, castimport requestsBASE_URL = "https://sdp.suki-stage.com"class StaticFormEntry(TypedDict): # Suki Medical form template. Do not also send `schema` in this object. form_template_id: strclass DynamicFormEntry(TypedDict): # Partner-defined form. Do not also send `form_template_id` in this object. schema: dict[str, Any] id: NotRequired[str] name: NotRequired[str] type: NotRequired[str]FormFillingMetadata = Union[StaticFormEntry, DynamicFormEntry]class FormFillingContext(TypedDict): # Non-empty list. Mix static and dynamic entries when needed. values: list[FormFillingMetadata]class FormFillingUpdateContextRequest(TypedDict, total=False): form_filling: FormFillingContextclass FormFillingReturnedContext(TypedDict, total=False): form_filling: FormFillingContextclass FormFillingUpdateContextResponse(TypedDict): context: FormFillingReturnedContextclass ApiHttpError(RuntimeError): def __init__(self, status: int, url: str, detail: str) -> None: super().__init__(f"HTTP {status} {url}: {detail}") self.status = status self.url = urldef _patch_json_expect( url: str, headers: dict[str, str], payload: dict[str, Any], expect_status: int,) -> dict[str, Any]: r = requests.patch(url, json=payload, headers=headers, timeout=60) if r.status_code == expect_status: data = r.json() if isinstance(data, dict): return data raise ApiHttpError(expect_status, url, "response JSON was not an object") detail = "" try: err = r.json() if isinstance(err, dict) and isinstance(err.get("message"), str): detail = err["message"] except ValueError: detail = (r.text or "")[:500] raise ApiHttpError(r.status_code, url, detail or "(no body)")def login_for_suki_token(partner_id: str, partner_token: str, *, provider_id: Optional[str] = None) -> str: url = f"{BASE_URL}/api/v1/auth/login" body: dict[str, Any] = {"partner_id": partner_id, "partner_token": partner_token} if provider_id is not None: body["provider_id"] = provider_id r = requests.post(url, json=body, headers={"Content-Type": "application/json"}, timeout=60) if r.status_code != 200: raise ApiHttpError(r.status_code, url, (r.text or "")[:500] or "(no body)") data = r.json() token = data.get("suki_token") if isinstance(data, dict) else None if not isinstance(token, str) or not token: raise ValueError(f"{url}: 200 response missing suki_token") return tokendef update_form_filling_session_context( suki_token: str, ambient_session_id: str, body: FormFillingUpdateContextRequest,) -> FormFillingUpdateContextResponse: """PATCH /api/v1/form-filling/session/{ambient_session_id}/context. HTTP 200 returns FormFillingUpdateContextResponse.""" url = f"{BASE_URL}/api/v1/form-filling/session/{ambient_session_id}/context" headers = {"sdp_suki_token": suki_token, "sdp_provider_id": "<sdp_provider_id>", "Content-Type": "application/json"} data = _patch_json_expect(url, headers, dict(body), 200) ctx = data.get("context") if not isinstance(ctx, dict): raise ValueError(f"{url}: 200 response missing context") return cast(FormFillingUpdateContextResponse, {"context": cast(FormFillingReturnedContext, ctx)})if __name__ == "__main__": try: token = login_for_suki_token("<partner_id>", "<partner_token>") # Example mixes one Suki template and one partner schema. # Each values[] entry must use either form_template_id or schema, never both. out = update_form_filling_session_context( token, ambient_session_id="<ambient_session_id>", body={ "form_filling": { "values": [ {"form_template_id": "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0"}, { "id": "partner-custom-1", "name": "Custom Partner Form", "type": "NEURO_ASSESSMENT", "schema": { "type": "object", "properties": {"gcs": {"type": "number"}}, }, }, ] } }, ) form_filling = out["context"].get("form_filling") print(form_filling) except (ApiHttpError, ValueError) as e: print(e)
const BASE_URL = "https://sdp.suki-stage.com";// Suki Medical form template. Do not also send `schema` in this object.type StaticFormEntry = { form_template_id: string };// Partner-defined form. Do not also send `form_template_id` in this object.type DynamicFormEntry = { schema: Record<string, unknown>; id?: string; name?: string; type?: string;};type FormFillingMetadata = StaticFormEntry | DynamicFormEntry;type FormFillingContext = { values: FormFillingMetadata[] }; // non-empty; mix allowedtype FormFillingUpdateContextRequest = { form_filling?: FormFillingContext };type FormFillingReturnedContext = { form_filling?: FormFillingContext };type FormFillingUpdateContextResponse = { context: FormFillingReturnedContext };class ApiHttpError extends Error { status: number; url: string; constructor(status: number, url: string, detail: string) { super(`HTTP ${status} ${url}: ${detail}`); this.status = status; this.url = url; }}async function patchJsonExpectObject( url: string, init: RequestInit, expectStatus: number,): Promise<Record<string, unknown>> { const res = await fetch(url, init); const text = await res.text(); if (res.status !== expectStatus) { let msg = text.slice(0, 500); try { const data: unknown = text ? JSON.parse(text) : null; if (data && typeof data === "object" && "message" in data) { msg = String((data as { message?: string }).message ?? msg); } } catch { // keep raw text } throw new ApiHttpError(res.status, url, msg || "(no body)"); } if (!text) throw new ApiHttpError(res.status, url, "(empty body)"); const data: unknown = JSON.parse(text); if (data && typeof data === "object" && !Array.isArray(data)) { return data as Record<string, unknown>; } throw new ApiHttpError(res.status, url, "response JSON was not an object");}async function loginForSukiToken(body: { partner_id: string; partner_token: string; provider_id?: string;}): Promise<string> { const url = `${BASE_URL}/api/v1/auth/login`; const json = await patchJsonExpectObject( url, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body), }, 200, ); const token = json.suki_token; if (typeof token !== "string" || !token) throw new Error(`${url}: missing suki_token`); return token;}async function updateFormFillingSessionContext( sukiToken: string, ambientSessionId: string, body: FormFillingUpdateContextRequest,): Promise<FormFillingUpdateContextResponse> { const url = `${BASE_URL}/api/v1/form-filling/session/${ambientSessionId}/context`; const json = await patchJsonExpectObject( url, { method: "PATCH", headers: { sdp_suki_token: sukiToken, sdp_provider_id: "<sdp_provider_id>", "Content-Type": "application/json", }, body: JSON.stringify(body), }, 200, ); const context = json.context; if (!context || typeof context !== "object" || Array.isArray(context)) { throw new Error(`${url}: 200 response missing context`); } return { context: context as FormFillingReturnedContext };}async function main(): Promise<void> { try { const token = await loginForSukiToken({ partner_id: "<partner_id>", partner_token: "<partner_token>", }); // Example mixes one Suki template and one partner schema. // Each values[] entry must use either form_template_id or schema, never both. const out = await updateFormFillingSessionContext(token, "<ambient_session_id>", { form_filling: { values: [ { form_template_id: "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0" }, { id: "partner-custom-1", name: "Custom Partner Form", type: "NEURO_ASSESSMENT", schema: { type: "object", properties: { gcs: { type: "number" } }, }, }, ], }, }); console.log(out.context.form_filling); } catch (e) { console.error(e instanceof Error ? e.message : e); }}void main();
Authorizations
sdp_suki_token
string
header
required
Suki access token (suki_token) from Login or Register. Expires after one hour.
Headers
sdp_provider_id
string
Optional for standard partners.
Required for:
Bearer authentication. Use the same provider_id returned by the Login or Register API.
Single Auth Token authentication. Include the same provider_id on every request as sdp_provider_id.
Example:
"provider-123"
Path Parameters
ambient_session_id
string
required
Form-filling session ID. The path parameter is named ambient_session_id, but this value identifies the form-filling session, not an ambient clinical documentation session. Use the ID returned from Create Form filling Session, or the UUID you supplied in that request.
Body
application/json
Partial update for Form filling session context. Send only the fields you want to change.
form_filling
object
Updated forms to fill for this session.
Show child attributes
Response
Request succeeded.
Response body for the /api/v1/form-filling/session/{ambient_session_id}/context PATCH endpoint