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

# Update Form Filling Session Context

> Partially update Form filling session context using the Form filling URL binding

Use this endpoint to partially update the
<Tooltip tip="Metadata provided when creating an ambient session that helps guide note generation and improve output quality." cta="View in Glossary" href="/Glossary/s">session context</Tooltip>
for Form filling sessions. Providing detailed context helps Suki generate a more accurate and relevant <Tooltip tip="The final structured medical documentation generated from a patient encounter, organized into standardized sections using LOINC codes." cta="View in Glossary" href="/Glossary/c">clinical note</Tooltip>.
This is a **PATCH** operation that allows partial updates to the session context.

<Note>
  The body of this request is optional. However, if you decide to provide context, you must provide **valid values** for the properties.
</Note>

<Tabs>
  <Tab title="Python">
    ```python expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    from typing import Any, Optional, TypedDict, cast

    import requests

    BASE_URL = "https://sdp.suki-stage.com"


    class FormFillingMetadata(TypedDict):
        form_template_id: str


    class FormFillingContext(TypedDict):
        values: list[FormFillingMetadata]


    class FormFillingUpdateContextRequest(TypedDict, total=False):
        form_filling: FormFillingContext


    class FormFillingReturnedContext(TypedDict, total=False):
        form_filling: FormFillingContext


    class FormFillingUpdateContextResponse(TypedDict):
        context: FormFillingReturnedContext


    class ApiHttpError(RuntimeError):
        def __init__(self, status: int, url: str, detail: str) -> None:
            super().__init__(f"HTTP {status} {url}: {detail}")
            self.status = status
            self.url = url


    def _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 token


    def 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>")

            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"},
                        ]
                    }
                },
            )
            form_filling = out["context"].get("form_filling")
            print(form_filling)
        except (ApiHttpError, ValueError) as e:
            print(e)
    ```
  </Tab>

  <Tab title="TypeScript">
    ```typescript expandable theme={"theme":{"light":"github-dark","dark":"material-theme-darker"}}
    const BASE_URL = "https://sdp.suki-stage.com";

    type FormFillingMetadata = { form_template_id: string };
    type FormFillingContext = { values: FormFillingMetadata[] };
    type 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>",
        });

        const out = await updateFormFillingSessionContext(token, "<ambient_session_id>", {
          form_filling: {
            values: [{ form_template_id: "019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0" }],
          },
        });

        console.log(out.context.form_filling);
      } catch (e) {
        console.error(e instanceof Error ? e.message : e);
      }
    }

    void main();
    ```
  </Tab>
</Tabs>


## OpenAPI

````yaml PATCH /api/v1/form-filling/session/{ambient_session_id}/context
openapi: 3.0.1
info:
  title: Suki Developer Platform
  description: >-
    REST and WebSocket APIs for the Suki Developer Platform. Authenticate with
    Login or Register to obtain a Suki access token, then integrate ambient
    clinical documentation, form filling, transcription, and reference metadata
    endpoints.
  contact: {}
  version: '1.0'
servers:
  - url: https://sdp.suki.ai
    description: >-
      Production base URL for Suki Developer Platform REST APIs. WebSocket
      endpoints use the same host with `wss://`.
security:
  - SukiTokenAuth: []
paths:
  /api/v1/form-filling/session/{ambient_session_id}/context:
    patch:
      tags:
        - /api/v1/form-filling/session
      summary: Update form-filling session context
      description: >-
        Partially updates form-filling session context. On success, returns the
        updated `context.form_filling` value.
      parameters:
        - name: ambient_session_id
          in: path
          description: >-
            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.
          required: true
          schema:
            type: string
        - $ref: '#/components/parameters/ProviderIdHeader'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/controllers.FormFillingUpdateContextRequest'
        required: true
      responses:
        '200':
          description: Request succeeded.
          content:
            application/json:
              schema:
                $ref: >-
                  #/components/schemas/controllers.FormFillingUpdateContextResponse
              example:
                context:
                  form_filling:
                    values:
                      - form_template_id: 019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0
        '400':
          description: Bad request. The request body or parameters failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.BadRequestError'
        '401':
          description: Unauthorized. The Suki access token is missing, expired, or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.AuthenticationError'
        '403':
          description: Forbidden. The authenticated user cannot access this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.ForbiddenError'
        '404':
          description: Not found. The session, encounter, or resource ID does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.NotFoundError'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/controllers.InternalServerError'
      security:
        - SukiTokenAuth: []
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |-
            curl --request PATCH \
              --url https://sdp.suki.ai/api/v1/form-filling/session/<ambient_session_id>/context \
              --header 'Content-Type: application/json' \
              --header 'sdp_suki_token: <sdp_suki_token>' \
              --header 'sdp_provider_id: <sdp_provider_id>'
