From c149d753eb898b6a387b2363e7c88647371b7b99 Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Tue, 12 May 2026 07:09:20 +0000
Subject: [PATCH] docs: document ingress client default serde (TypeScript SDK
 v1.14.1)

Generated-By: mintlify-agent
---
 .../invocation/clients/typescript-sdk.mdx     | 15 +++++++++
 .../src/references/ts/api-and-pitfalls.md     |  7 ++++
 snippets/ts/src/develop/clients/ingress.ts    | 33 +++++++++++++++++++
 3 files changed, 55 insertions(+)

diff --git a/docs/services/invocation/clients/typescript-sdk.mdx b/docs/services/invocation/clients/typescript-sdk.mdx
index 075e47be..9b8f6be4 100644
--- a/docs/services/invocation/clients/typescript-sdk.mdx
+++ b/docs/services/invocation/clients/typescript-sdk.mdx
@@ -174,6 +174,21 @@ if (peekOutput.ready) {
 }
 ```
 
+## Custom serialization
+
+By default, the ingress client uses JSON to serialize and deserialize handler payloads.
+If your handlers use a [custom serde](/develop/ts/serialization#custom-serialization), you can configure a default serde for the entire client connection.
+This applies to all handler calls, workflow attach and output polling, awakeable resolution, and attached invocation results.
+
+```typescript {"CODE_LOAD::ts/src/develop/clients/ingress.ts#default_serde"} 
+```
+
+Per-call options (via `clients.rpc.opts(...)` or `clients.rpc.sendOpts(...)`) still override the connection-level default when provided.
+
+<Info>
+  See the [Serialization docs](/develop/ts/serialization) for details on implementing custom `Serde` objects.
+</Info>
+
 ## Advanced: sharing service type definitions
 
 Have a look at the options listed in the [Service Communication docs](/develop/ts/service-communication#advanced%3A-sharing-service-type-definitions). These are also valid for the SDK clients.
diff --git a/restate-plugin/src/references/ts/api-and-pitfalls.md b/restate-plugin/src/references/ts/api-and-pitfalls.md
index b15a508a..22e9a644 100644
--- a/restate-plugin/src/references/ts/api-and-pitfalls.md
+++ b/restate-plugin/src/references/ts/api-and-pitfalls.md
@@ -285,6 +285,13 @@ Use `@restatedev/restate-sdk-clients` to call Restate handlers from outside a Re
 ```ts {"CODE_LOAD::ts/src/develop/skillsmd/clients.ts#here"}
 ```
 
+If your handlers use a custom serde, set a `serde` on the connection options so you don't have to repeat it on every call:
+
+```ts {"CODE_LOAD::ts/src/develop/clients/ingress.ts#default_serde"}
+```
+
+Per-call options (`clients.rpc.opts(...)` / `clients.rpc.sendOpts(...)`) override the connection-level default when provided.
+
 ---
 
 ## TypeScript-Specific Pitfalls
diff --git a/snippets/ts/src/develop/clients/ingress.ts b/snippets/ts/src/develop/clients/ingress.ts
index f2b0ec57..ec57a5b4 100644
--- a/snippets/ts/src/develop/clients/ingress.ts
+++ b/snippets/ts/src/develop/clients/ingress.ts
@@ -124,3 +124,36 @@ const workflowAttach = async () => {
   }
   // <end_workflow_attach>
 };
+
+import * as restate from "@restatedev/restate-sdk";
+
+const defaultSerdeExample = async () => {
+  // <start_default_serde>
+  // import * as clients from "@restatedev/restate-sdk-clients";
+  // import * as restate from "@restatedev/restate-sdk";
+
+  // Set a default serde for all calls on this client connection.
+  // This applies to handler calls, workflow attach/output, awakeable resolution,
+  // and attached invocation results — unless overridden per call.
+  const restateClient = clients.connect({
+    url: "http://localhost:8080",
+    serde: restate.serde.binary,
+  });
+
+  // This call uses the binary serde set above
+  const greet = await restateClient
+    .serviceClient<MyService>({ name: "MyService" })
+    .greet(new Uint8Array([1, 2, 3]));
+
+  // Per-call serde still overrides the default
+  const greet2 = await restateClient
+    .serviceClient<MyService>({ name: "MyService" })
+    .greet(
+      new Uint8Array([1, 2, 3]),
+      clients.rpc.opts({
+        input: restate.serde.binary,
+        output: restate.serde.binary,
+      })
+    );
+  // <end_default_serde>
+};