components:
  parameters:
    ProviderIdHeader:
      name: sdp_provider_id
      in: header
      description: >-
        **Optional** - Stable identifier for the active provider. Omit for
        standard partners whose `partner_token` identifies the user.
        **Required** for Bearer partners and Single Auth Token authentication
        where multiple providers share one `partner_token`. Use the same
        `provider_id` you sent on Login or Register.
      required: false
      schema:
        type: string
        example: provider-123
  schemas:
    controllers.FormFillingUpdateContextRequest:
      type: object
      properties:
        form_filling:
          description: '**Optional** - Form template metadata to add or update.'
          allOf:
            - $ref: '#/components/schemas/controllers.FormFillingContext'
      description: >-
        Partial form-filling context update. Include only the fields you want to
        change.
    controllers.FormFillingUpdateContextResponse:
      type: object
      properties:
        context:
          type: object
          description: Updated context for the form-filling session
          allOf:
            - $ref: '#/components/schemas/controllers.FormFillingReturnedContext'
      description: >-
        Response body for the
        /api/v1/form-filling/session/{ambient_session_id}/context PATCH endpoint
      example:
        context:
          form_filling:
            values:
              - form_template_id: 019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0
    controllers.BadRequestError:
      type: object
      properties:
        code:
          type: integer
          example: 400
          description: HTTP status code for the error.
        message:
          type: string
          example: invalid request
          description: Human-readable description of the validation or request error.
      description: Error response when the request fails validation.
    controllers.AuthenticationError:
      type: object
      properties:
        code:
          type: integer
          example: 401
          description: HTTP status code for the error.
        message:
          type: string
          example: invalid token
          description: Human-readable description of the authentication failure.
      description: Error response when authentication fails.
    controllers.ForbiddenError:
      type: object
      properties:
        code:
          type: integer
          example: 403
          description: HTTP status code for the error.
        message:
          type: string
          example: forbidden
          description: Human-readable description of the authorization failure.
      description: Error response when the caller lacks permission.
    controllers.NotFoundError:
      type: object
      properties:
        code:
          type: integer
          example: 404
          description: HTTP status code for the error.
        message:
          type: string
          example: not found
          description: Human-readable description of the missing resource.
      description: Error response when the requested resource was not found.
    controllers.InternalServerError:
      type: object
      properties:
        code:
          type: integer
          example: 500
          description: HTTP status code for the error.
        message:
          type: string
          example: internal server error
          description: Human-readable description of the server error.
      description: Error response when the server encounters an unexpected error.
    controllers.FormFillingContext:
      type: object
      description: Information about form-filling context
      required:
        - values
      properties:
        values:
          description: Array of form template metadata.
          type: array
          items:
            $ref: '#/components/schemas/controllers.FormFillingMetadata'
    controllers.FormFillingReturnedContext:
      description: >-
        Updated session context returned by form-filling context PATCH.
        Form-filling only; not used by ambient session context APIs.
      type: object
      properties:
        form_filling:
          type: object
          description: '**Optional** - Form template metadata for the session'
          allOf:
            - $ref: '#/components/schemas/controllers.FormFillingContext'
    controllers.FormFillingMetadata:
      type: object
      required:
        - form_template_id
      properties:
        form_template_id:
          description: Form template ID (UUID).
          type: string
          example: 019d4cdc-9319-7d81-ae2e-fd6de7f1b4f0
  securitySchemes:
    SukiTokenAuth:
      type: apiKey
      in: header
      name: sdp_suki_token
      description: >-
        Suki access token for the authenticated provider. Obtain this by calling
        Login or Register with a valid `partner_token`. Pass the `suki_token`
        value from the JSON response as the `sdp_suki_token` header on REST
        requests and non-browser WebSocket upgrades. Browser WebSocket clients
        pass the token in `Sec-WebSocket-Protocol` instead. Tokens expire after
        one hour; call Login again to refresh.

````