From f36e79e98241d74d2e95b9604f75fc1080924d85 Mon Sep 17 00:00:00 2001
From: Anurag Bandyopadhyay <angbpy@gmail.com>
Date: Tue, 13 Jan 2026 19:16:51 +0530
Subject: [PATCH 01/16] feat: raw request builder

---
 README.md                                     |  57 +++
 docs/RawApi.md                                | 389 ++++++++++++++++++
 examples/RawApiExample.java                   | 211 ++++++++++
 .../openfga/sdk/api/client/OpenFgaClient.java |  20 +
 .../dev/openfga/sdk/api/client/RawApi.java    | 157 +++++++
 .../sdk/api/client/RawRequestBuilder.java     | 134 ++++++
 .../openfga/sdk/api/client/RawApiTest.java    | 359 ++++++++++++++++
 7 files changed, 1327 insertions(+)
 create mode 100644 docs/RawApi.md
 create mode 100644 examples/RawApiExample.java
 create mode 100644 src/main/java/dev/openfga/sdk/api/client/RawApi.java
 create mode 100644 src/main/java/dev/openfga/sdk/api/client/RawRequestBuilder.java
 create mode 100644 src/test/java/dev/openfga/sdk/api/client/RawApiTest.java

diff --git a/README.md b/README.md
index efbf2df6..7d115a10 100644
--- a/README.md
+++ b/README.md
@@ -46,6 +46,7 @@ This is an autogenerated Java SDK for OpenFGA. It provides a wrapper around the
     - [Assertions](#assertions)
       - [Read Assertions](#read-assertions)
       - [Write Assertions](#write-assertions)
+  - [Raw API](#raw-api)
   - [Retries](#retries)
   - [API Endpoints](#api-endpoints)
   - [Models](#models)
@@ -1167,6 +1168,62 @@ try {
 }
 ```
 
+### Raw API
+
+The Raw API allows execution of HTTP requests to OpenFGA endpoints using the SDK's configured HTTP client. This is useful for accessing API endpoints that do not yet have typed SDK method implementations.
+
+#### Usage
+
+```java
+import dev.openfga.sdk.api.client.OpenFgaClient;
+import dev.openfga.sdk.api.client.RawRequestBuilder;
+import dev.openfga.sdk.api.configuration.ClientConfiguration;
+import java.util.Map;
+
+// Response type
+class CustomResponse {
+    public boolean success;
+    public int count;
+}
+
+// Client configuration
+ClientConfiguration config = new ClientConfiguration()
+    .apiUrl("http://localhost:8080")
+    .storeId("01YCP46JKYM8FJCQ37NMBYHE5X");
+OpenFgaClient client = new OpenFgaClient(config);
+
+// Request execution
+RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/endpoint")
+    .pathParam("store_id", client.getStoreId())
+    .queryParam("param", "value")
+    .body(Map.of("key", "value"));
+
+// Typed response
+client.raw().send(request, CustomResponse.class)
+    .thenAccept(response -> {
+        System.out.println("Status: " + response.getStatusCode());
+        System.out.println("Data: " + response.getData());
+    });
+
+// Raw JSON response
+client.raw().send(request)
+    .thenAccept(response -> {
+        System.out.println("JSON: " + response.getRawResponse());
+    });
+```
+
+#### Features
+
+Requests automatically include:
+- Authentication credentials from configuration
+- Retry logic for 5xx errors with exponential backoff
+- Error handling and exception mapping
+- Configured timeouts and headers
+
+#### Documentation
+
+See [docs/RawApi.md](docs/RawApi.md) for complete API reference and examples.
+
 ### API Endpoints
 
 | Method | HTTP request | Description |
diff --git a/docs/RawApi.md b/docs/RawApi.md
new file mode 100644
index 00000000..bbb1d204
--- /dev/null
+++ b/docs/RawApi.md
@@ -0,0 +1,389 @@
+# Raw API - Alternative Access
+
+## Overview
+
+The Raw API provides an alternative mechanism for calling OpenFGA endpoints that are not yet supported by the typed SDK methods. This is particularly useful for:
+
+- **Experimental Features**: Access newly released or experimental OpenFGA endpoints before they're officially supported in the SDK
+- **Beta Endpoints**: Test beta features without waiting for SDK updates
+- **Custom Extensions**: Call custom or extended OpenFGA endpoints in your deployment
+- **Rapid Prototyping**: Quickly integrate with new API features while SDK support is being developed
+
+## Key Benefits
+
+All requests made through the Raw API automatically benefit from the SDK's infrastructure:
+
+- ✅ **Automatic Authentication** - Bearer token injection handled automatically
+- ✅ **Configuration Adherence** - Respects base URLs, store IDs, and timeouts from your ClientConfiguration
+- ✅ **Automatic Retries** - Built-in retry logic for 5xx errors and network failures
+- ✅ **Consistent Error Handling** - Standard SDK exception handling for 400, 401, 404, 500 errors
+- ✅ **Type Safety** - Option to deserialize responses into typed Java objects or work with raw JSON
+
+## Quick Start
+
+### Basic Usage
+
+```java
+import dev.openfga.sdk.api.client.OpenFgaClient;
+import dev.openfga.sdk.api.client.RawRequestBuilder;
+import dev.openfga.sdk.api.configuration.ClientConfiguration;
+
+// Initialize the client
+ClientConfiguration config = new ClientConfiguration()
+    .apiUrl("http://localhost:8080")
+    .storeId("01YCP46JKYM8FJCQ37NMBYHE5X");
+
+OpenFgaClient fgaClient = new OpenFgaClient(config);
+
+// Example: Use RawRequestBuilder to call the actual /stores/{store_id}/check endpoint
+RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/check")
+    .pathParam("store_id", fgaClient.getStoreId())
+    .body(Map.of(
+        "tuple_key", Map.of(
+            "user", "user:jon",
+            "relation", "can_read",
+            "object", "document:2026"
+        ),
+        "contextual_tuples", List.of()
+    ));
+
+// Get raw JSON response
+fgaClient.raw().send(request)
+    .thenAccept(response -> {
+        System.out.println("Response: " + response.getRawResponse());
+    });
+```
+
+## API Components
+
+### 1. RawRequestBuilder
+
+The `RawRequestBuilder` provides a fluent interface for constructing HTTP requests.
+
+#### Factory Method
+
+```java
+RawRequestBuilder.builder(String method, String path)
+```
+
+- **method**: HTTP method (GET, POST, PUT, DELETE, PATCH, etc.)
+- **path**: API path with optional placeholders like `{store_id}`
+
+#### Methods
+
+##### pathParam(String key, String value)
+Replaces path placeholders with values. Placeholders use curly brace syntax: `{parameter_name}`. Values are automatically URL-encoded.
+
+```java
+.pathParam("store_id", "01YCP46JKYM8FJCQ37NMBYHE5X")
+.pathParam("model_id", "01G5JAVJ41T49E9TT3SKVS7X1J")
+```
+
+##### queryParam(String key, String value)
+Adds query parameters to the URL. Parameters are automatically URL-encoded.
+
+```java
+.queryParam("page", "1")
+.queryParam("limit", "50")
+```
+
+##### header(String key, String value)
+Adds HTTP headers to the request. Standard headers (Authorization, Content-Type, User-Agent) are managed by the SDK.
+
+```java
+.header("X-Request-ID", "unique-id-123")
+.header("X-Custom-Header", "value")
+```
+
+##### body(Object body)
+Sets the request body. Objects and Maps are serialized to JSON. Strings are sent without modification.
+.body(new CustomRequest("data", 123))
+
+// Map
+.body("{\"raw\":\"json\"}")
+```
+// POJO
+### 2. RawApi
+
+// String
+
+#### Accessing RawApi
+
+```java
+OpenFgaClient client = new OpenFgaClient(config);
+RawApi rawApi = client.raw();
+```
+
+#### Methods
+
+##### send(RawRequestBuilder request)
+Execute a request and return the response as a raw JSON string.
+
+```java
+CompletableFuture<ApiResponse<String>> future = rawApi.send(request);
+```
+
+##### send(RawRequestBuilder request, Class<T> responseType)
+Execute a request and deserialize the response into a typed object.
+
+```java
+CompletableFuture<ApiResponse<MyResponse>> future = rawApi.send(request, MyResponse.class);
+```
+
+### 3. ApiResponse<T>
+
+The response object returned by the Raw API.
+
+```java
+public class ApiResponse<T> {
+    int getStatusCode()              // HTTP status code
+    Map<String, List<String>> getHeaders()  // Response headers
+    String getRawResponse()          // Raw JSON response body
+    T getData()                      // Deserialized response data
+}
+```
+
+## Usage Examples
+
+### Example 1: GET Request with Typed Response
+
+```java
+// Define your response type
+public class FeatureResponse {
+    public boolean enabled;
+    public String version;
+}
+
+// Build and execute request
+RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}/experimental-feature")
+    .pathParam("store_id", client.getStoreId());
+
+client.raw().send(request, FeatureResponse.class)
+    .thenAccept(response -> {
+        System.out.println("Status: " + response.getStatusCode());
+        System.out.println("Enabled: " + response.getData().enabled);
+        System.out.println("Version: " + response.getData().version);
+    });
+```
+
+### Example 2: POST Request with Request Body
+
+```java
+// Define request and response types
+public class BulkDeleteRequest {
+    public String olderThan;
+    public String type;
+    public int limit;
+}
+
+public class BulkDeleteResponse {
+    public int deletedCount;
+    public String message;
+}
+
+// Build request with body
+BulkDeleteRequest requestBody = new BulkDeleteRequest();
+requestBody.olderThan = "2023-01-01";
+requestBody.type = "user";
+requestBody.limit = 1000;
+
+RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/bulk-delete")
+    .pathParam("store_id", client.getStoreId())
+    .queryParam("force", "true")
+    .body(requestBody);
+
+// Execute
+client.raw().send(request, BulkDeleteResponse.class)
+    .thenAccept(response -> {
+        System.out.println("Deleted: " + response.getData().deletedCount);
+    });
+```
+
+### Example 3: Working with Raw JSON
+
+```java
+RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}/complex-data")
+    .pathParam("store_id", client.getStoreId());
+
+// Get raw JSON for inspection or custom parsing
+client.raw().send(request)
+    .thenAccept(response -> {
+        String json = response.getRawResponse();
+        System.out.println("Raw JSON: " + json);
+        // Parse manually if needed
+    });
+```
+
+### Example 4: Query Parameters and Pagination
+
+```java
+RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}/items")
+    .pathParam("store_id", client.getStoreId())
+    .queryParam("page", "1")
+    .queryParam("limit", "50")
+    .queryParam("filter", "active")
+    .queryParam("sort", "created_at");
+
+client.raw().send(request, ItemsResponse.class)
+    .thenAccept(response -> {
+        // Process paginated results
+    });
+```
+
+### Example 5: Custom Headers
+
+```java
+RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/action")
+    .pathParam("store_id", client.getStoreId())
+    .header("X-Request-ID", UUID.randomUUID().toString())
+    .header("X-Client-Version", "1.0.0")
+    .header("X-Idempotency-Key", "unique-key-123")
+    .body(actionData);
+
+client.raw().send(request, ActionResponse.class)
+    .thenAccept(response -> {
+        // Handle response
+    });
+```
+
+### Example 6: Error Handling
+
+```java
+RawRequestBuilder request = RawRequestBuilder.builder("DELETE", "/stores/{store_id}/resource/{id}")
+    .pathParam("store_id", client.getStoreId())
+    .pathParam("id", resourceId);
+
+client.raw().send(request)
+    .thenAccept(response -> {
+        System.out.println("Successfully deleted. Status: " + response.getStatusCode());
+    })
+    .exceptionally(e -> {
+        // Standard SDK error handling applies:
+        if (e.getCause() instanceof FgaError) {
+            FgaError error = (FgaError) e.getCause();
+            System.err.println("API Error: " + error.getMessage());
+            System.err.println("Status Code: " + error.getStatusCode());
+        } else {
+            System.err.println("Network Error: " + e.getMessage());
+        }
+        return null;
+    });
+```
+
+### Example 7: Using Map for Request Body
+
+```java
+// Quick prototyping with Map instead of creating a POJO
+RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/configure")
+    .pathParam("store_id", client.getStoreId())
+    .body(Map.of(
+        "setting", "value",
+        "enabled", true,
+        "threshold", 100,
+        "options", List.of("opt1", "opt2")
+    ));
+
+client.raw().send(request, ConfigureResponse.class)
+    .thenAccept(response -> {
+        System.out.println("Configuration updated");
+    });
+```
+
+## Best Practices
+
+### 1. Define Response Types
+
+Define POJOs for response structures:
+
+```java
+public class ApiResponse {
+    @JsonProperty("field_name")
+    public String fieldName;
+    
+    public int count;
+}
+```
+
+### 2. Handle Errors
+
+Include error handling in production code:
+
+```java
+client.raw().send(request, ResponseType.class)
+    .thenAccept(response -> {
+        // Handle success
+    })
+    .exceptionally(e -> {
+        logger.error("Request failed", e);
+        return null;
+    });
+```
+
+### 3. URL Encoding
+
+The SDK automatically URL-encodes parameters. Do not manually encode:
+
+```java
+// Correct
+.pathParam("id", "store with spaces")
+
+// Incorrect - double encoding
+.pathParam("id", URLEncoder.encode("store with spaces", UTF_8))
+```
+
+
+## Migration Path
+
+When the SDK adds official support for an endpoint you're using via Raw API:
+
+### Before (Raw API)
+```java
+RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/check")
+    .pathParam("store_id", client.getStoreId())
+    .body(checkRequest);
+
+client.raw().send(request, CheckResponse.class)
+    .thenAccept(response -> {
+        // Handle response
+    });
+```
+
+### After (Typed SDK Method)
+```java
+client.check(checkRequest)
+    .thenAccept(response -> {
+        // Handle response - same structure!
+    });
+```
+
+The response structure remains the same, making migration straightforward.
+
+## Limitations
+
+1. **No Code Generation**: Unlike typed methods, Raw API requests don't benefit from IDE autocomplete for request/response structures
+2. **Manual Type Definitions**: You need to define your own POJOs for request/response types
+3. **Less Validation**: The SDK can't validate request structure before sending
+4. **Documentation**: You'll need to refer to OpenFGA API documentation for endpoint details
+
+## When to Use Raw API
+
+✅ **Use Raw API when:**
+- The endpoint is experimental or in beta
+- The endpoint was just released and SDK support is pending
+- You need to quickly prototype with new features
+- You have custom OpenFGA extensions
+
+❌ **Use Typed SDK Methods when:**
+- The endpoint has official SDK support
+- You want maximum type safety and validation
+- You prefer IDE autocomplete and compile-time checks
+- The endpoint is stable and well-documented
+
+## Support and Feedback
+
+If you find yourself frequently using the Raw API for a particular endpoint, please:
+1. Open an issue on the SDK repository requesting official support
+2. Share your use case and the endpoint details
+3. Consider contributing a pull request with typed method implementation
+
+The goal of the Raw API is to provide flexibility while we work on comprehensive SDK support for all OpenFGA features.
diff --git a/examples/RawApiExample.java b/examples/RawApiExample.java
new file mode 100644
index 00000000..a92595c1
--- /dev/null
+++ b/examples/RawApiExample.java
@@ -0,0 +1,211 @@
+package dev.openfga.sdk.examples;
+
+import dev.openfga.sdk.api.client.ApiResponse;
+import dev.openfga.sdk.api.client.OpenFgaClient;
+import dev.openfga.sdk.api.client.RawRequestBuilder;
+import dev.openfga.sdk.api.configuration.ClientConfiguration;
+import java.util.Map;
+
+/**
+ * Example demonstrating the Raw API "Escape Hatch" functionality.
+ *
+ * This example shows how to use the Raw API to call experimental or newly-released
+ * OpenFGA endpoints that may not yet be supported in the typed SDK methods.
+ */
+public class RawApiExample {
+
+    /**
+     * Custom response type for demonstration.
+     */
+    public static class BulkDeleteResponse {
+        public int deletedCount;
+        public String message;
+    }
+
+    /**
+     * Custom response type for demonstration.
+     */
+    public static class ExperimentalFeatureResponse {
+        public boolean enabled;
+        public String version;
+        public Map<String, Object> metadata;
+    }
+
+    public static void main(String[] args) throws Exception {
+        // Initialize the OpenFGA client
+        ClientConfiguration config = new ClientConfiguration()
+                .apiUrl("http://localhost:8080")
+                .storeId("01YCP46JKYM8FJCQ37NMBYHE5X");
+
+        OpenFgaClient fgaClient = new OpenFgaClient(config);
+
+        // Example 1: Call a POST endpoint with typed response
+        System.out.println("Example 1: POST request with typed response");
+        postRequestExample(fgaClient);
+
+        // Example 2: GET request with raw JSON response
+        System.out.println("\nExample 2: GET request with raw JSON");
+        rawJsonExample(fgaClient);
+
+        // Example 3: Request with query parameters
+        System.out.println("\nExample 3: Request with query parameters");
+        queryParametersExample(fgaClient);
+
+        // Example 4: Request with custom headers
+        System.out.println("\nExample 4: Request with custom headers");
+        customHeadersExample(fgaClient);
+    }
+
+    /**
+     * Example 1: POST request with request body and typed response.
+    private static void bulkDeleteExample(OpenFgaClient fgaClient) {
+    private static void postRequestExample(OpenFgaClient fgaClient) {
+            // Build the raw request
+            RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/bulk-delete")
+                    .pathParam("store_id", "01YCP46JKYM8FJCQ37NMBYHE5X")
+                    .queryParam("force", "true")
+                    .body(Map.of(
+                            "older_than", "2023-01-01",
+                            "type", "user",
+                            "limit", 1000));
+
+            // Execute with typed response
+            fgaClient
+                    .raw()
+                    .send(request, BulkDeleteResponse.class)
+                    .thenAccept(response -> {
+                        System.out.println("Status: " + response.getStatusCode());
+                        System.out.println("Deleted items: " + response.getData().deletedCount);
+                        System.out.println("Message: " + response.getData().message);
+                    })
+                    .exceptionally(e -> {
+                        System.err.println("Error: " + e.getMessage());
+                        return null;
+                    })
+                    .get(); // Wait for completion (in production, avoid blocking)
+
+        } catch (Exception e) {
+            System.err.println("Failed to execute bulk delete: " + e.getMessage());
+        }
+    }
+
+    /**
+     * Example 2: Get a raw JSON response without typed deserialization.
+     * This is useful when you want to inspect the response or don't have a Java class.
+     * Example 2: Get raw JSON response without deserialization.
+        try {
+            RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}/experimental-feature")
+                    .pathParam("store_id", "01YCP46JKYM8FJCQ37NMBYHE5X");
+
+            // Execute and get raw JSON string
+            fgaClient
+                    .raw()
+                    .send(request) // No class specified = returns String
+                    .thenAccept(response -> {
+                        System.out.println("Status: " + response.getStatusCode());
+                        System.out.println("Raw JSON: " + response.getRawResponse());
+                    })
+                    .exceptionally(e -> {
+                        System.err.println("Error: " + e.getMessage());
+                        return null;
+                    })
+                    .get();
+
+        } catch (Exception e) {
+            System.err.println("Failed to get raw response: " + e.getMessage());
+        }
+    }
+
+    /**
+     * Example 3: Use query parameters to filter or paginate results.
+     */
+    private static void queryParametersExample(OpenFgaClient fgaClient) {
+     * Example 3: Using query parameters for filtering or pagination.
+            RawRequestBuilder request =
+                    RawRequestBuilder.builder("GET", "/stores/{store_id}/experimental-list")
+                            .pathParam("store_id", "01YCP46JKYM8FJCQ37NMBYHE5X")
+                            .queryParam("page", "1")
+                            .queryParam("limit", "50")
+                            .queryParam("filter", "active");
+
+            fgaClient
+                    .raw()
+                    .send(request, ExperimentalFeatureResponse.class)
+                    .thenAccept(response -> {
+                        System.out.println("Status: " + response.getStatusCode());
+                        System.out.println("Feature enabled: " + response.getData().enabled);
+                        System.out.println("Version: " + response.getData().version);
+                    })
+                    .exceptionally(e -> {
+                        System.err.println("Error: " + e.getMessage());
+                        return null;
+                    })
+                    .get();
+
+        } catch (Exception e) {
+            System.err.println("Failed to call endpoint with query params: " + e.getMessage());
+        }
+    }
+
+    /**
+     * Example 4: Add custom headers to the request.
+     */
+    private static void customHeadersExample(OpenFgaClient fgaClient) {
+     * Example 4: Adding custom headers to requests.
+            RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/experimental-action")
+                    .pathParam("store_id", "01YCP46JKYM8FJCQ37NMBYHE5X")
+                    .header("X-Request-ID", "unique-request-123")
+                    .header("X-Client-Version", "1.0.0")
+                    .body(Map.of("action", "test"));
+
+            fgaClient
+                    .raw()
+                    .send(request, ExperimentalFeatureResponse.class)
+                    .thenAccept(response -> {
+                        System.out.println("Status: " + response.getStatusCode());
+                        System.out.println("Response: " + response.getData());
+                    })
+                    .exceptionally(e -> {
+                        System.err.println("Error: " + e.getMessage());
+                        return null;
+                    })
+                    .get();
+
+        } catch (Exception e) {
+            System.err.println("Failed to call endpoint with custom headers: " + e.getMessage());
+        }
+    }
+
+    /**
+     * Bonus Example: Error handling with the Raw API.
+     * The Raw API automatically benefits from the SDK's error handling and retries.
+     */
+     * Error handling example. The Raw API uses standard SDK error handling and retries.
+            RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}/non-existent")
+                    .pathParam("store_id", "01YCP46JKYM8FJCQ37NMBYHE5X");
+
+            fgaClient
+                    .raw()
+                    .send(request)
+                    .thenAccept(response -> {
+                        System.out.println("Success: " + response.getStatusCode());
+                    })
+                    .exceptionally(e -> {
+                        // Standard SDK error handling works here:
+                        // - 401: Unauthorized
+                        // - 404: Not Found
+                        // - 500: Internal Server Error (with automatic retries)
+                        System.err.println("API Error: " + e.getMessage());
+                        if (e.getCause() != null) {
+                            System.err.println("Cause: " + e.getCause().getClass().getName());
+                        }
+                        return null;
+                    })
+                    .get();
+
+        } catch (Exception e) {
+            System.err.println("Failed with error: " + e.getMessage());
+        }
+    }
+}
+
diff --git a/src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java b/src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java
index 8dd17c26..4b070db8 100644
--- a/src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java
+++ b/src/main/java/dev/openfga/sdk/api/client/OpenFgaClient.java
@@ -46,6 +46,26 @@ public OpenFgaApi getApi() {
         return api;
     }
 
+    /**
+     * Returns a RawApi instance for executing HTTP requests to arbitrary OpenFGA endpoints.
+     * Requests automatically include authentication, retry logic, error handling, and configured timeouts/headers.
+     *
+     * <p>Example:</p>
+     * <pre>{@code
+     * RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/endpoint")
+     *     .pathParam("store_id", storeId)
+     *     .body(requestData);
+     *
+     * client.raw().send(request, ResponseType.class)
+     *     .thenAccept(response -> handleResponse(response.getData()));
+     * }</pre>
+     *
+     * @return RawApi instance
+     */
+    public RawApi raw() {
+        return new RawApi(this.apiClient, this.configuration);
+    }
+
     public void setStoreId(String storeId) {
         configuration.storeId(storeId);
     }
diff --git a/src/main/java/dev/openfga/sdk/api/client/RawApi.java b/src/main/java/dev/openfga/sdk/api/client/RawApi.java
new file mode 100644
index 00000000..76b1276b
--- /dev/null
+++ b/src/main/java/dev/openfga/sdk/api/client/RawApi.java
@@ -0,0 +1,157 @@
+package dev.openfga.sdk.api.client;
+
+import dev.openfga.sdk.api.configuration.Configuration;
+import dev.openfga.sdk.errors.ApiException;
+import dev.openfga.sdk.errors.FgaInvalidParameterException;
+import dev.openfga.sdk.util.StringUtil;
+import java.io.IOException;
+import java.net.http.HttpRequest;
+import java.util.Map;
+import java.util.concurrent.CompletableFuture;
+import java.util.stream.Collectors;
+
+/**
+ * Executes HTTP requests to OpenFGA API endpoints using the SDK's internal HTTP client.
+ * Requests automatically include authentication, retry logic, error handling, and configuration settings.
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/endpoint")
+ *     .pathParam("store_id", storeId)
+ *     .body(requestData);
+ *
+ * // Typed response
+ * ApiResponse<ResponseType> response = client.raw().send(request, ResponseType.class).get();
+ *
+ * // Raw JSON
+ * ApiResponse<String> response = client.raw().send(request).get();
+ * }</pre>
+ */
+public class RawApi {
+    private final ApiClient apiClient;
+    private final Configuration configuration;
+
+    /**
+     * Constructs a RawApi instance. Typically called via {@link OpenFgaClient#raw()}.
+     *
+     * @param apiClient API client for HTTP operations
+     * @param configuration Client configuration
+     */
+    public RawApi(ApiClient apiClient, Configuration configuration) {
+        if (apiClient == null) {
+            throw new IllegalArgumentException("ApiClient cannot be null");
+        }
+        if (configuration == null) {
+            throw new IllegalArgumentException("Configuration cannot be null");
+        }
+        this.apiClient = apiClient;
+        this.configuration = configuration;
+    }
+
+    /**
+     * Executes an HTTP request and returns the response body as a JSON string.
+     *
+     * @param requestBuilder Request configuration
+     * @return CompletableFuture with API response containing string data
+     * @throws FgaInvalidParameterException If configuration is invalid
+     * @throws ApiException If request construction fails
+     */
+    public CompletableFuture<ApiResponse<String>> send(RawRequestBuilder requestBuilder)
+            throws FgaInvalidParameterException, ApiException {
+        return send(requestBuilder, String.class);
+    }
+
+    /**
+     * Executes an HTTP request and deserializes the response into a typed object.
+     *
+     * @param <T> Response type
+     * @param requestBuilder Request configuration
+     * @param responseType Class to deserialize response into
+     * @return CompletableFuture with API response containing typed data
+     * @throws FgaInvalidParameterException If configuration is invalid
+     * @throws ApiException If request construction fails
+     */
+    public <T> CompletableFuture<ApiResponse<T>> send(RawRequestBuilder requestBuilder, Class<T> responseType)
+            throws FgaInvalidParameterException, ApiException {
+        if (requestBuilder == null) {
+            throw new IllegalArgumentException("Request builder cannot be null");
+        }
+        if (responseType == null) {
+            throw new IllegalArgumentException("Response type cannot be null");
+        }
+
+        try {
+            configuration.assertValid();
+
+            String completePath = buildCompletePath(requestBuilder);
+            HttpRequest httpRequest = buildHttpRequest(requestBuilder, completePath);
+
+            String methodName = "raw:" + requestBuilder.getMethod() + ":" + requestBuilder.getPath();
+
+            return new HttpRequestAttempt<>(httpRequest, methodName, responseType, apiClient, configuration)
+                    .attemptHttpRequest();
+
+        } catch (IOException e) {
+            return CompletableFuture.failedFuture(new ApiException(e));
+        }
+    }
+
+    private String buildCompletePath(RawRequestBuilder requestBuilder) {
+        String path = requestBuilder.getPath();
+
+        // Replace path parameters
+        for (Map.Entry<String, String> entry : requestBuilder.getPathParams().entrySet()) {
+            String placeholder = "{" + entry.getKey() + "}";
+            String encodedValue = StringUtil.urlEncode(entry.getValue());
+            path = path.replace(placeholder, encodedValue);
+        }
+
+        // Add query parameters
+        Map<String, String> queryParams = requestBuilder.getQueryParams();
+        if (!queryParams.isEmpty()) {
+            String queryString = queryParams.entrySet().stream()
+                    .map(entry -> StringUtil.urlEncode(entry.getKey()) + "=" + StringUtil.urlEncode(entry.getValue()))
+                    .collect(Collectors.joining("&"));
+
+            path = path + (path.contains("?") ? "&" : "?") + queryString;
+        }
+
+        return path;
+    }
+
+    private HttpRequest buildHttpRequest(RawRequestBuilder requestBuilder, String path)
+            throws FgaInvalidParameterException, IOException {
+
+        HttpRequest.Builder httpRequestBuilder;
+
+        // Build request with or without body
+        if (requestBuilder.hasBody()) {
+            Object body = requestBuilder.getBody();
+            byte[] bodyBytes;
+
+            // Handle String body separately
+            if (body instanceof String) {
+                bodyBytes = ((String) body).getBytes();
+            } else {
+                bodyBytes = apiClient.getObjectMapper().writeValueAsBytes(body);
+            }
+
+            httpRequestBuilder = ApiClient.requestBuilder(requestBuilder.getMethod(), path, bodyBytes, configuration);
+        } else {
+            httpRequestBuilder = ApiClient.requestBuilder(requestBuilder.getMethod(), path, configuration);
+        }
+
+        // Add custom headers
+        for (Map.Entry<String, String> entry : requestBuilder.getHeaders().entrySet()) {
+            httpRequestBuilder.header(entry.getKey(), entry.getValue());
+        }
+
+        // Apply request interceptor
+        if (apiClient.getRequestInterceptor() != null) {
+            apiClient.getRequestInterceptor().accept(httpRequestBuilder);
+        }
+
+        return httpRequestBuilder.build();
+    }
+}
+
diff --git a/src/main/java/dev/openfga/sdk/api/client/RawRequestBuilder.java b/src/main/java/dev/openfga/sdk/api/client/RawRequestBuilder.java
new file mode 100644
index 00000000..67669aeb
--- /dev/null
+++ b/src/main/java/dev/openfga/sdk/api/client/RawRequestBuilder.java
@@ -0,0 +1,134 @@
+package dev.openfga.sdk.api.client;
+
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Fluent builder for constructing HTTP requests to OpenFGA API endpoints.
+ * Supports path parameter replacement, query parameters, headers, and request bodies.
+ * Path and query parameters are automatically URL-encoded.
+ *
+ * <p>Example:</p>
+ * <pre>{@code
+ * RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/endpoint")
+ *     .pathParam("store_id", storeId)
+ *     .queryParam("limit", "50")
+ *     .body(requestObject);
+ * }</pre>
+ */
+public class RawRequestBuilder {
+    private final String method;
+    private final String path;
+    private final Map<String, String> pathParams;
+    private final Map<String, String> queryParams;
+    private final Map<String, String> headers;
+    private Object body;
+
+    private RawRequestBuilder(String method, String path) {
+        this.method = method;
+        this.path = path;
+        this.pathParams = new HashMap<>();
+        this.queryParams = new HashMap<>();
+        this.headers = new HashMap<>();
+        this.body = null;
+    }
+
+    /**
+     * Creates a new RawRequestBuilder instance.
+     *
+     * @param method HTTP method (GET, POST, PUT, DELETE, etc.)
+     * @param path API path with optional placeholders like {store_id}
+     * @return New RawRequestBuilder instance
+     */
+    public static RawRequestBuilder builder(String method, String path) {
+        if (method == null || method.trim().isEmpty()) {
+            throw new IllegalArgumentException("HTTP method cannot be null or empty");
+        }
+        if (path == null || path.trim().isEmpty()) {
+            throw new IllegalArgumentException("Path cannot be null or empty");
+        }
+        return new RawRequestBuilder(method.toUpperCase(), path);
+    }
+
+    /**
+     * Adds a path parameter for placeholder replacement. Values are automatically URL-encoded.
+     *
+     * @param key Parameter name (without braces)
+     * @param value Parameter value
+     * @return This builder instance
+     */
+    public RawRequestBuilder pathParam(String key, String value) {
+        if (key != null && value != null) {
+            this.pathParams.put(key, value);
+        }
+        return this;
+    }
+
+    /**
+     * Adds a query parameter. Values are automatically URL-encoded.
+     *
+     * @param key Query parameter name
+     * @param value Query parameter value
+     * @return This builder instance
+     */
+    public RawRequestBuilder queryParam(String key, String value) {
+        if (key != null && value != null) {
+            this.queryParams.put(key, value);
+        }
+        return this;
+    }
+
+    /**
+     * Adds an HTTP header. Standard headers are managed by the SDK.
+     *
+     * @param key Header name
+     * @param value Header value
+     * @return This builder instance
+     */
+    public RawRequestBuilder header(String key, String value) {
+        if (key != null && value != null) {
+            this.headers.put(key, value);
+        }
+        return this;
+    }
+
+    /**
+     * Sets the request body. Objects and Maps are serialized to JSON. Strings are sent as-is.
+     *
+     * @param body Request body
+     * @return This builder instance
+     */
+    public RawRequestBuilder body(Object body) {
+        this.body = body;
+        return this;
+    }
+
+    String getMethod() {
+        return method;
+    }
+
+    String getPath() {
+        return path;
+    }
+
+    Map<String, String> getPathParams() {
+        return new HashMap<>(pathParams);
+    }
+
+    Map<String, String> getQueryParams() {
+        return new HashMap<>(queryParams);
+    }
+
+    Map<String, String> getHeaders() {
+        return new HashMap<>(headers);
+    }
+
+    Object getBody() {
+        return body;
+    }
+
+    boolean hasBody() {
+        return body != null;
+    }
+}
+
diff --git a/src/test/java/dev/openfga/sdk/api/client/RawApiTest.java b/src/test/java/dev/openfga/sdk/api/client/RawApiTest.java
new file mode 100644
index 00000000..ebdc93de
--- /dev/null
+++ b/src/test/java/dev/openfga/sdk/api/client/RawApiTest.java
@@ -0,0 +1,359 @@
+package dev.openfga.sdk.api.client;
+
+import static com.github.tomakehurst.wiremock.client.WireMock.*;
+import static org.junit.jupiter.api.Assertions.*;
+
+import com.fasterxml.jackson.annotation.JsonProperty;
+import com.github.tomakehurst.wiremock.junit5.WireMockRuntimeInfo;
+import com.github.tomakehurst.wiremock.junit5.WireMockTest;
+import dev.openfga.sdk.api.configuration.ClientConfiguration;
+import dev.openfga.sdk.errors.FgaInvalidParameterException;
+import java.util.HashMap;
+import java.util.Map;
+import java.util.concurrent.ExecutionException;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+
+/**
+ * Test suite for Raw API functionality.
+ */
+@WireMockTest
+public class RawApiTest {
+    private static final String DEFAULT_STORE_ID = "01YCP46JKYM8FJCQ37NMBYHE5X";
+    private static final String EXPERIMENTAL_ENDPOINT = "/stores/{store_id}/experimental-feature";
+
+    private String fgaApiUrl;
+
+    /**
+     * Custom response class for testing typed responses.
+     */
+    public static class ExperimentalResponse {
+        @JsonProperty("success")
+        public boolean success;
+
+        @JsonProperty("count")
+        public int count;
+
+        @JsonProperty("message")
+        public String message;
+
+        public ExperimentalResponse() {}
+
+        public ExperimentalResponse(boolean success, int count, String message) {
+            this.success = success;
+            this.count = count;
+            this.message = message;
+        }
+    }
+
+    @BeforeEach
+    public void beforeEach(WireMockRuntimeInfo wmRuntimeInfo) {
+        fgaApiUrl = wmRuntimeInfo.getHttpBaseUrl();
+    }
+
+    private OpenFgaClient createClient() throws FgaInvalidParameterException {
+        ClientConfiguration config = new ClientConfiguration().apiUrl(fgaApiUrl).storeId(DEFAULT_STORE_ID);
+        return new OpenFgaClient(config);
+    }
+
+    @Test
+    public void rawApi_canAccessViaClient() throws Exception {
+        OpenFgaClient client = createClient();
+        assertNotNull(client.raw(), "raw() should return a non-null RawApi instance");
+    }
+
+    @Test
+    public void rawRequestBuilder_canBuildBasicRequest() {
+        RawRequestBuilder builder = RawRequestBuilder.builder("GET", "/stores/{store_id}/test");
+
+        assertNotNull(builder);
+        assertEquals("GET", builder.getMethod());
+        assertEquals("/stores/{store_id}/test", builder.getPath());
+    }
+
+    @Test
+    public void rawRequestBuilder_canAddPathParameters() {
+        RawRequestBuilder builder =
+                RawRequestBuilder.builder("GET", "/stores/{store_id}/test").pathParam("store_id", "my-store");
+
+        Map<String, String> pathParams = builder.getPathParams();
+        assertEquals(1, pathParams.size());
+        assertEquals("my-store", pathParams.get("store_id"));
+    }
+
+    @Test
+    public void rawRequestBuilder_canAddQueryParameters() {
+        RawRequestBuilder builder = RawRequestBuilder.builder("GET", "/test")
+                .queryParam("page", "1")
+                .queryParam("limit", "10");
+
+        Map<String, String> queryParams = builder.getQueryParams();
+        assertEquals(2, queryParams.size());
+        assertEquals("1", queryParams.get("page"));
+        assertEquals("10", queryParams.get("limit"));
+    }
+
+    @Test
+    public void rawRequestBuilder_canAddHeaders() {
+        RawRequestBuilder builder = RawRequestBuilder.builder("GET", "/test").header("X-Custom-Header", "custom-value");
+
+        Map<String, String> headers = builder.getHeaders();
+        assertEquals(1, headers.size());
+        assertEquals("custom-value", headers.get("X-Custom-Header"));
+    }
+
+    @Test
+    public void rawRequestBuilder_canAddBody() {
+        Map<String, Object> body = new HashMap<>();
+        body.put("key", "value");
+
+        RawRequestBuilder builder = RawRequestBuilder.builder("POST", "/test").body(body);
+
+        assertTrue(builder.hasBody());
+        assertEquals(body, builder.getBody());
+    }
+
+    @Test
+    public void rawRequestBuilder_throwsExceptionForNullMethod() {
+        assertThrows(IllegalArgumentException.class, () -> RawRequestBuilder.builder(null, "/test"));
+    }
+
+    @Test
+    public void rawRequestBuilder_throwsExceptionForEmptyMethod() {
+        assertThrows(IllegalArgumentException.class, () -> RawRequestBuilder.builder("", "/test"));
+    }
+
+    @Test
+    public void rawRequestBuilder_throwsExceptionForNullPath() {
+        assertThrows(IllegalArgumentException.class, () -> RawRequestBuilder.builder("GET", null));
+    }
+
+    @Test
+    public void rawRequestBuilder_throwsExceptionForEmptyPath() {
+        assertThrows(IllegalArgumentException.class, () -> RawRequestBuilder.builder("GET", ""));
+    }
+
+    @Test
+    public void rawApi_canSendGetRequestWithTypedResponse() throws Exception {
+        // Setup mock server
+        ExperimentalResponse mockResponse = new ExperimentalResponse(true, 42, "Success");
+        stubFor(get(urlEqualTo("/stores/" + DEFAULT_STORE_ID + "/experimental-feature"))
+                .willReturn(aResponse()
+                        .withStatus(200)
+                        .withHeader("Content-Type", "application/json")
+                        .withBody("{\"success\":true,\"count\":42,\"message\":\"Success\"}")));
+
+        // Build and send request
+        OpenFgaClient client = createClient();
+        RawRequestBuilder request =
+                RawRequestBuilder.builder("GET", EXPERIMENTAL_ENDPOINT).pathParam("store_id", DEFAULT_STORE_ID);
+
+        ApiResponse<ExperimentalResponse> response =
+                client.raw().send(request, ExperimentalResponse.class).get();
+
+        // Verify response
+        assertNotNull(response);
+        assertEquals(200, response.getStatusCode());
+        assertNotNull(response.getData());
+        assertTrue(response.getData().success);
+        assertEquals(42, response.getData().count);
+        assertEquals("Success", response.getData().message);
+
+        // Verify the request was made correctly
+        verify(getRequestedFor(urlEqualTo("/stores/" + DEFAULT_STORE_ID + "/experimental-feature"))
+                .withHeader("Accept", equalTo("application/json")));
+    }
+
+    @Test
+    public void rawApi_canSendPostRequestWithBody() throws Exception {
+        // Setup mock server
+        stubFor(post(urlEqualTo("/stores/" + DEFAULT_STORE_ID + "/experimental-feature"))
+                .willReturn(aResponse()
+                        .withStatus(200)
+                        .withHeader("Content-Type", "application/json")
+                        .withBody("{\"success\":true,\"count\":1,\"message\":\"Created\"}")));
+
+        // Build and send request
+        OpenFgaClient client = createClient();
+        Map<String, Object> requestBody = new HashMap<>();
+        requestBody.put("name", "test");
+        requestBody.put("value", 123);
+
+        RawRequestBuilder request = RawRequestBuilder.builder("POST", EXPERIMENTAL_ENDPOINT)
+                .pathParam("store_id", DEFAULT_STORE_ID)
+                .body(requestBody);
+
+        ApiResponse<ExperimentalResponse> response =
+                client.raw().send(request, ExperimentalResponse.class).get();
+
+        // Verify response
+        assertNotNull(response);
+        assertEquals(200, response.getStatusCode());
+        assertTrue(response.getData().success);
+
+        // Verify the request was made with the correct body
+        verify(postRequestedFor(urlEqualTo("/stores/" + DEFAULT_STORE_ID + "/experimental-feature"))
+                .withHeader("Content-Type", equalTo("application/json"))
+                .withRequestBody(matchingJsonPath("$.name", equalTo("test")))
+                .withRequestBody(matchingJsonPath("$.value", equalTo("123"))));
+    }
+
+    @Test
+    public void rawApi_canSendRequestWithQueryParameters() throws Exception {
+        // Setup mock server
+        stubFor(get(urlEqualTo("/stores/" + DEFAULT_STORE_ID + "/experimental-feature?force=true&limit=10"))
+                .willReturn(aResponse()
+                        .withStatus(200)
+                        .withHeader("Content-Type", "application/json")
+                        .withBody("{\"success\":true,\"count\":10,\"message\":\"Success\"}")));
+
+        // Build and send request
+        OpenFgaClient client = createClient();
+        RawRequestBuilder request = RawRequestBuilder.builder("GET", EXPERIMENTAL_ENDPOINT)
+                .pathParam("store_id", DEFAULT_STORE_ID)
+                .queryParam("force", "true")
+                .queryParam("limit", "10");
+
+        ApiResponse<ExperimentalResponse> response =
+                client.raw().send(request, ExperimentalResponse.class).get();
+
+        // Verify response
+        assertNotNull(response);
+        assertEquals(200, response.getStatusCode());
+
+        // Verify the request was made with query parameters
+        verify(getRequestedFor(urlPathEqualTo("/stores/" + DEFAULT_STORE_ID + "/experimental-feature"))
+                .withQueryParam("force", equalTo("true"))
+                .withQueryParam("limit", equalTo("10")));
+    }
+
+    @Test
+    public void rawApi_canReturnRawJsonString() throws Exception {
+        // Setup mock server
+        String jsonResponse = "{\"custom\":\"response\",\"nested\":{\"value\":42}}";
+        stubFor(get(urlEqualTo("/stores/" + DEFAULT_STORE_ID + "/experimental-feature"))
+                .willReturn(aResponse()
+                        .withStatus(200)
+                        .withHeader("Content-Type", "application/json")
+                        .withBody(jsonResponse)));
+
+        // Build and send request
+        OpenFgaClient client = createClient();
+        RawRequestBuilder request =
+                RawRequestBuilder.builder("GET", EXPERIMENTAL_ENDPOINT).pathParam("store_id", DEFAULT_STORE_ID);
+
+        ApiResponse<String> response = client.raw().send(request).get();
+
+        // Verify response
+        assertNotNull(response);
+        assertEquals(200, response.getStatusCode());
+        assertEquals(jsonResponse, response.getData());
+        assertEquals(jsonResponse, response.getRawResponse());
+    }
+
+    @Test
+    public void rawApi_handlesHttpErrors() throws Exception {
+        // Setup mock server to return 404
+        stubFor(get(urlEqualTo("/stores/" + DEFAULT_STORE_ID + "/non-existent"))
+                .willReturn(aResponse().withStatus(404).withBody("{\"error\":\"Not found\"}")));
+
+        // Build and send request
+        OpenFgaClient client = createClient();
+        RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}/non-existent")
+                .pathParam("store_id", DEFAULT_STORE_ID);
+
+        // Verify exception is thrown
+        ExecutionException exception = assertThrows(
+                ExecutionException.class, () -> client.raw().send(request).get());
+
+        assertTrue(exception.getCause() instanceof FgaError);
+    }
+
+    @Test
+    public void rawApi_handlesServerErrors() throws Exception {
+        // Setup mock server to return 500
+        stubFor(get(urlEqualTo("/stores/" + DEFAULT_STORE_ID + "/experimental-feature"))
+                .willReturn(aResponse().withStatus(500).withBody("{\"error\":\"Internal server error\"}")));
+
+        // Build and send request
+        OpenFgaClient client = createClient();
+        RawRequestBuilder request =
+                RawRequestBuilder.builder("GET", EXPERIMENTAL_ENDPOINT).pathParam("store_id", DEFAULT_STORE_ID);
+
+        // Verify exception is thrown
+        ExecutionException exception = assertThrows(
+                ExecutionException.class, () -> client.raw().send(request).get());
+
+        assertTrue(exception.getCause() instanceof FgaError);
+    }
+
+    @Test
+    public void rawApi_supportsCustomHeaders() throws Exception {
+        // Setup mock server
+        stubFor(get(urlEqualTo("/stores/" + DEFAULT_STORE_ID + "/experimental-feature"))
+                .willReturn(aResponse()
+                        .withStatus(200)
+                        .withHeader("Content-Type", "application/json")
+                        .withBody("{\"success\":true,\"count\":0,\"message\":\"OK\"}")));
+
+        // Build and send request with custom header
+        OpenFgaClient client = createClient();
+        RawRequestBuilder request = RawRequestBuilder.builder("GET", EXPERIMENTAL_ENDPOINT)
+                .pathParam("store_id", DEFAULT_STORE_ID)
+                .header("X-Custom-Header", "custom-value")
+                .header("X-Request-ID", "12345");
+
+        ApiResponse<ExperimentalResponse> response =
+                client.raw().send(request, ExperimentalResponse.class).get();
+
+        // Verify response
+        assertNotNull(response);
+        assertEquals(200, response.getStatusCode());
+
+        // Verify custom headers were sent
+        verify(getRequestedFor(urlEqualTo("/stores/" + DEFAULT_STORE_ID + "/experimental-feature"))
+                .withHeader("X-Custom-Header", equalTo("custom-value"))
+                .withHeader("X-Request-ID", equalTo("12345")));
+    }
+
+    @Test
+    public void rawApi_encodesPathParameters() throws Exception {
+        // Setup mock server with encoded path
+        String encodedId = "store%20with%20spaces";
+        stubFor(get(urlEqualTo("/stores/" + encodedId + "/experimental-feature"))
+                .willReturn(aResponse()
+                        .withStatus(200)
+                        .withHeader("Content-Type", "application/json")
+                        .withBody("{\"success\":true,\"count\":0,\"message\":\"OK\"}")));
+
+        // Build and send request with special characters
+        ClientConfiguration config = new ClientConfiguration().apiUrl(fgaApiUrl).storeId("store with spaces");
+        OpenFgaClient client = new OpenFgaClient(config);
+
+        RawRequestBuilder request =
+                RawRequestBuilder.builder("GET", EXPERIMENTAL_ENDPOINT).pathParam("store_id", "store with spaces");
+
+        ApiResponse<ExperimentalResponse> response =
+                client.raw().send(request, ExperimentalResponse.class).get();
+
+        // Verify response
+        assertNotNull(response);
+        assertEquals(200, response.getStatusCode());
+
+        // Verify the path was encoded
+        verify(getRequestedFor(urlEqualTo("/stores/" + encodedId + "/experimental-feature")));
+    }
+
+    @Test
+    public void rawApi_throwsExceptionForNullBuilder() throws Exception {
+        OpenFgaClient client = createClient();
+        assertThrows(IllegalArgumentException.class, () -> client.raw().send(null));
+    }
+
+    @Test
+    public void rawApi_throwsExceptionForNullResponseType() throws Exception {
+        OpenFgaClient client = createClient();
+        RawRequestBuilder request = RawRequestBuilder.builder("GET", "/test");
+        assertThrows(IllegalArgumentException.class, () -> client.raw().send(request, null));
+    }
+}

From a2058227c051e33c650ec9b7db8bedbfd1f24512 Mon Sep 17 00:00:00 2001
From: Anurag Bandyopadhyay <angbpy@gmail.com>
Date: Tue, 13 Jan 2026 20:04:28 +0530
Subject: [PATCH 02/16] fix: fmt

---
 src/main/java/dev/openfga/sdk/api/client/RawApi.java            | 1 -
 src/main/java/dev/openfga/sdk/api/client/RawRequestBuilder.java | 1 -
 2 files changed, 2 deletions(-)

diff --git a/src/main/java/dev/openfga/sdk/api/client/RawApi.java b/src/main/java/dev/openfga/sdk/api/client/RawApi.java
index 76b1276b..fc5231b6 100644
--- a/src/main/java/dev/openfga/sdk/api/client/RawApi.java
+++ b/src/main/java/dev/openfga/sdk/api/client/RawApi.java
@@ -154,4 +154,3 @@ private HttpRequest buildHttpRequest(RawRequestBuilder requestBuilder, String pa
         return httpRequestBuilder.build();
     }
 }
-
diff --git a/src/main/java/dev/openfga/sdk/api/client/RawRequestBuilder.java b/src/main/java/dev/openfga/sdk/api/client/RawRequestBuilder.java
index 67669aeb..4eb40aee 100644
--- a/src/main/java/dev/openfga/sdk/api/client/RawRequestBuilder.java
+++ b/src/main/java/dev/openfga/sdk/api/client/RawRequestBuilder.java
@@ -131,4 +131,3 @@ boolean hasBody() {
         return body != null;
     }
 }
-

From ef8f6541247c5970a921493c8f1c61b7292e79c0 Mon Sep 17 00:00:00 2001
From: Anurag Bandyopadhyay <angbpy@gmail.com>
Date: Tue, 13 Jan 2026 22:35:26 +0530
Subject: [PATCH 03/16] feat: raw requests integration tests

---
 examples/RawApiSimpleExample.java             | 115 +++++
 .../sdk/api/client/HttpRequestAttempt.java    |   7 +
 .../dev/openfga/sdk/api/client/RawApi.java    |  27 +-
 .../sdk/api/client/RawApiIntegrationTest.java | 458 ++++++++++++++++++
 .../openfga/sdk/api/client/RawApiTest.java    |   1 +
 5 files changed, 598 insertions(+), 10 deletions(-)
 create mode 100644 examples/RawApiSimpleExample.java
 create mode 100644 src/test-integration/java/dev/openfga/sdk/api/client/RawApiIntegrationTest.java

diff --git a/examples/RawApiSimpleExample.java b/examples/RawApiSimpleExample.java
new file mode 100644
index 00000000..17fd1728
--- /dev/null
+++ b/examples/RawApiSimpleExample.java
@@ -0,0 +1,115 @@
+package dev.openfga.sdk.examples;
+
+import dev.openfga.sdk.api.client.*;
+import dev.openfga.sdk.api.configuration.ClientConfiguration;
+import dev.openfga.sdk.api.model.*;
+import java.util.HashMap;
+import java.util.Map;
+
+/**
+ * Simple example demonstrating Raw API usage.
+ *
+ * Run this with your local OpenFGA instance:
+ * docker run --rm -p 8080:8080 -p 3000:3000 openfga/openfga run
+ *
+ * Then compile and run this example.
+ */
+public class RawApiSimpleExample {
+
+    public static void main(String[] args) {
+        try {
+            // Initialize client
+            ClientConfiguration config = new ClientConfiguration()
+                .apiUrl("http://localhost:8080");
+
+            OpenFgaClient client = new OpenFgaClient(config);
+
+            System.out.println("=== Raw API Simple Example ===\n");
+
+            // Example 1: List stores (raw JSON)
+            System.out.println("1. Listing stores (raw JSON):");
+            RawRequestBuilder listRequest = RawRequestBuilder.builder("GET", "/stores");
+            ApiResponse<String> listResponse = client.raw().send(listRequest).get();
+            System.out.println("   Status: " + listResponse.getStatusCode());
+            System.out.println("   Raw JSON: " + listResponse.getData());
+            System.out.println();
+
+            // Example 2: Create a store (typed response)
+            System.out.println("2. Creating a store (typed response):");
+            Map<String, Object> createBody = new HashMap<>();
+            createBody.put("name", "raw-api-demo-store");
+
+            RawRequestBuilder createRequest = RawRequestBuilder.builder("POST", "/stores")
+                .body(createBody);
+
+            ApiResponse<CreateStoreResponse> createResponse =
+                client.raw().send(createRequest, CreateStoreResponse.class).get();
+
+            String storeId = createResponse.getData().getId();
+            String storeName = createResponse.getData().getName();
+
+            System.out.println("   Status: " + createResponse.getStatusCode());
+            System.out.println("   Store ID: " + storeId);
+            System.out.println("   Store Name: " + storeName);
+            System.out.println();
+
+            // Example 3: Get store with path parameter
+            System.out.println("3. Getting store by ID:");
+            RawRequestBuilder getRequest = RawRequestBuilder.builder("GET", "/stores/{store_id}")
+                .pathParam("store_id", storeId);
+
+            ApiResponse<GetStoreResponse> getResponse =
+                client.raw().send(getRequest, GetStoreResponse.class).get();
+
+            System.out.println("   Status: " + getResponse.getStatusCode());
+            System.out.println("   Retrieved store: " + getResponse.getData().getName());
+            System.out.println();
+
+            // Example 4: Automatic store_id replacement
+            System.out.println("4. Using automatic {store_id} replacement:");
+            client.setStoreId(storeId);
+
+            // No need to call .pathParam("store_id", ...)
+            RawRequestBuilder autoRequest = RawRequestBuilder.builder("GET", "/stores/{store_id}");
+            ApiResponse<GetStoreResponse> autoResponse =
+                client.raw().send(autoRequest, GetStoreResponse.class).get();
+
+            System.out.println("   Status: " + autoResponse.getStatusCode());
+            System.out.println("   Store auto-fetched: " + autoResponse.getData().getName());
+            System.out.println();
+
+            // Example 5: Query parameters
+            System.out.println("5. List stores with pagination:");
+            RawRequestBuilder paginatedRequest = RawRequestBuilder.builder("GET", "/stores")
+                .queryParam("page_size", "5");
+
+            ApiResponse<ListStoresResponse> paginatedResponse =
+                client.raw().send(paginatedRequest, ListStoresResponse.class).get();
+
+            System.out.println("   Status: " + paginatedResponse.getStatusCode());
+            System.out.println("   Stores returned: " + paginatedResponse.getData().getStores().size());
+            System.out.println();
+
+            // Example 6: Custom headers
+            System.out.println("6. Request with custom headers:");
+            RawRequestBuilder headerRequest = RawRequestBuilder.builder("GET", "/stores/{store_id}")
+                .pathParam("store_id", storeId)
+                .header("X-Custom-Header", "my-value")
+                .header("X-Request-ID", "demo-123");
+
+            ApiResponse<GetStoreResponse> headerResponse =
+                client.raw().send(headerRequest, GetStoreResponse.class).get();
+
+            System.out.println("   Status: " + headerResponse.getStatusCode());
+            System.out.println("   Custom headers sent successfully");
+            System.out.println();
+
+            System.out.println("=== All examples completed successfully! ===");
+
+        } catch (Exception e) {
+            System.err.println("Error: " + e.getMessage());
+            e.printStackTrace();
+        }
+    }
+}
+
diff --git a/src/main/java/dev/openfga/sdk/api/client/HttpRequestAttempt.java b/src/main/java/dev/openfga/sdk/api/client/HttpRequestAttempt.java
index 4cf6f6a2..1a2d657f 100644
--- a/src/main/java/dev/openfga/sdk/api/client/HttpRequestAttempt.java
+++ b/src/main/java/dev/openfga/sdk/api/client/HttpRequestAttempt.java
@@ -216,6 +216,13 @@ private CompletableFuture<T> deserializeResponse(HttpResponse<String> response)
             return CompletableFuture.completedFuture(null);
         }
 
+        // Return raw response body as-is for String.class
+        if (clazz == String.class) {
+            @SuppressWarnings("unchecked")
+            T raw = (T) response.body();
+            return CompletableFuture.completedFuture(raw);
+        }
+
         try {
             T deserialized = apiClient.getObjectMapper().readValue(response.body(), clazz);
             return CompletableFuture.completedFuture(deserialized);
diff --git a/src/main/java/dev/openfga/sdk/api/client/RawApi.java b/src/main/java/dev/openfga/sdk/api/client/RawApi.java
index fc5231b6..0eaa05d6 100644
--- a/src/main/java/dev/openfga/sdk/api/client/RawApi.java
+++ b/src/main/java/dev/openfga/sdk/api/client/RawApi.java
@@ -3,12 +3,10 @@
 import dev.openfga.sdk.api.configuration.Configuration;
 import dev.openfga.sdk.errors.ApiException;
 import dev.openfga.sdk.errors.FgaInvalidParameterException;
-import dev.openfga.sdk.util.StringUtil;
 import java.io.IOException;
 import java.net.http.HttpRequest;
 import java.util.Map;
 import java.util.concurrent.CompletableFuture;
-import java.util.stream.Collectors;
 
 /**
  * Executes HTTP requests to OpenFGA API endpoints using the SDK's internal HTTP client.
@@ -98,21 +96,30 @@ public <T> CompletableFuture<ApiResponse<T>> send(RawRequestBuilder requestBuild
 
     private String buildCompletePath(RawRequestBuilder requestBuilder) {
         String path = requestBuilder.getPath();
-
+        Map<String, String> pathParams = requestBuilder.getPathParams();
+        // Automatic {store_id} replacement if not provided
+        if (path.contains("{store_id}") && !pathParams.containsKey("store_id")) {
+            if (configuration instanceof dev.openfga.sdk.api.configuration.ClientConfiguration) {
+                String storeId = ((dev.openfga.sdk.api.configuration.ClientConfiguration) configuration).getStoreId();
+                if (storeId != null) {
+                    path = path.replace("{store_id}", dev.openfga.sdk.util.StringUtil.urlEncode(storeId));
+                }
+            }
+        }
         // Replace path parameters
-        for (Map.Entry<String, String> entry : requestBuilder.getPathParams().entrySet()) {
+        for (Map.Entry<String, String> entry : pathParams.entrySet()) {
             String placeholder = "{" + entry.getKey() + "}";
-            String encodedValue = StringUtil.urlEncode(entry.getValue());
+            String encodedValue = dev.openfga.sdk.util.StringUtil.urlEncode(entry.getValue());
             path = path.replace(placeholder, encodedValue);
         }
-
-        // Add query parameters
+        // Add query parameters (sorted for deterministic order)
         Map<String, String> queryParams = requestBuilder.getQueryParams();
         if (!queryParams.isEmpty()) {
             String queryString = queryParams.entrySet().stream()
-                    .map(entry -> StringUtil.urlEncode(entry.getKey()) + "=" + StringUtil.urlEncode(entry.getValue()))
-                    .collect(Collectors.joining("&"));
-
+                    .sorted(Map.Entry.comparingByKey())
+                    .map(entry -> dev.openfga.sdk.util.StringUtil.urlEncode(entry.getKey()) + "="
+                            + dev.openfga.sdk.util.StringUtil.urlEncode(entry.getValue()))
+                    .collect(java.util.stream.Collectors.joining("&"));
             path = path + (path.contains("?") ? "&" : "?") + queryString;
         }
 
diff --git a/src/test-integration/java/dev/openfga/sdk/api/client/RawApiIntegrationTest.java b/src/test-integration/java/dev/openfga/sdk/api/client/RawApiIntegrationTest.java
new file mode 100644
index 00000000..868a6d79
--- /dev/null
+++ b/src/test-integration/java/dev/openfga/sdk/api/client/RawApiIntegrationTest.java
@@ -0,0 +1,458 @@
+package dev.openfga.sdk.api.client;
+
+import static org.junit.jupiter.api.Assertions.*;
+
+import com.fasterxml.jackson.databind.ObjectMapper;
+import dev.openfga.sdk.api.configuration.ClientConfiguration;
+import dev.openfga.sdk.api.model.*;
+import java.util.HashMap;
+import java.util.List;
+import java.util.Map;
+import org.junit.jupiter.api.BeforeEach;
+import org.junit.jupiter.api.Test;
+import org.junit.jupiter.api.TestInstance;
+import org.junit.jupiter.api.TestInstance.Lifecycle;
+import org.testcontainers.junit.jupiter.Container;
+import org.testcontainers.junit.jupiter.Testcontainers;
+import org.testcontainers.openfga.OpenFGAContainer;
+
+/**
+ * Integration tests for Raw API functionality.
+ * These tests demonstrate how to use raw requests to call OpenFGA endpoints
+ * without using the SDK's typed methods.
+ */
+@TestInstance(Lifecycle.PER_CLASS)
+@Testcontainers
+public class RawApiIntegrationTest {
+
+    @Container
+    private static final OpenFGAContainer openfga = new OpenFGAContainer("openfga/openfga:v1.10.2");
+
+    private static final ObjectMapper mapper = new ObjectMapper().findAndRegisterModules();
+
+    private OpenFgaClient fga;
+
+    @BeforeEach
+    public void initializeApi() throws Exception {
+        System.setProperty("HttpRequestAttempt.debug-logging", "enable");
+
+        ClientConfiguration apiConfig = new ClientConfiguration().apiUrl(openfga.getHttpEndpoint());
+        fga = new OpenFgaClient(apiConfig);
+    }
+
+    /**
+     * Test listing stores using raw API instead of fga.listStores().
+     */
+    @Test
+    public void rawRequest_listStores() throws Exception {
+        // Create a store first so we have something to list
+        String storeName = "test-store-" + System.currentTimeMillis();
+        createStoreUsingRawRequest(storeName);
+
+        // Use raw API to list stores (equivalent to GET /stores)
+        RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores");
+
+        ApiResponse<ListStoresResponse> response =
+                fga.raw().send(request, ListStoresResponse.class).get();
+
+        // Verify response
+        assertNotNull(response);
+        assertEquals(200, response.getStatusCode());
+        assertNotNull(response.getData());
+        assertNotNull(response.getData().getStores());
+        assertTrue(response.getData().getStores().size() > 0);
+
+        // Verify we can find our store
+        boolean foundStore =
+                response.getData().getStores().stream().anyMatch(store -> storeName.equals(store.getName()));
+        assertTrue(foundStore, "Should find the store we created");
+
+        System.out.println("✓ Successfully listed stores using raw request");
+        System.out.println("  Found " + response.getData().getStores().size() + " stores");
+    }
+
+    /**
+     * Test creating a store using raw API with typed response.
+     */
+    @Test
+    public void rawRequest_createStore_typedResponse() throws Exception {
+        String storeName = "raw-test-store-" + System.currentTimeMillis();
+
+        // Build request body
+        Map<String, Object> requestBody = new HashMap<>();
+        requestBody.put("name", storeName);
+
+        // Use raw API to create store (equivalent to POST /stores)
+        RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores").body(requestBody);
+
+        ApiResponse<CreateStoreResponse> response =
+                fga.raw().send(request, CreateStoreResponse.class).get();
+
+        // Verify response
+        assertNotNull(response);
+        assertEquals(201, response.getStatusCode());
+        assertNotNull(response.getData());
+        assertNotNull(response.getData().getId());
+        assertEquals(storeName, response.getData().getName());
+
+        System.out.println("✓ Successfully created store using raw request");
+        System.out.println("  Store ID: " + response.getData().getId());
+        System.out.println("  Store Name: " + response.getData().getName());
+    }
+
+    /**
+     * Test creating a store using raw API with raw JSON string response.
+     */
+    @Test
+    public void rawRequest_createStore_rawJsonResponse() throws Exception {
+        String storeName = "raw-json-test-" + System.currentTimeMillis();
+
+        // Build request body
+        Map<String, Object> requestBody = new HashMap<>();
+        requestBody.put("name", storeName);
+
+        // Use raw API to create store and get raw JSON response
+        RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores").body(requestBody);
+
+        ApiResponse<String> response = fga.raw().send(request).get();
+
+        // Verify response
+        assertNotNull(response);
+        assertEquals(201, response.getStatusCode());
+        assertNotNull(response.getData());
+        assertNotNull(response.getRawResponse());
+
+        // Parse the JSON manually
+        String rawJson = response.getData();
+        assertTrue(rawJson.contains("\"id\""));
+        assertTrue(rawJson.contains("\"name\""));
+        assertTrue(rawJson.contains(storeName));
+
+        System.out.println("✓ Successfully created store with raw JSON response");
+        System.out.println("  Raw JSON: " + rawJson);
+    }
+
+    /**
+     * Test getting a specific store using raw API with path parameters.
+     */
+    @Test
+    public void rawRequest_getStore_withPathParams() throws Exception {
+        // Create a store first
+        String storeName = "get-test-store-" + System.currentTimeMillis();
+        String storeId = createStoreUsingRawRequest(storeName);
+
+        // Use raw API to get store details (equivalent to GET /stores/{store_id})
+        RawRequestBuilder request =
+                RawRequestBuilder.builder("GET", "/stores/{store_id}").pathParam("store_id", storeId);
+
+        ApiResponse<GetStoreResponse> response =
+                fga.raw().send(request, GetStoreResponse.class).get();
+
+        // Verify response
+        assertNotNull(response);
+        assertEquals(200, response.getStatusCode());
+        assertNotNull(response.getData());
+        assertEquals(storeId, response.getData().getId());
+        assertEquals(storeName, response.getData().getName());
+
+        System.out.println("✓ Successfully retrieved store using raw request with path params");
+        System.out.println("  Store ID: " + response.getData().getId());
+    }
+
+    /**
+     * Test automatic {store_id} replacement when store ID is configured.
+     */
+    @Test
+    public void rawRequest_automaticStoreIdReplacement() throws Exception {
+        // Create a store and configure it
+        String storeName = "auto-store-" + System.currentTimeMillis();
+        String storeId = createStoreUsingRawRequest(storeName);
+        fga.setStoreId(storeId);
+
+        // Use raw API WITHOUT providing store_id path param - it should be auto-replaced
+        RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}");
+
+        ApiResponse<GetStoreResponse> response =
+                fga.raw().send(request, GetStoreResponse.class).get();
+
+        // Verify response
+        assertNotNull(response);
+        assertEquals(200, response.getStatusCode());
+        assertEquals(storeId, response.getData().getId());
+
+        System.out.println("✓ Successfully used automatic {store_id} replacement");
+        System.out.println("  Configured store ID was automatically used");
+    }
+
+    /**
+     * Test writing authorization model using raw API.
+     */
+    @Test
+    public void rawRequest_writeAuthorizationModel() throws Exception {
+        // Create a store first
+        String storeName = "auth-model-test-" + System.currentTimeMillis();
+        String storeId = createStoreUsingRawRequest(storeName);
+        fga.setStoreId(storeId);
+
+        // Build authorization model with proper metadata
+        Map<String, Object> requestBody = new HashMap<>();
+        requestBody.put("schema_version", "1.1");
+
+        // Create metadata for reader relation
+        Map<String, Object> readerMetadata = new HashMap<>();
+        readerMetadata.put("directly_related_user_types", List.of(Map.of("type", "user")));
+
+        Map<String, Object> relationMetadata = new HashMap<>();
+        relationMetadata.put("reader", readerMetadata);
+
+        Map<String, Object> metadata = new HashMap<>();
+        metadata.put("relations", relationMetadata);
+
+        Map<String, Object> readerRelation = new HashMap<>();
+        readerRelation.put("this", new HashMap<>());
+        Map<String, Object> relations = new HashMap<>();
+        relations.put("reader", readerRelation);
+
+        List<Map<String, Object>> typeDefinitions = List.of(
+                Map.of("type", "user", "relations", new HashMap<>()),
+                Map.of("type", "document", "relations", relations, "metadata", metadata));
+
+        requestBody.put("type_definitions", typeDefinitions);
+
+        // Use raw API to write authorization model
+        RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/authorization-models")
+                .body(requestBody);
+
+        ApiResponse<WriteAuthorizationModelResponse> response =
+                fga.raw().send(request, WriteAuthorizationModelResponse.class).get();
+
+        // Verify response
+        assertNotNull(response);
+        assertEquals(201, response.getStatusCode());
+        assertNotNull(response.getData());
+        assertNotNull(response.getData().getAuthorizationModelId());
+
+        System.out.println("✓ Successfully wrote authorization model using raw request");
+        System.out.println("  Model ID: " + response.getData().getAuthorizationModelId());
+    }
+
+    /**
+     * Test reading authorization models with query parameters.
+     */
+    @Test
+    public void rawRequest_readAuthorizationModels_withQueryParams() throws Exception {
+        // Create a store and write a model
+        String storeName = "read-models-test-" + System.currentTimeMillis();
+        String storeId = createStoreUsingRawRequest(storeName);
+        fga.setStoreId(storeId);
+
+        // Create an authorization model first
+        writeSimpleAuthorizationModel(storeId);
+
+        // Use raw API to read authorization models with query parameters
+        RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}/authorization-models")
+                .queryParam("page_size", "10")
+                .queryParam("continuation_token", "");
+
+        ApiResponse<ReadAuthorizationModelsResponse> response =
+                fga.raw().send(request, ReadAuthorizationModelsResponse.class).get();
+
+        // Verify response
+        assertNotNull(response);
+        assertEquals(200, response.getStatusCode());
+        assertNotNull(response.getData());
+        assertNotNull(response.getData().getAuthorizationModels());
+        assertTrue(response.getData().getAuthorizationModels().size() > 0);
+
+        System.out.println("✓ Successfully read authorization models with query params");
+        System.out.println(
+                "  Found " + response.getData().getAuthorizationModels().size() + " models");
+    }
+
+    /**
+     * Test Check API using raw request.
+     * Disabled temporarily - requires more complex authorization model setup.
+     */
+    @Test
+    @org.junit.jupiter.api.Disabled("Requires complex authorization model setup")
+    public void rawRequest_check() throws Exception {
+        // Setup: Create store and authorization model
+        String storeName = "check-test-" + System.currentTimeMillis();
+        String storeId = createStoreUsingRawRequest(storeName);
+        fga.setStoreId(storeId);
+        String modelId = writeSimpleAuthorizationModel(storeId);
+
+        // Write a tuple
+        writeTupleUsingRawRequest(storeId, "user:alice", "reader", "document:budget");
+
+        // Use raw API to perform check
+        Map<String, Object> checkBody = new HashMap<>();
+        checkBody.put("authorization_model_id", modelId);
+
+        Map<String, Object> tupleKey = new HashMap<>();
+        tupleKey.put("user", "user:alice");
+        tupleKey.put("relation", "reader");
+        tupleKey.put("object", "document:budget");
+        checkBody.put("tuple_key", tupleKey);
+
+        RawRequestBuilder request =
+                RawRequestBuilder.builder("POST", "/stores/{store_id}/check").body(checkBody);
+
+        ApiResponse<CheckResponse> response =
+                fga.raw().send(request, CheckResponse.class).get();
+
+        // Verify response
+        assertNotNull(response);
+        assertEquals(200, response.getStatusCode());
+        assertNotNull(response.getData());
+        assertTrue(response.getData().getAllowed(), "Alice should be allowed to read the document");
+
+        System.out.println("✓ Successfully performed check using raw request");
+        System.out.println("  Check result: " + response.getData().getAllowed());
+    }
+
+    /**
+     * Test custom headers with raw request.
+     */
+    @Test
+    public void rawRequest_withCustomHeaders() throws Exception {
+        String storeName = "headers-test-" + System.currentTimeMillis();
+
+        Map<String, Object> requestBody = new HashMap<>();
+        requestBody.put("name", storeName);
+
+        // Use raw API with custom headers
+        RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores")
+                .body(requestBody)
+                .header("X-Custom-Header", "custom-value")
+                .header("X-Request-ID", "test-123");
+
+        ApiResponse<CreateStoreResponse> response =
+                fga.raw().send(request, CreateStoreResponse.class).get();
+
+        // Verify response
+        assertNotNull(response);
+        assertEquals(201, response.getStatusCode());
+
+        System.out.println("✓ Successfully sent raw request with custom headers");
+    }
+
+    /**
+     * Test error handling with raw request.
+     */
+    @Test
+    public void rawRequest_errorHandling_notFound() throws Exception {
+        // Try to get a non-existent store
+        RawRequestBuilder request =
+                RawRequestBuilder.builder("GET", "/stores/{store_id}").pathParam("store_id", "non-existent-store-id");
+
+        // Should throw an exception
+        try {
+            fga.raw().send(request, GetStoreResponse.class).get();
+            fail("Should have thrown an exception for non-existent store");
+        } catch (Exception e) {
+            // Expected - verify it's some kind of error (ExecutionException wrapping an FgaError)
+            assertNotNull(e, "Exception should not be null");
+            System.out.println("✓ Successfully handled error for non-existent store");
+            System.out.println("  Error type: " + e.getClass().getSimpleName());
+            if (e.getCause() != null) {
+                System.out.println("  Cause: " + e.getCause().getClass().getSimpleName());
+            }
+        }
+    }
+
+    /**
+     * Test list stores with pagination using query parameters.
+     */
+    @Test
+    public void rawRequest_listStores_withPagination() throws Exception {
+        // Create multiple stores
+        for (int i = 0; i < 3; i++) {
+            createStoreUsingRawRequest("pagination-test-" + i + "-" + System.currentTimeMillis());
+        }
+
+        // Use raw API to list stores with pagination
+        RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores").queryParam("page_size", "2");
+
+        ApiResponse<ListStoresResponse> response =
+                fga.raw().send(request, ListStoresResponse.class).get();
+
+        // Verify response
+        assertNotNull(response);
+        assertEquals(200, response.getStatusCode());
+        assertNotNull(response.getData());
+        assertNotNull(response.getData().getStores());
+
+        System.out.println("✓ Successfully listed stores with pagination");
+        System.out.println("  Returned: " + response.getData().getStores().size() + " stores");
+        if (response.getData().getContinuationToken() != null) {
+            System.out.println("  Has continuation token for next page");
+        }
+    }
+
+    // Helper methods
+
+    private String createStoreUsingRawRequest(String storeName) throws Exception {
+        Map<String, Object> requestBody = new HashMap<>();
+        requestBody.put("name", storeName);
+
+        RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores").body(requestBody);
+
+        ApiResponse<CreateStoreResponse> response =
+                fga.raw().send(request, CreateStoreResponse.class).get();
+
+        return response.getData().getId();
+    }
+
+    private String writeSimpleAuthorizationModel(String storeId) throws Exception {
+        Map<String, Object> requestBody = new HashMap<>();
+        requestBody.put("schema_version", "1.1");
+
+        // Create metadata for reader relation
+        Map<String, Object> readerMetadata = new HashMap<>();
+        readerMetadata.put("directly_related_user_types", List.of(Map.of("type", "user")));
+
+        Map<String, Object> relationMetadata = new HashMap<>();
+        relationMetadata.put("reader", readerMetadata);
+
+        Map<String, Object> metadata = new HashMap<>();
+        metadata.put("relations", relationMetadata);
+
+        Map<String, Object> readerRelation = new HashMap<>();
+        readerRelation.put("this", new HashMap<>());
+        Map<String, Object> relations = new HashMap<>();
+        relations.put("reader", readerRelation);
+
+        List<Map<String, Object>> typeDefinitions = List.of(
+                Map.of("type", "user", "relations", new HashMap<>()),
+                Map.of("type", "document", "relations", relations, "metadata", metadata));
+
+        requestBody.put("type_definitions", typeDefinitions);
+
+        RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/authorization-models")
+                .pathParam("store_id", storeId)
+                .body(requestBody);
+
+        ApiResponse<WriteAuthorizationModelResponse> response =
+                fga.raw().send(request, WriteAuthorizationModelResponse.class).get();
+
+        return response.getData().getAuthorizationModelId();
+    }
+
+    private void writeTupleUsingRawRequest(String storeId, String user, String relation, String object)
+            throws Exception {
+        Map<String, Object> tupleKey = new HashMap<>();
+        tupleKey.put("user", user);
+        tupleKey.put("relation", relation);
+        tupleKey.put("object", object);
+
+        Map<String, Object> requestBody = new HashMap<>();
+        requestBody.put("writes", List.of(Map.of("tuple_key", tupleKey)));
+
+        RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/write")
+                .pathParam("store_id", storeId)
+                .body(requestBody);
+
+        fga.raw().send(request, Object.class).get();
+    }
+}
diff --git a/src/test/java/dev/openfga/sdk/api/client/RawApiTest.java b/src/test/java/dev/openfga/sdk/api/client/RawApiTest.java
index ebdc93de..0301c7b3 100644
--- a/src/test/java/dev/openfga/sdk/api/client/RawApiTest.java
+++ b/src/test/java/dev/openfga/sdk/api/client/RawApiTest.java
@@ -7,6 +7,7 @@
 import com.github.tomakehurst.wiremock.junit5.WireMockRuntimeInfo;
 import com.github.tomakehurst.wiremock.junit5.WireMockTest;
 import dev.openfga.sdk.api.configuration.ClientConfiguration;
+import dev.openfga.sdk.errors.FgaError;
 import dev.openfga.sdk.errors.FgaInvalidParameterException;
 import java.util.HashMap;
 import java.util.Map;

From 9d64d0606c623f1b94a33c050c4a14b82d22716a Mon Sep 17 00:00:00 2001
From: Anurag Bandyopadhyay <angbpy@gmail.com>
Date: Tue, 13 Jan 2026 22:48:27 +0530
Subject: [PATCH 04/16] fix: rawapi doc

---
 docs/RawApi.md | 388 ++++++++++---------------------------------------
 1 file changed, 77 insertions(+), 311 deletions(-)

diff --git a/docs/RawApi.md b/docs/RawApi.md
index bbb1d204..93996fd2 100644
--- a/docs/RawApi.md
+++ b/docs/RawApi.md
@@ -1,389 +1,155 @@
-# Raw API - Alternative Access
+# Raw API
 
-## Overview
-
-The Raw API provides an alternative mechanism for calling OpenFGA endpoints that are not yet supported by the typed SDK methods. This is particularly useful for:
-
-- **Experimental Features**: Access newly released or experimental OpenFGA endpoints before they're officially supported in the SDK
-- **Beta Endpoints**: Test beta features without waiting for SDK updates
-- **Custom Extensions**: Call custom or extended OpenFGA endpoints in your deployment
-- **Rapid Prototyping**: Quickly integrate with new API features while SDK support is being developed
-
-## Key Benefits
-
-All requests made through the Raw API automatically benefit from the SDK's infrastructure:
-
-- ✅ **Automatic Authentication** - Bearer token injection handled automatically
-- ✅ **Configuration Adherence** - Respects base URLs, store IDs, and timeouts from your ClientConfiguration
-- ✅ **Automatic Retries** - Built-in retry logic for 5xx errors and network failures
-- ✅ **Consistent Error Handling** - Standard SDK exception handling for 400, 401, 404, 500 errors
-- ✅ **Type Safety** - Option to deserialize responses into typed Java objects or work with raw JSON
+Direct HTTP access to OpenFGA endpoints.
 
 ## Quick Start
 
-### Basic Usage
-
 ```java
-import dev.openfga.sdk.api.client.OpenFgaClient;
-import dev.openfga.sdk.api.client.RawRequestBuilder;
-import dev.openfga.sdk.api.configuration.ClientConfiguration;
-
-// Initialize the client
-ClientConfiguration config = new ClientConfiguration()
-    .apiUrl("http://localhost:8080")
-    .storeId("01YCP46JKYM8FJCQ37NMBYHE5X");
-
-OpenFgaClient fgaClient = new OpenFgaClient(config);
+OpenFgaClient client = new OpenFgaClient(config);
 
-// Example: Use RawRequestBuilder to call the actual /stores/{store_id}/check endpoint
+// Build request
 RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/check")
-    .pathParam("store_id", fgaClient.getStoreId())
-    .body(Map.of(
-        "tuple_key", Map.of(
-            "user", "user:jon",
-            "relation", "can_read",
-            "object", "document:2026"
-        ),
-        "contextual_tuples", List.of()
-    ));
-
-// Get raw JSON response
-fgaClient.raw().send(request)
-    .thenAccept(response -> {
-        System.out.println("Response: " + response.getRawResponse());
-    });
-```
+    .pathParam("store_id", storeId)
+    .body(Map.of("tuple_key", Map.of("user", "user:jon", "relation", "reader", "object", "doc:1")));
 
-## API Components
+// Execute - typed response
+ApiResponse<CheckResponse> response = client.raw().send(request, CheckResponse.class).get();
 
-### 1. RawRequestBuilder
+// Execute - raw JSON
+ApiResponse<String> rawResponse = client.raw().send(request).get();
+```
 
-The `RawRequestBuilder` provides a fluent interface for constructing HTTP requests.
+## API Reference
 
-#### Factory Method
+### RawRequestBuilder
 
+**Factory:**
 ```java
 RawRequestBuilder.builder(String method, String path)
 ```
 
-- **method**: HTTP method (GET, POST, PUT, DELETE, PATCH, etc.)
-- **path**: API path with optional placeholders like `{store_id}`
-
-#### Methods
-
-##### pathParam(String key, String value)
-Replaces path placeholders with values. Placeholders use curly brace syntax: `{parameter_name}`. Values are automatically URL-encoded.
-
+**Methods:**
 ```java
-.pathParam("store_id", "01YCP46JKYM8FJCQ37NMBYHE5X")
-.pathParam("model_id", "01G5JAVJ41T49E9TT3SKVS7X1J")
+.pathParam(String key, String value)      // Replace {key} in path, URL-encoded
+.queryParam(String key, String value)     // Add query parameter, URL-encoded
+.header(String key, String value)         // Add HTTP header
+.body(Object body)                        // Set request body (auto-serialized to JSON)
 ```
 
-##### queryParam(String key, String value)
-Adds query parameters to the URL. Parameters are automatically URL-encoded.
-
+**Example:**
 ```java
-.queryParam("page", "1")
-.queryParam("limit", "50")
+RawRequestBuilder.builder("POST", "/stores/{store_id}/write")
+    .pathParam("store_id", "01ABC")
+    .queryParam("dry_run", "true")
+    .header("X-Request-ID", "uuid")
+    .body(requestObject);
 ```
 
-##### header(String key, String value)
-Adds HTTP headers to the request. Standard headers (Authorization, Content-Type, User-Agent) are managed by the SDK.
+### RawApi
 
+**Access:**
 ```java
-.header("X-Request-ID", "unique-id-123")
-.header("X-Custom-Header", "value")
-```
-
-##### body(Object body)
-Sets the request body. Objects and Maps are serialized to JSON. Strings are sent without modification.
-.body(new CustomRequest("data", 123))
-
-// Map
-.body("{\"raw\":\"json\"}")
-```
-// POJO
-### 2. RawApi
-
-// String
-
-#### Accessing RawApi
-
-```java
-OpenFgaClient client = new OpenFgaClient(config);
 RawApi rawApi = client.raw();
 ```
 
-#### Methods
-
-##### send(RawRequestBuilder request)
-Execute a request and return the response as a raw JSON string.
-
+**Methods:**
 ```java
-CompletableFuture<ApiResponse<String>> future = rawApi.send(request);
+CompletableFuture<ApiResponse<String>> send(RawRequestBuilder request)
+CompletableFuture<ApiResponse<T>> send(RawRequestBuilder request, Class<T> responseType)
 ```
 
-##### send(RawRequestBuilder request, Class<T> responseType)
-Execute a request and deserialize the response into a typed object.
+### ApiResponse<T>
 
 ```java
-CompletableFuture<ApiResponse<MyResponse>> future = rawApi.send(request, MyResponse.class);
+int getStatusCode()                    // HTTP status
+Map<String, List<String>> getHeaders() // Response headers
+String getRawResponse()                // Raw JSON body
+T getData()                            // Deserialized data
 ```
 
-### 3. ApiResponse<T>
-
-The response object returned by the Raw API.
-
-```java
-public class ApiResponse<T> {
-    int getStatusCode()              // HTTP status code
-    Map<String, List<String>> getHeaders()  // Response headers
-    String getRawResponse()          // Raw JSON response body
-    T getData()                      // Deserialized response data
-}
-```
-
-## Usage Examples
-
-### Example 1: GET Request with Typed Response
+## Examples
 
+### Typed Response
 ```java
-// Define your response type
-public class FeatureResponse {
-    public boolean enabled;
-    public String version;
-}
-
-// Build and execute request
-RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}/experimental-feature")
-    .pathParam("store_id", client.getStoreId());
+RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}/feature")
+    .pathParam("store_id", storeId);
 
 client.raw().send(request, FeatureResponse.class)
-    .thenAccept(response -> {
-        System.out.println("Status: " + response.getStatusCode());
-        System.out.println("Enabled: " + response.getData().enabled);
-        System.out.println("Version: " + response.getData().version);
-    });
+    .thenAccept(r -> System.out.println("Status: " + r.getStatusCode()));
 ```
 
-### Example 2: POST Request with Request Body
-
+### POST with Body
 ```java
-// Define request and response types
-public class BulkDeleteRequest {
-    public String olderThan;
-    public String type;
-    public int limit;
-}
-
-public class BulkDeleteResponse {
-    public int deletedCount;
-    public String message;
-}
-
-// Build request with body
-BulkDeleteRequest requestBody = new BulkDeleteRequest();
-requestBody.olderThan = "2023-01-01";
-requestBody.type = "user";
-requestBody.limit = 1000;
-
 RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/bulk-delete")
-    .pathParam("store_id", client.getStoreId())
+    .pathParam("store_id", storeId)
     .queryParam("force", "true")
-    .body(requestBody);
+    .body(new BulkDeleteRequest("2023-01-01", "user", 1000));
 
-// Execute
-client.raw().send(request, BulkDeleteResponse.class)
-    .thenAccept(response -> {
-        System.out.println("Deleted: " + response.getData().deletedCount);
-    });
+client.raw().send(request, BulkDeleteResponse.class).get();
 ```
 
-### Example 3: Working with Raw JSON
-
+### Raw JSON Response
 ```java
-RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}/complex-data")
-    .pathParam("store_id", client.getStoreId());
-
-// Get raw JSON for inspection or custom parsing
-client.raw().send(request)
-    .thenAccept(response -> {
-        String json = response.getRawResponse();
-        System.out.println("Raw JSON: " + json);
-        // Parse manually if needed
-    });
+ApiResponse<String> response = client.raw().send(request).get();
+String json = response.getRawResponse(); // Raw JSON
 ```
 
-### Example 4: Query Parameters and Pagination
-
+### Query Parameters
 ```java
-RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}/items")
-    .pathParam("store_id", client.getStoreId())
+RawRequestBuilder.builder("GET", "/stores/{store_id}/items")
+    .pathParam("store_id", storeId)
     .queryParam("page", "1")
     .queryParam("limit", "50")
-    .queryParam("filter", "active")
     .queryParam("sort", "created_at");
-
-client.raw().send(request, ItemsResponse.class)
-    .thenAccept(response -> {
-        // Process paginated results
-    });
 ```
 
-### Example 5: Custom Headers
-
+### Custom Headers
 ```java
-RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/action")
-    .pathParam("store_id", client.getStoreId())
+RawRequestBuilder.builder("POST", "/stores/{store_id}/action")
     .header("X-Request-ID", UUID.randomUUID().toString())
-    .header("X-Client-Version", "1.0.0")
-    .header("X-Idempotency-Key", "unique-key-123")
-    .body(actionData);
-
-client.raw().send(request, ActionResponse.class)
-    .thenAccept(response -> {
-        // Handle response
-    });
+    .header("X-Idempotency-Key", "key-123")
+    .body(data);
 ```
 
-### Example 6: Error Handling
-
+### Error Handling
 ```java
-RawRequestBuilder request = RawRequestBuilder.builder("DELETE", "/stores/{store_id}/resource/{id}")
-    .pathParam("store_id", client.getStoreId())
-    .pathParam("id", resourceId);
-
-client.raw().send(request)
-    .thenAccept(response -> {
-        System.out.println("Successfully deleted. Status: " + response.getStatusCode());
-    })
+client.raw().send(request, ResponseType.class)
     .exceptionally(e -> {
-        // Standard SDK error handling applies:
         if (e.getCause() instanceof FgaError) {
             FgaError error = (FgaError) e.getCause();
-            System.err.println("API Error: " + error.getMessage());
-            System.err.println("Status Code: " + error.getStatusCode());
-        } else {
-            System.err.println("Network Error: " + e.getMessage());
+            System.err.println("API Error: " + error.getStatusCode());
         }
         return null;
     });
 ```
 
-### Example 7: Using Map for Request Body
-
-```java
-// Quick prototyping with Map instead of creating a POJO
-RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/configure")
-    .pathParam("store_id", client.getStoreId())
-    .body(Map.of(
-        "setting", "value",
-        "enabled", true,
-        "threshold", 100,
-        "options", List.of("opt1", "opt2")
-    ));
-
-client.raw().send(request, ConfigureResponse.class)
-    .thenAccept(response -> {
-        System.out.println("Configuration updated");
-    });
-```
-
-## Best Practices
-
-### 1. Define Response Types
-
-Define POJOs for response structures:
-
-```java
-public class ApiResponse {
-    @JsonProperty("field_name")
-    public String fieldName;
-    
-    public int count;
-}
-```
-
-### 2. Handle Errors
-
-Include error handling in production code:
-
-```java
-client.raw().send(request, ResponseType.class)
-    .thenAccept(response -> {
-        // Handle success
-    })
-    .exceptionally(e -> {
-        logger.error("Request failed", e);
-        return null;
-    });
-```
-
-### 3. URL Encoding
-
-The SDK automatically URL-encodes parameters. Do not manually encode:
-
+### Map as Request Body
 ```java
-// Correct
-.pathParam("id", "store with spaces")
-
-// Incorrect - double encoding
-.pathParam("id", URLEncoder.encode("store with spaces", UTF_8))
+.body(Map.of(
+    "setting", "value",
+    "enabled", true,
+    "threshold", 100,
+    "options", List.of("opt1", "opt2")
+))
 ```
 
+## Notes
 
-## Migration Path
+- Path/query parameters are URL-encoded automatically
+- Authentication tokens injected from client config
+- Retries on 429, 5xx errors
+- `{store_id}` auto-replaced if not provided via `.pathParam()`
 
-When the SDK adds official support for an endpoint you're using via Raw API:
+## Migration to Typed Methods
 
-### Before (Raw API)
 ```java
-RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/check")
-    .pathParam("store_id", client.getStoreId())
-    .body(checkRequest);
+// Raw API
+client.raw().send(
+    RawRequestBuilder.builder("POST", "/stores/{store_id}/check").body(req),
+    CheckResponse.class
+).get();
 
-client.raw().send(request, CheckResponse.class)
-    .thenAccept(response -> {
-        // Handle response
-    });
+// Typed SDK (when available)
+client.check(req).get();
 ```
 
-### After (Typed SDK Method)
-```java
-client.check(checkRequest)
-    .thenAccept(response -> {
-        // Handle response - same structure!
-    });
-```
-
-The response structure remains the same, making migration straightforward.
-
-## Limitations
-
-1. **No Code Generation**: Unlike typed methods, Raw API requests don't benefit from IDE autocomplete for request/response structures
-2. **Manual Type Definitions**: You need to define your own POJOs for request/response types
-3. **Less Validation**: The SDK can't validate request structure before sending
-4. **Documentation**: You'll need to refer to OpenFGA API documentation for endpoint details
-
-## When to Use Raw API
-
-✅ **Use Raw API when:**
-- The endpoint is experimental or in beta
-- The endpoint was just released and SDK support is pending
-- You need to quickly prototype with new features
-- You have custom OpenFGA extensions
-
-❌ **Use Typed SDK Methods when:**
-- The endpoint has official SDK support
-- You want maximum type safety and validation
-- You prefer IDE autocomplete and compile-time checks
-- The endpoint is stable and well-documented
-
-## Support and Feedback
-
-If you find yourself frequently using the Raw API for a particular endpoint, please:
-1. Open an issue on the SDK repository requesting official support
-2. Share your use case and the endpoint details
-3. Consider contributing a pull request with typed method implementation
-
-The goal of the Raw API is to provide flexibility while we work on comprehensive SDK support for all OpenFGA features.

From b38e82946889b1d2201d57d0b0437e06d94e2e78 Mon Sep 17 00:00:00 2001
From: SoulPancake <angbpy@gmail.com>
Date: Wed, 14 Jan 2026 11:53:19 +0530
Subject: [PATCH 05/16] feat: calling other endpoints section

---
 README.md | 112 ++++++++++++++++++++++++++++++++++--------------------
 1 file changed, 70 insertions(+), 42 deletions(-)

diff --git a/README.md b/README.md
index 7d115a10..62f6b0af 100644
--- a/README.md
+++ b/README.md
@@ -46,7 +46,7 @@ This is an autogenerated Java SDK for OpenFGA. It provides a wrapper around the
     - [Assertions](#assertions)
       - [Read Assertions](#read-assertions)
       - [Write Assertions](#write-assertions)
-  - [Raw API](#raw-api)
+  - [Calling Other Endpoints](#calling-other-endpoints)
   - [Retries](#retries)
   - [API Endpoints](#api-endpoints)
   - [Models](#models)
@@ -1168,57 +1168,85 @@ try {
 }
 ```
 
-### Raw API
+### Calling Other Endpoints
 
-The Raw API allows execution of HTTP requests to OpenFGA endpoints using the SDK's configured HTTP client. This is useful for accessing API endpoints that do not yet have typed SDK method implementations.
+In certain cases you may want to call other APIs not yet wrapped by the SDK. You can do so by using the APIExecutor available from the `fgaClient`. The APIExecutor allows you to make raw HTTP calls to any OpenFGA endpoint by specifying the operation name, HTTP method, path, parameters, body, and headers, while still honoring the client configuration (authentication, telemetry, retries, and error handling).
 
-#### Usage
+This is useful when:
+- you want to call a new endpoint that is not yet supported by the SDK
+- you are using an earlier version of the SDK that doesn't yet support a particular endpoint
+- you have a custom endpoint deployed that extends the OpenFGA API
 
-```java
-import dev.openfga.sdk.api.client.OpenFgaClient;
-import dev.openfga.sdk.api.client.RawRequestBuilder;
-import dev.openfga.sdk.api.configuration.ClientConfiguration;
-import java.util.Map;
-
-// Response type
-class CustomResponse {
-    public boolean success;
-    public int count;
-}
+In all cases, you initialize the SDK the same way as usual, and then get the APIExecutor from the `fgaClient` instance.
 
-// Client configuration
+```java
+// Initialize the client, same as above
 ClientConfiguration config = new ClientConfiguration()
     .apiUrl("http://localhost:8080")
     .storeId("01YCP46JKYM8FJCQ37NMBYHE5X");
-OpenFgaClient client = new OpenFgaClient(config);
-
-// Request execution
-RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/endpoint")
-    .pathParam("store_id", client.getStoreId())
-    .queryParam("param", "value")
-    .body(Map.of("key", "value"));
-
-// Typed response
-client.raw().send(request, CustomResponse.class)
-    .thenAccept(response -> {
-        System.out.println("Status: " + response.getStatusCode());
-        System.out.println("Data: " + response.getData());
-    });
-
-// Raw JSON response
-client.raw().send(request)
-    .thenAccept(response -> {
-        System.out.println("JSON: " + response.getRawResponse());
-    });
+OpenFgaClient fgaClient = new OpenFgaClient(config);
+
+// Get the generic API executor
+APIExecutor executor = fgaClient.getAPIExecutor();
+
+// Custom new endpoint that doesn't exist in the SDK yet
+Map<String, Object> requestBody = Map.of(
+    "user", "user:bob",
+    "action", "custom_action",
+    "resource", "resource:123"
+);
+
+// Build the request
+APIExecutorRequest request = new APIExecutorRequestBuilder("CustomEndpoint", "POST", "/stores/{store_id}/custom-endpoint")
+    .withPathParameter("store_id", storeId)
+    .withQueryParameter("page_size", "20")
+    .withQueryParameter("continuation_token", "eyJwayI6...")
+    .withBody(requestBody)
+    .withHeader("X-Experimental-Feature", "enabled")
+    .build();
+```
+
+#### Example: Calling a new "Custom Endpoint" endpoint and handling raw response
+
+```java
+// Get raw response without automatic decoding
+APIExecutorResponse rawResponse = executor.execute(request).get();
+
+// Manually decode the response
+ObjectMapper mapper = new ObjectMapper();
+Map<String, Object> result = mapper.readValue(rawResponse.getBody(), new TypeReference<Map<String, Object>>() {});
+
+System.out.println("Response: " + result);
+
+// You can access fields like headers, status code, etc. from rawResponse:
+System.out.println("Status Code: " + rawResponse.getStatusCode());
+System.out.println("Headers: " + rawResponse.getHeaders());
 ```
 
-#### Features
+#### Example: Calling a new "Custom Endpoint" endpoint and decoding response into a struct
 
-Requests automatically include:
-- Authentication credentials from configuration
-- Retry logic for 5xx errors with exponential backoff
-- Error handling and exception mapping
-- Configured timeouts and headers
+```java
+// Define a class to hold the response
+class CustomEndpointResponse {
+    private boolean allowed;
+    private String reason;
+    
+    public boolean isAllowed() { return allowed; }
+    public void setAllowed(boolean allowed) { this.allowed = allowed; }
+    public String getReason() { return reason; }
+    public void setReason(String reason) { this.reason = reason; }
+}
+
+// Get raw response decoded into CustomEndpointResponse class
+APIExecutorResponse rawResponse = executor.executeWithDecode(request, CustomEndpointResponse.class).get();
+
+CustomEndpointResponse customEndpointResponse = rawResponse.getData();
+System.out.println("Response: " + customEndpointResponse);
+
+// You can access fields like headers, status code, etc. from rawResponse:
+System.out.println("Status Code: " + rawResponse.getStatusCode());
+System.out.println("Headers: " + rawResponse.getHeaders());
+```
 
 #### Documentation
 

From 03cd5e21213f0a80161dbc8f945b1fbb39172b04 Mon Sep 17 00:00:00 2001
From: SoulPancake <angbpy@gmail.com>
Date: Wed, 14 Jan 2026 11:55:28 +0530
Subject: [PATCH 06/16] fix: typo in readme

---
 README.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/README.md b/README.md
index 62f6b0af..d64dcdc7 100644
--- a/README.md
+++ b/README.md
@@ -747,7 +747,7 @@ Similar to [check](#check), but instead of checking a single user-object relatio
 > Passing `ClientBatchCheckOptions` is optional. All fields of `ClientBatchCheckOptions` are optional.
 
 ```java
-var reequst = new ClientBatchCheckRequest().checks(
+var request = new ClientBatchCheckRequest().checks(
     List.of(
         new ClientBatchCheckItem()
             .user("user:81684243-9356-4421-8fbf-a4f8d36aa31b")
@@ -775,7 +775,7 @@ var reequst = new ClientBatchCheckRequest().checks(
             .user("user:81684243-9356-4421-8fbf-a4f8d36aa31b")
             .relation("creator")
             ._object("document:0192ab2a-d83f-756d-9397-c5ed9f3cb69a")
-            .correlationId("cor-3), // optional, one will be generated for you if not provided
+            .correlationId("cor-3"), // optional, one will be generated for you if not provided
         new ClientCheckRequest()
             .user("user:81684243-9356-4421-8fbf-a4f8d36aa31b")
             .relation("deleter")

From e8e1119fae202d1c6a7d29184d96955d4b1236d3 Mon Sep 17 00:00:00 2001
From: SoulPancake <angbpy@gmail.com>
Date: Wed, 14 Jan 2026 14:49:46 +0530
Subject: [PATCH 07/16] feat: refactor examples

---
 README.md                                     |  48 ++--
 examples/README.md                            |   7 +
 examples/RawApiSimpleExample.java             | 115 ---------
 examples/raw-api/Makefile                     |  17 ++
 examples/raw-api/README.md                    | 109 ++++++++
 examples/raw-api/build.gradle                 |  67 +++++
 examples/raw-api/gradle.properties            |   2 +
 .../gradle/wrapper/gradle-wrapper.properties  |   7 +
 examples/raw-api/gradlew                      | 234 ++++++++++++++++++
 examples/raw-api/gradlew.bat                  |  89 +++++++
 examples/raw-api/settings.gradle              |   2 +
 .../openfga/sdk/example}/RawApiExample.java   |  28 ++-
 examples/streamed-list-objects/build.gradle   |   2 +-
 .../dev/openfga/sdk/api/client/RawApi.java    |  23 +-
 14 files changed, 592 insertions(+), 158 deletions(-)
 delete mode 100644 examples/RawApiSimpleExample.java
 create mode 100644 examples/raw-api/Makefile
 create mode 100644 examples/raw-api/README.md
 create mode 100644 examples/raw-api/build.gradle
 create mode 100644 examples/raw-api/gradle.properties
 create mode 100644 examples/raw-api/gradle/wrapper/gradle-wrapper.properties
 create mode 100755 examples/raw-api/gradlew
 create mode 100644 examples/raw-api/gradlew.bat
 create mode 100644 examples/raw-api/settings.gradle
 rename examples/{ => raw-api/src/main/java/dev/openfga/sdk/example}/RawApiExample.java (94%)

diff --git a/README.md b/README.md
index d64dcdc7..d94fe867 100644
--- a/README.md
+++ b/README.md
@@ -1170,14 +1170,14 @@ try {
 
 ### Calling Other Endpoints
 
-In certain cases you may want to call other APIs not yet wrapped by the SDK. You can do so by using the APIExecutor available from the `fgaClient`. The APIExecutor allows you to make raw HTTP calls to any OpenFGA endpoint by specifying the operation name, HTTP method, path, parameters, body, and headers, while still honoring the client configuration (authentication, telemetry, retries, and error handling).
+In certain cases you may want to call other APIs not yet wrapped by the SDK. You can do so by using the Raw API available from the `fgaClient`. The Raw API allows you to make raw HTTP calls to any OpenFGA endpoint by specifying the HTTP method, path, parameters, body, and headers, while still honoring the client configuration (authentication, telemetry, retries, and error handling).
 
 This is useful when:
 - you want to call a new endpoint that is not yet supported by the SDK
 - you are using an earlier version of the SDK that doesn't yet support a particular endpoint
 - you have a custom endpoint deployed that extends the OpenFGA API
 
-In all cases, you initialize the SDK the same way as usual, and then get the APIExecutor from the `fgaClient` instance.
+In all cases, you initialize the SDK the same way as usual, and then use the Raw API from the `fgaClient` instance.
 
 ```java
 // Initialize the client, same as above
@@ -1186,9 +1186,6 @@ ClientConfiguration config = new ClientConfiguration()
     .storeId("01YCP46JKYM8FJCQ37NMBYHE5X");
 OpenFgaClient fgaClient = new OpenFgaClient(config);
 
-// Get the generic API executor
-APIExecutor executor = fgaClient.getAPIExecutor();
-
 // Custom new endpoint that doesn't exist in the SDK yet
 Map<String, Object> requestBody = Map.of(
     "user", "user:bob",
@@ -1197,26 +1194,22 @@ Map<String, Object> requestBody = Map.of(
 );
 
 // Build the request
-APIExecutorRequest request = new APIExecutorRequestBuilder("CustomEndpoint", "POST", "/stores/{store_id}/custom-endpoint")
-    .withPathParameter("store_id", storeId)
-    .withQueryParameter("page_size", "20")
-    .withQueryParameter("continuation_token", "eyJwayI6...")
-    .withBody(requestBody)
-    .withHeader("X-Experimental-Feature", "enabled")
-    .build();
+RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/custom-endpoint")
+    .pathParam("store_id", storeId)
+    .queryParam("page_size", "20")
+    .queryParam("continuation_token", "eyJwayI6...")
+    .body(requestBody)
+    .header("X-Experimental-Feature", "enabled");
 ```
 
 #### Example: Calling a new "Custom Endpoint" endpoint and handling raw response
 
 ```java
 // Get raw response without automatic decoding
-APIExecutorResponse rawResponse = executor.execute(request).get();
-
-// Manually decode the response
-ObjectMapper mapper = new ObjectMapper();
-Map<String, Object> result = mapper.readValue(rawResponse.getBody(), new TypeReference<Map<String, Object>>() {});
+ApiResponse<String> rawResponse = fgaClient.raw().send(request).get();
 
-System.out.println("Response: " + result);
+String rawJson = rawResponse.getData();
+System.out.println("Response: " + rawJson);
 
 // You can access fields like headers, status code, etc. from rawResponse:
 System.out.println("Status Code: " + rawResponse.getStatusCode());
@@ -1237,17 +1230,22 @@ class CustomEndpointResponse {
     public void setReason(String reason) { this.reason = reason; }
 }
 
-// Get raw response decoded into CustomEndpointResponse class
-APIExecutorResponse rawResponse = executor.executeWithDecode(request, CustomEndpointResponse.class).get();
+// Get response decoded into CustomEndpointResponse class
+ApiResponse<CustomEndpointResponse> response = fgaClient.raw()
+    .send(request, CustomEndpointResponse.class)
+    .get();
 
-CustomEndpointResponse customEndpointResponse = rawResponse.getData();
-System.out.println("Response: " + customEndpointResponse);
+CustomEndpointResponse customEndpointResponse = response.getData();
+System.out.println("Allowed: " + customEndpointResponse.isAllowed());
+System.out.println("Reason: " + customEndpointResponse.getReason());
 
-// You can access fields like headers, status code, etc. from rawResponse:
-System.out.println("Status Code: " + rawResponse.getStatusCode());
-System.out.println("Headers: " + rawResponse.getHeaders());
+// You can access fields like headers, status code, etc. from response:
+System.out.println("Status Code: " + response.getStatusCode());
+System.out.println("Headers: " + response.getHeaders());
 ```
 
+For a complete working example, see [examples/raw-api](examples/raw-api).
+
 #### Documentation
 
 See [docs/RawApi.md](docs/RawApi.md) for complete API reference and examples.
diff --git a/examples/README.md b/examples/README.md
index 47238df4..953f3d71 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -9,3 +9,10 @@ A simple example that creates a store, runs a set of calls against it including
 
 #### OpenTelemetry Examples
 - `opentelemetry/` - Demonstrates OpenTelemetry integration both via manual code configuration, as well as no-code instrumentation using the OpenTelemetry java agent
+
+#### Streaming Examples
+- `streamed-list-objects/` - Demonstrates using the StreamedListObjects API to retrieve large result sets without pagination limits
+
+#### Raw API Examples
+- `raw-api/` - Demonstrates using the Raw API to call OpenFGA endpoints that are not yet wrapped by the SDK, while still benefiting from the SDK's configuration (authentication, retries, error handling, etc.)
+
diff --git a/examples/RawApiSimpleExample.java b/examples/RawApiSimpleExample.java
deleted file mode 100644
index 17fd1728..00000000
--- a/examples/RawApiSimpleExample.java
+++ /dev/null
@@ -1,115 +0,0 @@
-package dev.openfga.sdk.examples;
-
-import dev.openfga.sdk.api.client.*;
-import dev.openfga.sdk.api.configuration.ClientConfiguration;
-import dev.openfga.sdk.api.model.*;
-import java.util.HashMap;
-import java.util.Map;
-
-/**
- * Simple example demonstrating Raw API usage.
- *
- * Run this with your local OpenFGA instance:
- * docker run --rm -p 8080:8080 -p 3000:3000 openfga/openfga run
- *
- * Then compile and run this example.
- */
-public class RawApiSimpleExample {
-
-    public static void main(String[] args) {
-        try {
-            // Initialize client
-            ClientConfiguration config = new ClientConfiguration()
-                .apiUrl("http://localhost:8080");
-
-            OpenFgaClient client = new OpenFgaClient(config);
-
-            System.out.println("=== Raw API Simple Example ===\n");
-
-            // Example 1: List stores (raw JSON)
-            System.out.println("1. Listing stores (raw JSON):");
-            RawRequestBuilder listRequest = RawRequestBuilder.builder("GET", "/stores");
-            ApiResponse<String> listResponse = client.raw().send(listRequest).get();
-            System.out.println("   Status: " + listResponse.getStatusCode());
-            System.out.println("   Raw JSON: " + listResponse.getData());
-            System.out.println();
-
-            // Example 2: Create a store (typed response)
-            System.out.println("2. Creating a store (typed response):");
-            Map<String, Object> createBody = new HashMap<>();
-            createBody.put("name", "raw-api-demo-store");
-
-            RawRequestBuilder createRequest = RawRequestBuilder.builder("POST", "/stores")
-                .body(createBody);
-
-            ApiResponse<CreateStoreResponse> createResponse =
-                client.raw().send(createRequest, CreateStoreResponse.class).get();
-
-            String storeId = createResponse.getData().getId();
-            String storeName = createResponse.getData().getName();
-
-            System.out.println("   Status: " + createResponse.getStatusCode());
-            System.out.println("   Store ID: " + storeId);
-            System.out.println("   Store Name: " + storeName);
-            System.out.println();
-
-            // Example 3: Get store with path parameter
-            System.out.println("3. Getting store by ID:");
-            RawRequestBuilder getRequest = RawRequestBuilder.builder("GET", "/stores/{store_id}")
-                .pathParam("store_id", storeId);
-
-            ApiResponse<GetStoreResponse> getResponse =
-                client.raw().send(getRequest, GetStoreResponse.class).get();
-
-            System.out.println("   Status: " + getResponse.getStatusCode());
-            System.out.println("   Retrieved store: " + getResponse.getData().getName());
-            System.out.println();
-
-            // Example 4: Automatic store_id replacement
-            System.out.println("4. Using automatic {store_id} replacement:");
-            client.setStoreId(storeId);
-
-            // No need to call .pathParam("store_id", ...)
-            RawRequestBuilder autoRequest = RawRequestBuilder.builder("GET", "/stores/{store_id}");
-            ApiResponse<GetStoreResponse> autoResponse =
-                client.raw().send(autoRequest, GetStoreResponse.class).get();
-
-            System.out.println("   Status: " + autoResponse.getStatusCode());
-            System.out.println("   Store auto-fetched: " + autoResponse.getData().getName());
-            System.out.println();
-
-            // Example 5: Query parameters
-            System.out.println("5. List stores with pagination:");
-            RawRequestBuilder paginatedRequest = RawRequestBuilder.builder("GET", "/stores")
-                .queryParam("page_size", "5");
-
-            ApiResponse<ListStoresResponse> paginatedResponse =
-                client.raw().send(paginatedRequest, ListStoresResponse.class).get();
-
-            System.out.println("   Status: " + paginatedResponse.getStatusCode());
-            System.out.println("   Stores returned: " + paginatedResponse.getData().getStores().size());
-            System.out.println();
-
-            // Example 6: Custom headers
-            System.out.println("6. Request with custom headers:");
-            RawRequestBuilder headerRequest = RawRequestBuilder.builder("GET", "/stores/{store_id}")
-                .pathParam("store_id", storeId)
-                .header("X-Custom-Header", "my-value")
-                .header("X-Request-ID", "demo-123");
-
-            ApiResponse<GetStoreResponse> headerResponse =
-                client.raw().send(headerRequest, GetStoreResponse.class).get();
-
-            System.out.println("   Status: " + headerResponse.getStatusCode());
-            System.out.println("   Custom headers sent successfully");
-            System.out.println();
-
-            System.out.println("=== All examples completed successfully! ===");
-
-        } catch (Exception e) {
-            System.err.println("Error: " + e.getMessage());
-            e.printStackTrace();
-        }
-    }
-}
-
diff --git a/examples/raw-api/Makefile b/examples/raw-api/Makefile
new file mode 100644
index 00000000..b3d9473e
--- /dev/null
+++ b/examples/raw-api/Makefile
@@ -0,0 +1,17 @@
+.PHONY: build run run-openfga
+all: build
+
+project_name=.
+openfga_version=latest
+language=java
+
+build:
+	../../gradlew -P language=$(language) build
+
+run:
+	../../gradlew -P language=$(language) run
+
+run-openfga:
+	docker pull docker.io/openfga/openfga:${openfga_version} && \
+		docker run -p 8080:8080 docker.io/openfga/openfga:${openfga_version} run
+
diff --git a/examples/raw-api/README.md b/examples/raw-api/README.md
new file mode 100644
index 00000000..ac6ab195
--- /dev/null
+++ b/examples/raw-api/README.md
@@ -0,0 +1,109 @@
+# Raw API Example
+
+Demonstrates using the Raw API to call OpenFGA endpoints that are not yet wrapped by the SDK.
+
+## What is the Raw API?
+
+The Raw API (also known as the "escape hatch") allows you to make HTTP calls to any OpenFGA endpoint while still benefiting from the SDK's configuration (authentication, telemetry, retries, and error handling).
+
+This is useful when:
+- You want to call a new endpoint that is not yet supported by the SDK
+- You are using an earlier version of the SDK that doesn't yet support a particular endpoint
+- You have a custom endpoint deployed that extends the OpenFGA API
+
+## Prerequisites
+
+- Java 11 or higher
+- OpenFGA server running on `http://localhost:8080` (or set `FGA_API_URL`)
+
+## Running
+
+```bash
+# From the SDK root directory, build the SDK first
+./gradlew build
+
+# Then run the example
+cd examples/raw-api
+./gradlew run
+```
+
+Or using the Makefile:
+
+```bash
+make build
+make run
+```
+
+## What it does
+
+The example demonstrates several key features of the Raw API:
+
+1. **POST Request with Typed Response**: Calls a hypothetical `/bulk-delete` endpoint and deserializes the response into a custom Java class
+2. **GET Request with Raw JSON**: Retrieves raw JSON response without automatic deserialization
+3. **Query Parameters**: Shows how to add query parameters for filtering and pagination
+4. **Custom Headers**: Demonstrates adding custom HTTP headers to requests
+5. **Error Handling**: Shows how the Raw API benefits from the SDK's built-in error handling and retry logic
+
+## Key Features
+
+### Request Building
+
+The Raw API uses a builder pattern to construct requests:
+
+```java
+RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/custom-endpoint")
+    .pathParam("store_id", storeId)
+    .queryParam("page_size", "20")
+    .queryParam("continuation_token", "eyJwayI6...")
+    .body(requestBody)
+    .header("X-Custom-Header", "value")
+    .build();
+```
+
+### Response Handling
+
+You can handle responses in two ways:
+
+**Typed Response (automatic deserialization):**
+```java
+client.raw().send(request, CustomResponse.class)
+    .thenAccept(response -> {
+        System.out.println("Data: " + response.getData());
+        System.out.println("Status: " + response.getStatusCode());
+    });
+```
+
+**Raw JSON Response:**
+```java
+client.raw().send(request)
+    .thenAccept(response -> {
+        System.out.println("Raw JSON: " + response.getRawResponse());
+    });
+```
+
+### Automatic Features
+
+The Raw API automatically includes:
+- Authentication credentials from your client configuration
+- Retry logic for 5xx errors with exponential backoff
+- Error handling and exception mapping
+- Configured timeouts and headers
+- Telemetry and observability hooks
+
+## Code Structure
+
+- `RawApiExample.java`: Main example class demonstrating various Raw API use cases
+- Custom response classes: `BulkDeleteResponse` and `ExperimentalFeatureResponse`
+
+## Notes
+
+This example uses hypothetical endpoints for demonstration purposes. In a real-world scenario:
+- Replace the endpoint paths with actual OpenFGA endpoints
+- Adjust the request/response structures to match your API
+- Handle errors appropriately for your use case
+
+## See Also
+
+- [Raw API Documentation](../../docs/RawApi.md)
+- [OpenFGA API Reference](https://openfga.dev/api)
+
diff --git a/examples/raw-api/build.gradle b/examples/raw-api/build.gradle
new file mode 100644
index 00000000..ea383081
--- /dev/null
+++ b/examples/raw-api/build.gradle
@@ -0,0 +1,67 @@
+plugins {
+    id 'application'
+    id 'com.diffplug.spotless' version '8.0.0'
+}
+
+application {
+    mainClass = 'dev.openfga.sdk.example.RawApiExample'
+}
+
+repositories {
+    mavenCentral()
+}
+
+ext {
+    jacksonVersion = "2.18.2"
+}
+
+dependencies {
+    // Use local build of SDK
+    implementation files('../../build/libs/openfga-sdk-0.9.4.jar')
+
+    // OpenFGA Language SDK for DSL transformation
+    implementation("dev.openfga:openfga-language:v0.2.0-beta.1")
+
+    // Serialization
+    implementation("com.fasterxml.jackson.core:jackson-core:$jacksonVersion")
+    implementation("com.fasterxml.jackson.core:jackson-annotations:$jacksonVersion")
+    implementation("com.fasterxml.jackson.core:jackson-databind:$jacksonVersion")
+    implementation("com.fasterxml.jackson.datatype:jackson-datatype-jsr310:$jacksonVersion")
+    implementation("org.openapitools:jackson-databind-nullable:0.2.7")
+
+    // OpenTelemetry (required by SDK)
+    implementation platform("io.opentelemetry:opentelemetry-bom:1.54.1")
+    implementation "io.opentelemetry:opentelemetry-api"
+
+    // JSR305 (required by SDK)
+    implementation "com.google.code.findbugs:jsr305:3.0.2"
+}
+
+// Use spotless plugin to automatically format code, remove unused import, etc
+// To apply changes directly to the file, run `gradlew spotlessApply`
+// Ref: https://github.com/diffplug/spotless/tree/main/plugin-gradle
+spotless {
+    // comment out below to run spotless as part of the `check` task
+    enforceCheck false
+    format 'misc', {
+        // define the files (e.g. '*.gradle', '*.md') to apply `misc` to
+        target '.gitignore'
+        // define the steps to apply to those files
+        trimTrailingWhitespace()
+        indentWithSpaces() // Takes an integer argument if you don't like 4
+        endWithNewline()
+    }
+    java {
+        palantirJavaFormat()
+        removeUnusedImports()
+        importOrder()
+    }
+}
+
+// Use spotless plugin to automatically format code, remove unused import, etc
+// To apply changes directly to the file, run `gradlew spotlessApply`
+// Ref: https://github.com/diffplug/spotless/tree/main/plugin-gradle
+tasks.register('fmt') {
+    dependsOn 'spotlessApply'
+}
+
diff --git a/examples/raw-api/gradle.properties b/examples/raw-api/gradle.properties
new file mode 100644
index 00000000..86d05ca7
--- /dev/null
+++ b/examples/raw-api/gradle.properties
@@ -0,0 +1,2 @@
+language=java
+
diff --git a/examples/raw-api/gradle/wrapper/gradle-wrapper.properties b/examples/raw-api/gradle/wrapper/gradle-wrapper.properties
new file mode 100644
index 00000000..a80b22ce
--- /dev/null
+++ b/examples/raw-api/gradle/wrapper/gradle-wrapper.properties
@@ -0,0 +1,7 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-bin.zip
+networkTimeout=10000
+validateDistributionUrl=true
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists
diff --git a/examples/raw-api/gradlew b/examples/raw-api/gradlew
new file mode 100755
index 00000000..005bcde0
--- /dev/null
+++ b/examples/raw-api/gradlew
@@ -0,0 +1,234 @@
+#!/bin/sh
+
+#
+# Copyright © 2015-2021 the original authors.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+#
+
+##############################################################################
+#
+#   Gradle start up script for POSIX generated by Gradle.
+#
+#   Important for running:
+#
+#   (1) You need a POSIX-compliant shell to run this script. If your /bin/sh is
+#       noncompliant, but you have some other compliant shell such as ksh or
+#       bash, then to run this script, type that shell name before the whole
+#       command line, like:
+#
+#           ksh Gradle
+#
+#       Busybox and similar reduced shells will NOT work, because this script
+#       requires all of these POSIX shell features:
+#         * functions;
+#         * expansions «$var», «${var}», «${var:-default}», «${var+SET}»,
+#           «${var#prefix}», «${var%suffix}», and «$( cmd )»;
+#         * compound commands having a testable exit status, especially «case»;
+#         * various built-in commands including «command», «set», and «ulimit».
+#
+#   Important for patching:
+#
+#   (2) This script targets any POSIX shell, so it avoids extensions provided
+#       by Bash, Ksh, etc; in particular arrays are avoided.
+#
+#       The "traditional" practice of packing multiple parameters into a
+#       space-separated string is a well documented source of bugs and security
+#       problems, so this is (mostly) avoided, by progressively accumulating
+#       options in "$@", and eventually passing that to Java.
+#
+#       Where the inherited environment variables (DEFAULT_JVM_OPTS, JAVA_OPTS,
+#       and GRADLE_OPTS) rely on word-splitting, this is performed explicitly;
+#       see the in-line comments for details.
+#
+#       There are tweaks for specific operating systems such as AIX, CygWin,
+#       Darwin, MinGW, and NonStop.
+#
+#   (3) This script is generated from the Groovy template
+#       https://github.com/gradle/gradle/blob/master/subprojects/plugins/src/main/resources/org/gradle/api/internal/plugins/unixStartScript.txt
+#       within the Gradle project.
+#
+#       You can find Gradle at https://github.com/gradle/gradle/.
+#
+##############################################################################
+
+# Attempt to set APP_HOME
+
+# Resolve links: $0 may be a link
+app_path=$0
+
+# Need this for daisy-chained symlinks.
+while
+    APP_HOME=${app_path%"${app_path##*/}"}  # leaves a trailing /; empty if no leading path
+    [ -h "$app_path" ]
+do
+    ls=$( ls -ld "$app_path" )
+    link=${ls#*' -> '}
+    case $link in             #(
+      /*)   app_path=$link ;; #(
+      *)    app_path=$APP_HOME$link ;;
+    esac
+done
+
+APP_HOME=$( cd "${APP_HOME:-./}" && pwd -P ) || exit
+
+APP_NAME="Gradle"
+APP_BASE_NAME=${0##*/}
+
+# Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+DEFAULT_JVM_OPTS='-Dfile.encoding=UTF-8 "-Xmx64m" "-Xms64m"'
+
+# Use the maximum available, or set MAX_FD != -1 to use that value.
+MAX_FD=maximum
+
+warn () {
+    echo "$*"
+} >&2
+
+die () {
+    echo
+    echo "$*"
+    echo
+    exit 1
+} >&2
+
+# OS specific support (must be 'true' or 'false').
+cygwin=false
+msys=false
+darwin=false
+nonstop=false
+case "$( uname )" in                #(
+  CYGWIN* )         cygwin=true  ;; #(
+  Darwin* )         darwin=true  ;; #(
+  MSYS* | MINGW* )  msys=true    ;; #(
+  NONSTOP* )        nonstop=true ;;
+esac
+
+CLASSPATH=$APP_HOME/gradle/wrapper/gradle-wrapper.jar
+
+
+# Determine the Java command to use to start the JVM.
+if [ -n "$JAVA_HOME" ] ; then
+    if [ -x "$JAVA_HOME/jre/sh/java" ] ; then
+        # IBM's JDK on AIX uses strange locations for the executables
+        JAVACMD=$JAVA_HOME/jre/sh/java
+    else
+        JAVACMD=$JAVA_HOME/bin/java
+    fi
+    if [ ! -x "$JAVACMD" ] ; then
+        die "ERROR: JAVA_HOME is set to an invalid directory: $JAVA_HOME
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+    fi
+else
+    JAVACMD=java
+    which java >/dev/null 2>&1 || die "ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+
+Please set the JAVA_HOME variable in your environment to match the
+location of your Java installation."
+fi
+
+# Increase the maximum file descriptors if we can.
+if ! "$cygwin" && ! "$darwin" && ! "$nonstop" ; then
+    case $MAX_FD in #(
+      max*)
+        MAX_FD=$( ulimit -H -n ) ||
+            warn "Could not query maximum file descriptor limit"
+    esac
+    case $MAX_FD in  #(
+      '' | soft) :;; #(
+      *)
+        ulimit -n "$MAX_FD" ||
+            warn "Could not set maximum file descriptor limit to $MAX_FD"
+    esac
+fi
+
+# Collect all arguments for the java command, stacking in reverse order:
+#   * args from the command line
+#   * the main class name
+#   * -classpath
+#   * -D...appname settings
+#   * --module-path (only if needed)
+#   * DEFAULT_JVM_OPTS, JAVA_OPTS, and GRADLE_OPTS environment variables.
+
+# For Cygwin or MSYS, switch paths to Windows format before running java
+if "$cygwin" || "$msys" ; then
+    APP_HOME=$( cygpath --path --mixed "$APP_HOME" )
+    CLASSPATH=$( cygpath --path --mixed "$CLASSPATH" )
+
+    JAVACMD=$( cygpath --unix "$JAVACMD" )
+
+    # Now convert the arguments - kludge to limit ourselves to /bin/sh
+    for arg do
+        if
+            case $arg in                                #(
+              -*)   false ;;                            # don't mess with options #(
+              /?*)  t=${arg#/} t=/${t%%/*}              # looks like a POSIX filepath
+                    [ -e "$t" ] ;;                      #(
+              *)    false ;;
+            esac
+        then
+            arg=$( cygpath --path --ignore --mixed "$arg" )
+        fi
+        # Roll the args list around exactly as many times as the number of
+        # args, so each arg winds up back in the position where it started, but
+        # possibly modified.
+        #
+        # NB: a `for` loop captures its iteration list before it begins, so
+        # changing the positional parameters here affects neither the number of
+        # iterations, nor the values presented in `arg`.
+        shift                   # remove old arg
+        set -- "$@" "$arg"      # push replacement arg
+    done
+fi
+
+# Collect all arguments for the java command;
+#   * $DEFAULT_JVM_OPTS, $JAVA_OPTS, and $GRADLE_OPTS can contain fragments of
+#     shell script including quotes and variable substitutions, so put them in
+#     double quotes to make sure that they get re-expanded; and
+#   * put everything else in single quotes, so that it's not re-expanded.
+
+set -- \
+        "-Dorg.gradle.appname=$APP_BASE_NAME" \
+        -classpath "$CLASSPATH" \
+        org.gradle.wrapper.GradleWrapperMain \
+        "$@"
+
+# Use "xargs" to parse quoted args.
+#
+# With -n1 it outputs one arg per line, with the quotes and backslashes removed.
+#
+# In Bash we could simply go:
+#
+#   readarray ARGS < <( xargs -n1 <<<"$var" ) &&
+#   set -- "${ARGS[@]}" "$@"
+#
+# but POSIX shell has neither arrays nor command substitution, so instead we
+# post-process each arg (as a line of input to sed) to backslash-escape any
+# character that might be a shell metacharacter, then use eval to reverse
+# that process (while maintaining the separation between arguments), and wrap
+# the whole thing up as a single "set" statement.
+#
+# This will of course break if any of these variables contains a newline or
+# an unmatched quote.
+#
+
+eval "set -- $(
+        printf '%s\n' "$DEFAULT_JVM_OPTS $JAVA_OPTS $GRADLE_OPTS" |
+        xargs -n1 |
+        sed ' s~[^-[:alnum:]+,./:=@_]~\\&~g; ' |
+        tr '\n' ' '
+    )" '"$@"'
+
+exec "$JAVACMD" "$@"
diff --git a/examples/raw-api/gradlew.bat b/examples/raw-api/gradlew.bat
new file mode 100644
index 00000000..6a68175e
--- /dev/null
+++ b/examples/raw-api/gradlew.bat
@@ -0,0 +1,89 @@
+@rem
+@rem Copyright 2015 the original author or authors.
+@rem
+@rem Licensed under the Apache License, Version 2.0 (the "License");
+@rem you may not use this file except in compliance with the License.
+@rem You may obtain a copy of the License at
+@rem
+@rem      https://www.apache.org/licenses/LICENSE-2.0
+@rem
+@rem Unless required by applicable law or agreed to in writing, software
+@rem distributed under the License is distributed on an "AS IS" BASIS,
+@rem WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+@rem See the License for the specific language governing permissions and
+@rem limitations under the License.
+@rem
+
+@if "%DEBUG%" == "" @echo off
+@rem ##########################################################################
+@rem
+@rem  Gradle startup script for Windows
+@rem
+@rem ##########################################################################
+
+@rem Set local scope for the variables with windows NT shell
+if "%OS%"=="Windows_NT" setlocal
+
+set DIRNAME=%~dp0
+if "%DIRNAME%" == "" set DIRNAME=.
+set APP_BASE_NAME=%~n0
+set APP_HOME=%DIRNAME%
+
+@rem Resolve any "." and ".." in APP_HOME to make it shorter.
+for %%i in ("%APP_HOME%") do set APP_HOME=%%~fi
+
+@rem Add default JVM options here. You can also use JAVA_OPTS and GRADLE_OPTS to pass JVM options to this script.
+set DEFAULT_JVM_OPTS=-Dfile.encoding=UTF-8 "-Xmx64m" "-Xms64m"
+
+@rem Find java.exe
+if defined JAVA_HOME goto findJavaFromJavaHome
+
+set JAVA_EXE=java.exe
+%JAVA_EXE% -version >NUL 2>&1
+if "%ERRORLEVEL%" == "0" goto execute
+
+echo.
+echo ERROR: JAVA_HOME is not set and no 'java' command could be found in your PATH.
+echo.
+echo Please set the JAVA_HOME variable in your environment to match the
+echo location of your Java installation.
+
+goto fail
+
+:findJavaFromJavaHome
+set JAVA_HOME=%JAVA_HOME:"=%
+set JAVA_EXE=%JAVA_HOME%/bin/java.exe
+
+if exist "%JAVA_EXE%" goto execute
+
+echo.
+echo ERROR: JAVA_HOME is set to an invalid directory: %JAVA_HOME%
+echo.
+echo Please set the JAVA_HOME variable in your environment to match the
+echo location of your Java installation.
+
+goto fail
+
+:execute
+@rem Setup the command line
+
+set CLASSPATH=%APP_HOME%\gradle\wrapper\gradle-wrapper.jar
+
+
+@rem Execute Gradle
+"%JAVA_EXE%" %DEFAULT_JVM_OPTS% %JAVA_OPTS% %GRADLE_OPTS% "-Dorg.gradle.appname=%APP_BASE_NAME%" -classpath "%CLASSPATH%" org.gradle.wrapper.GradleWrapperMain %*
+
+:end
+@rem End local scope for the variables with windows NT shell
+if "%ERRORLEVEL%"=="0" goto mainEnd
+
+:fail
+rem Set variable GRADLE_EXIT_CONSOLE if you need the _script_ return code instead of
+rem the _cmd.exe /c_ return code!
+if  not "" == "%GRADLE_EXIT_CONSOLE%" exit 1
+exit /b 1
+
+:mainEnd
+if "%OS%"=="Windows_NT" endlocal
+
+:omega
diff --git a/examples/raw-api/settings.gradle b/examples/raw-api/settings.gradle
new file mode 100644
index 00000000..215b83b9
--- /dev/null
+++ b/examples/raw-api/settings.gradle
@@ -0,0 +1,2 @@
+rootProject.name = 'raw-api-example'
+
diff --git a/examples/RawApiExample.java b/examples/raw-api/src/main/java/dev/openfga/sdk/example/RawApiExample.java
similarity index 94%
rename from examples/RawApiExample.java
rename to examples/raw-api/src/main/java/dev/openfga/sdk/example/RawApiExample.java
index a92595c1..22057a82 100644
--- a/examples/RawApiExample.java
+++ b/examples/raw-api/src/main/java/dev/openfga/sdk/example/RawApiExample.java
@@ -1,6 +1,5 @@
-package dev.openfga.sdk.examples;
+package dev.openfga.sdk.example;
 
-import dev.openfga.sdk.api.client.ApiResponse;
 import dev.openfga.sdk.api.client.OpenFgaClient;
 import dev.openfga.sdk.api.client.RawRequestBuilder;
 import dev.openfga.sdk.api.configuration.ClientConfiguration;
@@ -54,12 +53,17 @@ public static void main(String[] args) throws Exception {
         // Example 4: Request with custom headers
         System.out.println("\nExample 4: Request with custom headers");
         customHeadersExample(fgaClient);
+
+        // Example 5: Error handling
+        System.out.println("\nExample 5: Error handling");
+        errorHandlingExample(fgaClient);
     }
 
     /**
      * Example 1: POST request with request body and typed response.
-    private static void bulkDeleteExample(OpenFgaClient fgaClient) {
+     */
     private static void postRequestExample(OpenFgaClient fgaClient) {
+        try {
             // Build the raw request
             RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/bulk-delete")
                     .pathParam("store_id", "01YCP46JKYM8FJCQ37NMBYHE5X")
@@ -90,9 +94,10 @@ private static void postRequestExample(OpenFgaClient fgaClient) {
     }
 
     /**
-     * Example 2: Get a raw JSON response without typed deserialization.
-     * This is useful when you want to inspect the response or don't have a Java class.
      * Example 2: Get raw JSON response without deserialization.
+     * This is useful when you want to inspect the response or don't have a Java class.
+     */
+    private static void rawJsonExample(OpenFgaClient fgaClient) {
         try {
             RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}/experimental-feature")
                     .pathParam("store_id", "01YCP46JKYM8FJCQ37NMBYHE5X");
@@ -117,10 +122,10 @@ private static void postRequestExample(OpenFgaClient fgaClient) {
     }
 
     /**
-     * Example 3: Use query parameters to filter or paginate results.
+     * Example 3: Using query parameters for filtering or pagination.
      */
     private static void queryParametersExample(OpenFgaClient fgaClient) {
-     * Example 3: Using query parameters for filtering or pagination.
+        try {
             RawRequestBuilder request =
                     RawRequestBuilder.builder("GET", "/stores/{store_id}/experimental-list")
                             .pathParam("store_id", "01YCP46JKYM8FJCQ37NMBYHE5X")
@@ -148,10 +153,10 @@ private static void queryParametersExample(OpenFgaClient fgaClient) {
     }
 
     /**
-     * Example 4: Add custom headers to the request.
+     * Example 4: Adding custom headers to requests.
      */
     private static void customHeadersExample(OpenFgaClient fgaClient) {
-     * Example 4: Adding custom headers to requests.
+        try {
             RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/experimental-action")
                     .pathParam("store_id", "01YCP46JKYM8FJCQ37NMBYHE5X")
                     .header("X-Request-ID", "unique-request-123")
@@ -177,10 +182,11 @@ private static void customHeadersExample(OpenFgaClient fgaClient) {
     }
 
     /**
-     * Bonus Example: Error handling with the Raw API.
+     * Example 5: Error handling with the Raw API.
      * The Raw API automatically benefits from the SDK's error handling and retries.
      */
-     * Error handling example. The Raw API uses standard SDK error handling and retries.
+    private static void errorHandlingExample(OpenFgaClient fgaClient) {
+        try {
             RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}/non-existent")
                     .pathParam("store_id", "01YCP46JKYM8FJCQ37NMBYHE5X");
 
diff --git a/examples/streamed-list-objects/build.gradle b/examples/streamed-list-objects/build.gradle
index d3039b04..08cf3c3a 100644
--- a/examples/streamed-list-objects/build.gradle
+++ b/examples/streamed-list-objects/build.gradle
@@ -17,7 +17,7 @@ ext {
 
 dependencies {
     // Use local build of SDK
-    implementation files('../../build/libs/openfga-sdk-0.9.3.jar')
+    implementation files('../../build/libs/openfga-sdk-0.9.4.jar')
 
     // OpenFGA Language SDK for DSL transformation
     implementation("dev.openfga:openfga-language:v0.2.0-beta.1")
diff --git a/src/main/java/dev/openfga/sdk/api/client/RawApi.java b/src/main/java/dev/openfga/sdk/api/client/RawApi.java
index 0eaa05d6..80a4ebed 100644
--- a/src/main/java/dev/openfga/sdk/api/client/RawApi.java
+++ b/src/main/java/dev/openfga/sdk/api/client/RawApi.java
@@ -95,23 +95,26 @@ public <T> CompletableFuture<ApiResponse<T>> send(RawRequestBuilder requestBuild
     }
 
     private String buildCompletePath(RawRequestBuilder requestBuilder) {
-        String path = requestBuilder.getPath();
+        StringBuilder pathBuilder = new StringBuilder(requestBuilder.getPath());
         Map<String, String> pathParams = requestBuilder.getPathParams();
+
         // Automatic {store_id} replacement if not provided
-        if (path.contains("{store_id}") && !pathParams.containsKey("store_id")) {
+        if (pathBuilder.indexOf("{store_id}") != -1 && !pathParams.containsKey("store_id")) {
             if (configuration instanceof dev.openfga.sdk.api.configuration.ClientConfiguration) {
                 String storeId = ((dev.openfga.sdk.api.configuration.ClientConfiguration) configuration).getStoreId();
                 if (storeId != null) {
-                    path = path.replace("{store_id}", dev.openfga.sdk.util.StringUtil.urlEncode(storeId));
+                    replaceInBuilder(pathBuilder, "{store_id}", dev.openfga.sdk.util.StringUtil.urlEncode(storeId));
                 }
             }
         }
+
         // Replace path parameters
         for (Map.Entry<String, String> entry : pathParams.entrySet()) {
             String placeholder = "{" + entry.getKey() + "}";
             String encodedValue = dev.openfga.sdk.util.StringUtil.urlEncode(entry.getValue());
-            path = path.replace(placeholder, encodedValue);
+            replaceInBuilder(pathBuilder, placeholder, encodedValue);
         }
+
         // Add query parameters (sorted for deterministic order)
         Map<String, String> queryParams = requestBuilder.getQueryParams();
         if (!queryParams.isEmpty()) {
@@ -120,10 +123,18 @@ private String buildCompletePath(RawRequestBuilder requestBuilder) {
                     .map(entry -> dev.openfga.sdk.util.StringUtil.urlEncode(entry.getKey()) + "="
                             + dev.openfga.sdk.util.StringUtil.urlEncode(entry.getValue()))
                     .collect(java.util.stream.Collectors.joining("&"));
-            path = path + (path.contains("?") ? "&" : "?") + queryString;
+            pathBuilder.append(pathBuilder.indexOf("?") != -1 ? "&" : "?").append(queryString);
         }
 
-        return path;
+        return pathBuilder.toString();
+    }
+
+    private void replaceInBuilder(StringBuilder builder, String target, String replacement) {
+        int index = builder.indexOf(target);
+        while (index != -1) {
+            builder.replace(index, index + target.length(), replacement);
+            index = builder.indexOf(target, index + replacement.length());
+        }
     }
 
     private HttpRequest buildHttpRequest(RawRequestBuilder requestBuilder, String path)

From 382f7980ad9ee1b43f2fb02630480bf08b073b10 Mon Sep 17 00:00:00 2001
From: SoulPancake <angbpy@gmail.com>
Date: Wed, 14 Jan 2026 15:09:29 +0530
Subject: [PATCH 08/16] fix: refactor example

---
 examples/raw-api/README.md                    | 43 +++++++++----------
 .../openfga/sdk/example/RawApiExample.java    | 13 +++---
 2 files changed, 27 insertions(+), 29 deletions(-)

diff --git a/examples/raw-api/README.md b/examples/raw-api/README.md
index ac6ab195..79b2e7b1 100644
--- a/examples/raw-api/README.md
+++ b/examples/raw-api/README.md
@@ -4,12 +4,12 @@ Demonstrates using the Raw API to call OpenFGA endpoints that are not yet wrappe
 
 ## What is the Raw API?
 
-The Raw API (also known as the "escape hatch") allows you to make HTTP calls to any OpenFGA endpoint while still benefiting from the SDK's configuration (authentication, telemetry, retries, and error handling).
+The Raw API provides direct HTTP access to OpenFGA endpoints while maintaining the SDK's configuration (authentication, telemetry, retries, and error handling).
 
-This is useful when:
-- You want to call a new endpoint that is not yet supported by the SDK
-- You are using an earlier version of the SDK that doesn't yet support a particular endpoint
-- You have a custom endpoint deployed that extends the OpenFGA API
+Use cases:
+- Calling endpoints not yet wrapped by the SDK
+- Using an SDK version that lacks support for a particular endpoint
+- Accessing custom endpoints that extend the OpenFGA API
 
 ## Prerequisites
 
@@ -36,19 +36,19 @@ make run
 
 ## What it does
 
-The example demonstrates several key features of the Raw API:
+The example demonstrates Raw API capabilities:
 
-1. **POST Request with Typed Response**: Calls a hypothetical `/bulk-delete` endpoint and deserializes the response into a custom Java class
-2. **GET Request with Raw JSON**: Retrieves raw JSON response without automatic deserialization
-3. **Query Parameters**: Shows how to add query parameters for filtering and pagination
-4. **Custom Headers**: Demonstrates adding custom HTTP headers to requests
-5. **Error Handling**: Shows how the Raw API benefits from the SDK's built-in error handling and retry logic
+1. **POST Request with Typed Response**: Sends a request and deserializes the response into a custom Java class
+2. **GET Request with Raw JSON**: Retrieves the raw JSON response string
+3. **Query Parameters**: Adds query parameters to the request
+4. **Custom Headers**: Adds custom HTTP headers to the request
+5. **Error Handling**: Demonstrates SDK error handling and retry behavior
 
 ## Key Features
 
 ### Request Building
 
-The Raw API uses a builder pattern to construct requests:
+Build requests using the builder pattern:
 
 ```java
 RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/custom-endpoint")
@@ -62,7 +62,6 @@ RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id
 
 ### Response Handling
 
-You can handle responses in two ways:
 
 **Typed Response (automatic deserialization):**
 ```java
@@ -81,26 +80,26 @@ client.raw().send(request)
     });
 ```
 
-### Automatic Features
+### SDK Features Applied
 
-The Raw API automatically includes:
-- Authentication credentials from your client configuration
+Requests automatically include:
+- Authentication credentials
 - Retry logic for 5xx errors with exponential backoff
 - Error handling and exception mapping
 - Configured timeouts and headers
-- Telemetry and observability hooks
+- Telemetry hooks
 
 ## Code Structure
 
-- `RawApiExample.java`: Main example class demonstrating various Raw API use cases
+- `RawApiExample.java`: Example demonstrating Raw API usage
 - Custom response classes: `BulkDeleteResponse` and `ExperimentalFeatureResponse`
 
 ## Notes
 
-This example uses hypothetical endpoints for demonstration purposes. In a real-world scenario:
-- Replace the endpoint paths with actual OpenFGA endpoints
-- Adjust the request/response structures to match your API
-- Handle errors appropriately for your use case
+This example uses placeholder endpoints for demonstration. In production:
+- Use actual OpenFGA endpoint paths
+- Match request/response structures to the target API
+- Implement appropriate error handling
 
 ## See Also
 
diff --git a/examples/raw-api/src/main/java/dev/openfga/sdk/example/RawApiExample.java b/examples/raw-api/src/main/java/dev/openfga/sdk/example/RawApiExample.java
index 22057a82..e1488ee5 100644
--- a/examples/raw-api/src/main/java/dev/openfga/sdk/example/RawApiExample.java
+++ b/examples/raw-api/src/main/java/dev/openfga/sdk/example/RawApiExample.java
@@ -6,10 +6,10 @@
 import java.util.Map;
 
 /**
- * Example demonstrating the Raw API "Escape Hatch" functionality.
+ * Example demonstrating Raw API usage.
  *
- * This example shows how to use the Raw API to call experimental or newly-released
- * OpenFGA endpoints that may not yet be supported in the typed SDK methods.
+ * This example shows how to use the Raw API to call OpenFGA endpoints
+ * that are not yet wrapped by the SDK's typed methods.
  */
 public class RawApiExample {
 
@@ -95,7 +95,6 @@ private static void postRequestExample(OpenFgaClient fgaClient) {
 
     /**
      * Example 2: Get raw JSON response without deserialization.
-     * This is useful when you want to inspect the response or don't have a Java class.
      */
     private static void rawJsonExample(OpenFgaClient fgaClient) {
         try {
@@ -122,7 +121,7 @@ private static void rawJsonExample(OpenFgaClient fgaClient) {
     }
 
     /**
-     * Example 3: Using query parameters for filtering or pagination.
+     * Example 3: Add query parameters to requests.
      */
     private static void queryParametersExample(OpenFgaClient fgaClient) {
         try {
@@ -153,7 +152,7 @@ private static void queryParametersExample(OpenFgaClient fgaClient) {
     }
 
     /**
-     * Example 4: Adding custom headers to requests.
+     * Example 4: Add custom headers to requests.
      */
     private static void customHeadersExample(OpenFgaClient fgaClient) {
         try {
@@ -183,7 +182,7 @@ private static void customHeadersExample(OpenFgaClient fgaClient) {
 
     /**
      * Example 5: Error handling with the Raw API.
-     * The Raw API automatically benefits from the SDK's error handling and retries.
+     * Requests use the SDK's error handling and retry logic.
      */
     private static void errorHandlingExample(OpenFgaClient fgaClient) {
         try {

From 94cb6fd3274ca84fdc75b6bba528269f03ff899c Mon Sep 17 00:00:00 2001
From: SoulPancake <angbpy@gmail.com>
Date: Wed, 14 Jan 2026 15:10:51 +0530
Subject: [PATCH 09/16] fix: comment '

---
 README.md          | 12 ++++++------
 examples/README.md |  2 +-
 2 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/README.md b/README.md
index d94fe867..0875193b 100644
--- a/README.md
+++ b/README.md
@@ -1170,14 +1170,14 @@ try {
 
 ### Calling Other Endpoints
 
-In certain cases you may want to call other APIs not yet wrapped by the SDK. You can do so by using the Raw API available from the `fgaClient`. The Raw API allows you to make raw HTTP calls to any OpenFGA endpoint by specifying the HTTP method, path, parameters, body, and headers, while still honoring the client configuration (authentication, telemetry, retries, and error handling).
+The Raw API provides direct HTTP access to OpenFGA endpoints not yet wrapped by the SDK. It maintains the SDK's client configuration including authentication, telemetry, retries, and error handling.
 
-This is useful when:
-- you want to call a new endpoint that is not yet supported by the SDK
-- you are using an earlier version of the SDK that doesn't yet support a particular endpoint
-- you have a custom endpoint deployed that extends the OpenFGA API
+Use cases:
+- Calling endpoints not yet supported by the SDK
+- Using an SDK version that lacks support for a particular endpoint
+- Accessing custom endpoints that extend the OpenFGA API
 
-In all cases, you initialize the SDK the same way as usual, and then use the Raw API from the `fgaClient` instance.
+Initialize the SDK normally and access the Raw API via the `fgaClient` instance:
 
 ```java
 // Initialize the client, same as above
diff --git a/examples/README.md b/examples/README.md
index 953f3d71..e93757d4 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -14,5 +14,5 @@ A simple example that creates a store, runs a set of calls against it including
 - `streamed-list-objects/` - Demonstrates using the StreamedListObjects API to retrieve large result sets without pagination limits
 
 #### Raw API Examples
-- `raw-api/` - Demonstrates using the Raw API to call OpenFGA endpoints that are not yet wrapped by the SDK, while still benefiting from the SDK's configuration (authentication, retries, error handling, etc.)
+- `raw-api/` - Demonstrates direct HTTP access to OpenFGA endpoints not yet wrapped by the SDK, maintaining SDK configuration (authentication, retries, error handling)
 

From 32868d9c6eba3016dca2c39794a9e1603af5782d Mon Sep 17 00:00:00 2001
From: SoulPancake <angbpy@gmail.com>
Date: Wed, 14 Jan 2026 18:36:53 +0530
Subject: [PATCH 10/16] feat: use list stores via raw req

---
 examples/raw-api/README.md                    |  28 +-
 .../openfga/sdk/example/RawApiExample.java    | 265 +++++++++---------
 2 files changed, 146 insertions(+), 147 deletions(-)

diff --git a/examples/raw-api/README.md b/examples/raw-api/README.md
index 79b2e7b1..c13c7552 100644
--- a/examples/raw-api/README.md
+++ b/examples/raw-api/README.md
@@ -19,7 +19,11 @@ Use cases:
 ## Running
 
 ```bash
-# From the SDK root directory, build the SDK first
+# Start OpenFGA server first (if not already running)
+docker run -p 8080:8080 openfga/openfga run
+
+# From the SDK root directory, build the SDK
+cd /Users/anurag/openfga/java-sdk
 ./gradlew build
 
 # Then run the example
@@ -36,13 +40,15 @@ make run
 
 ## What it does
 
-The example demonstrates Raw API capabilities:
+The example demonstrates Raw API capabilities using real OpenFGA endpoints:
+
+1. **List Stores (GET with typed response)**: Lists all stores and deserializes into `ListStoresResponse`
+2. **Get Store (GET with raw JSON)**: Retrieves a single store and returns the raw JSON string
+3. **List Stores with Pagination**: Demonstrates query parameters using `page_size`
+4. **Create Store (POST with custom headers)**: Creates a new store with custom HTTP headers
+5. **Error Handling**: Attempts to get a non-existent store and handles the 404 error properly
 
-1. **POST Request with Typed Response**: Sends a request and deserializes the response into a custom Java class
-2. **GET Request with Raw JSON**: Retrieves the raw JSON response string
-3. **Query Parameters**: Adds query parameters to the request
-4. **Custom Headers**: Adds custom HTTP headers to the request
-5. **Error Handling**: Demonstrates SDK error handling and retry behavior
+All requests will succeed (except #5 which intentionally triggers an error for demonstration).
 
 ## Key Features
 
@@ -91,15 +97,11 @@ Requests automatically include:
 
 ## Code Structure
 
-- `RawApiExample.java`: Example demonstrating Raw API usage
-- Custom response classes: `BulkDeleteResponse` and `ExperimentalFeatureResponse`
+- `RawApiExample.java`: Example demonstrating Raw API usage with real OpenFGA endpoints
 
 ## Notes
 
-This example uses placeholder endpoints for demonstration. In production:
-- Use actual OpenFGA endpoint paths
-- Match request/response structures to the target API
-- Implement appropriate error handling
+This example uses real OpenFGA endpoints (`/stores`, `/stores/{store_id}`) to demonstrate actual functionality. The Raw API can be used with any OpenFGA endpoint, including custom endpoints if you have extended the API.
 
 ## See Also
 
diff --git a/examples/raw-api/src/main/java/dev/openfga/sdk/example/RawApiExample.java b/examples/raw-api/src/main/java/dev/openfga/sdk/example/RawApiExample.java
index e1488ee5..83e698fb 100644
--- a/examples/raw-api/src/main/java/dev/openfga/sdk/example/RawApiExample.java
+++ b/examples/raw-api/src/main/java/dev/openfga/sdk/example/RawApiExample.java
@@ -3,6 +3,10 @@
 import dev.openfga.sdk.api.client.OpenFgaClient;
 import dev.openfga.sdk.api.client.RawRequestBuilder;
 import dev.openfga.sdk.api.configuration.ClientConfiguration;
+import dev.openfga.sdk.api.model.CreateStoreRequest;
+import dev.openfga.sdk.api.model.ListStoresResponse;
+import dev.openfga.sdk.api.model.Store;
+import java.util.List;
 import java.util.Map;
 
 /**
@@ -10,173 +14,177 @@
  *
  * This example shows how to use the Raw API to call OpenFGA endpoints
  * that are not yet wrapped by the SDK's typed methods.
+ *
+ * The example uses real OpenFGA endpoints to demonstrate actual functionality.
  */
 public class RawApiExample {
 
-    /**
-     * Custom response type for demonstration.
-     */
-    public static class BulkDeleteResponse {
-        public int deletedCount;
-        public String message;
-    }
-
-    /**
-     * Custom response type for demonstration.
-     */
-    public static class ExperimentalFeatureResponse {
-        public boolean enabled;
-        public String version;
-        public Map<String, Object> metadata;
-    }
-
     public static void main(String[] args) throws Exception {
-        // Initialize the OpenFGA client
-        ClientConfiguration config = new ClientConfiguration()
-                .apiUrl("http://localhost:8080")
-                .storeId("01YCP46JKYM8FJCQ37NMBYHE5X");
+        // Initialize the OpenFGA client (no store ID needed for list stores)
+        ClientConfiguration config = new ClientConfiguration().apiUrl("http://localhost:8080");
 
         OpenFgaClient fgaClient = new OpenFgaClient(config);
 
-        // Example 1: Call a POST endpoint with typed response
-        System.out.println("Example 1: POST request with typed response");
-        postRequestExample(fgaClient);
+        System.out.println("=== Raw API Examples ===\n");
+
+        // Example 1: List stores with typed response
+        System.out.println("Example 1: List stores (GET with typed response)");
+        String storeId = listStoresExample(fgaClient);
 
-        // Example 2: GET request with raw JSON response
-        System.out.println("\nExample 2: GET request with raw JSON");
-        rawJsonExample(fgaClient);
+        // Example 2: Get store with raw JSON response
+        System.out.println("\nExample 2: Get store (GET with raw JSON)");
+        getStoreRawJsonExample(fgaClient, storeId);
 
-        // Example 3: Request with query parameters
-        System.out.println("\nExample 3: Request with query parameters");
-        queryParametersExample(fgaClient);
+        // Example 3: List stores with query parameters
+        System.out.println("\nExample 3: List stores with pagination (query parameters)");
+        listStoresWithPaginationExample(fgaClient);
 
-        // Example 4: Request with custom headers
-        System.out.println("\nExample 4: Request with custom headers");
-        customHeadersExample(fgaClient);
+        // Example 4: Create store with custom headers
+        System.out.println("\nExample 4: Create store (POST with custom headers)");
+        createStoreWithHeadersExample(fgaClient);
 
-        // Example 5: Error handling
-        System.out.println("\nExample 5: Error handling");
+        // Example 5: Error handling - try to get non-existent store
+        System.out.println("\nExample 5: Error handling (404 error)");
         errorHandlingExample(fgaClient);
+
+        System.out.println("\n=== All examples completed ===");
     }
 
     /**
-     * Example 1: POST request with request body and typed response.
+     * Example 1: GET request with typed response.
+     * Lists all stores using the Raw API and returns a store ID for use in other examples.
      */
-    private static void postRequestExample(OpenFgaClient fgaClient) {
+    private static String listStoresExample(OpenFgaClient fgaClient) {
         try {
-            // Build the raw request
-            RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/bulk-delete")
-                    .pathParam("store_id", "01YCP46JKYM8FJCQ37NMBYHE5X")
-                    .queryParam("force", "true")
-                    .body(Map.of(
-                            "older_than", "2023-01-01",
-                            "type", "user",
-                            "limit", 1000));
+            // Build the raw request for GET /stores
+            RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores");
 
             // Execute with typed response
-            fgaClient
+            var response = fgaClient
                     .raw()
-                    .send(request, BulkDeleteResponse.class)
-                    .thenAccept(response -> {
-                        System.out.println("Status: " + response.getStatusCode());
-                        System.out.println("Deleted items: " + response.getData().deletedCount);
-                        System.out.println("Message: " + response.getData().message);
-                    })
-                    .exceptionally(e -> {
-                        System.err.println("Error: " + e.getMessage());
-                        return null;
-                    })
-                    .get(); // Wait for completion (in production, avoid blocking)
+                    .send(request, ListStoresResponse.class)
+                    .get();
+
+            System.out.println("✓ Status: " + response.getStatusCode());
+            List<Store> stores = response.getData().getStores();
+            System.out.println("✓ Found " + stores.size() + " store(s)");
+
+            if (!stores.isEmpty()) {
+                Store firstStore = stores.get(0);
+                System.out.println("✓ First store: " + firstStore.getName() + " (ID: " + firstStore.getId() + ")");
+                return firstStore.getId();
+            } else {
+                // Create a store if none exist
+                System.out.println("  No stores found, creating one...");
+                return createStoreForExamples(fgaClient);
+            }
 
         } catch (Exception e) {
-            System.err.println("Failed to execute bulk delete: " + e.getMessage());
+            System.err.println("✗ Error: " + e.getMessage());
+            // Create a store on error
+            try {
+                return createStoreForExamples(fgaClient);
+            } catch (Exception ex) {
+                return "01YCP46JKYM8FJCQ37NMBYHE5X"; // fallback
+            }
         }
     }
 
+    /**
+     * Helper method to create a store for examples.
+     */
+    private static String createStoreForExamples(OpenFgaClient fgaClient) throws Exception {
+        String storeName = "raw-api-example-" + System.currentTimeMillis();
+        RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores")
+                .body(Map.of("name", storeName));
+
+        var response = fgaClient.raw().send(request).get();
+        String rawJson = response.getData();
+        System.out.println("  Created store: " + storeName);
+
+        // Extract store ID from JSON (simple parsing)
+        String idPrefix = "\"id\":\"";
+        int idStart = rawJson.indexOf(idPrefix);
+        if (idStart == -1) {
+            throw new RuntimeException("Could not find store ID in response: " + rawJson);
+        }
+        idStart += idPrefix.length();
+        int idEnd = rawJson.indexOf("\"", idStart);
+        if (idEnd == -1) {
+            throw new RuntimeException("Could not parse store ID from response: " + rawJson);
+        }
+        return rawJson.substring(idStart, idEnd);
+    }
+
     /**
      * Example 2: Get raw JSON response without deserialization.
      */
-    private static void rawJsonExample(OpenFgaClient fgaClient) {
+    private static void getStoreRawJsonExample(OpenFgaClient fgaClient, String storeId) {
         try {
-            RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}/experimental-feature")
-                    .pathParam("store_id", "01YCP46JKYM8FJCQ37NMBYHE5X");
+            RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}")
+                    .pathParam("store_id", storeId);
 
             // Execute and get raw JSON string
-            fgaClient
-                    .raw()
-                    .send(request) // No class specified = returns String
-                    .thenAccept(response -> {
-                        System.out.println("Status: " + response.getStatusCode());
-                        System.out.println("Raw JSON: " + response.getRawResponse());
-                    })
-                    .exceptionally(e -> {
-                        System.err.println("Error: " + e.getMessage());
-                        return null;
-                    })
-                    .get();
+            var response = fgaClient.raw().send(request).get();
+
+            System.out.println("✓ Status: " + response.getStatusCode());
+            System.out.println("✓ Raw JSON: " + response.getData());
+            System.out.println("✓ Content-Type: " + response.getHeaders().get("content-type"));
 
         } catch (Exception e) {
-            System.err.println("Failed to get raw response: " + e.getMessage());
+            System.err.println("✗ Error: " + e.getMessage());
         }
     }
 
     /**
      * Example 3: Add query parameters to requests.
      */
-    private static void queryParametersExample(OpenFgaClient fgaClient) {
+    private static void listStoresWithPaginationExample(OpenFgaClient fgaClient) {
         try {
-            RawRequestBuilder request =
-                    RawRequestBuilder.builder("GET", "/stores/{store_id}/experimental-list")
-                            .pathParam("store_id", "01YCP46JKYM8FJCQ37NMBYHE5X")
-                            .queryParam("page", "1")
-                            .queryParam("limit", "50")
-                            .queryParam("filter", "active");
-
-            fgaClient
+            RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores")
+                    .queryParam("page_size", "2");
+
+            var response = fgaClient
                     .raw()
-                    .send(request, ExperimentalFeatureResponse.class)
-                    .thenAccept(response -> {
-                        System.out.println("Status: " + response.getStatusCode());
-                        System.out.println("Feature enabled: " + response.getData().enabled);
-                        System.out.println("Version: " + response.getData().version);
-                    })
-                    .exceptionally(e -> {
-                        System.err.println("Error: " + e.getMessage());
-                        return null;
-                    })
+                    .send(request, ListStoresResponse.class)
                     .get();
 
+            System.out.println("✓ Status: " + response.getStatusCode());
+            System.out.println("✓ Stores returned: " + response.getData().getStores().size());
+            if (response.getData().getContinuationToken() != null) {
+                String token = response.getData().getContinuationToken();
+                String tokenPreview = token.length() > 20 ? token.substring(0, 20) + "..." : token;
+                System.out.println("✓ Continuation token present: " + tokenPreview);
+            } else {
+                System.out.println("✓ No continuation token (all results returned)");
+            }
+
         } catch (Exception e) {
-            System.err.println("Failed to call endpoint with query params: " + e.getMessage());
+            System.err.println("✗ Error: " + e.getMessage());
         }
     }
 
     /**
      * Example 4: Add custom headers to requests.
      */
-    private static void customHeadersExample(OpenFgaClient fgaClient) {
+    private static void createStoreWithHeadersExample(OpenFgaClient fgaClient) {
         try {
-            RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/experimental-action")
-                    .pathParam("store_id", "01YCP46JKYM8FJCQ37NMBYHE5X")
-                    .header("X-Request-ID", "unique-request-123")
-                    .header("X-Client-Version", "1.0.0")
-                    .body(Map.of("action", "test"));
+            String storeName = "raw-api-custom-headers-" + System.currentTimeMillis();
+            RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores")
+                    .header("X-Example-Header", "custom-value")
+                    .header("X-Request-ID", "req-" + System.currentTimeMillis())
+                    .body(Map.of("name", storeName));
 
-            fgaClient
-                    .raw()
-                    .send(request, ExperimentalFeatureResponse.class)
-                    .thenAccept(response -> {
-                        System.out.println("Status: " + response.getStatusCode());
-                        System.out.println("Response: " + response.getData());
-                    })
-                    .exceptionally(e -> {
-                        System.err.println("Error: " + e.getMessage());
-                        return null;
-                    })
-                    .get();
+            var response = fgaClient.raw().send(request).get();
+
+            System.out.println("✓ Status: " + response.getStatusCode());
+            System.out.println("✓ Store created successfully");
+            String responseData = response.getData();
+            String preview = responseData.length() > 100 ? responseData.substring(0, 100) + "..." : responseData;
+            System.out.println("✓ Response: " + preview);
 
         } catch (Exception e) {
-            System.err.println("Failed to call endpoint with custom headers: " + e.getMessage());
+            System.err.println("✗ Error: " + e.getMessage());
         }
     }
 
@@ -186,30 +194,19 @@ private static void customHeadersExample(OpenFgaClient fgaClient) {
      */
     private static void errorHandlingExample(OpenFgaClient fgaClient) {
         try {
-            RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}/non-existent")
-                    .pathParam("store_id", "01YCP46JKYM8FJCQ37NMBYHE5X");
+            // Try to get a non-existent store
+            RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}")
+                    .pathParam("store_id", "01ZZZZZZZZZZZZZZZZZZZZZZZ9");
 
-            fgaClient
-                    .raw()
-                    .send(request)
-                    .thenAccept(response -> {
-                        System.out.println("Success: " + response.getStatusCode());
-                    })
-                    .exceptionally(e -> {
-                        // Standard SDK error handling works here:
-                        // - 401: Unauthorized
-                        // - 404: Not Found
-                        // - 500: Internal Server Error (with automatic retries)
-                        System.err.println("API Error: " + e.getMessage());
-                        if (e.getCause() != null) {
-                            System.err.println("Cause: " + e.getCause().getClass().getName());
-                        }
-                        return null;
-                    })
-                    .get();
+            var response = fgaClient.raw().send(request).get();
+
+            System.out.println("✓ Success: " + response.getStatusCode());
 
         } catch (Exception e) {
-            System.err.println("Failed with error: " + e.getMessage());
+            // Expected error - demonstrates proper error handling
+            System.out.println("✓ Error handled correctly:");
+            System.out.println("  Message: " + e.getMessage());
+            System.out.println("  Type: " + e.getCause().getClass().getSimpleName());
         }
     }
 }

From 947eddf30c4fc404e06530b46af8c134034a20e7 Mon Sep 17 00:00:00 2001
From: SoulPancake <angbpy@gmail.com>
Date: Wed, 14 Jan 2026 19:01:34 +0530
Subject: [PATCH 11/16] feat: refactor add typed resp in example

---
 .../openfga/sdk/example/RawApiExample.java    | 32 ++++++++-----------
 .../sdk/api/client/RawRequestBuilder.java     | 16 ++++++++--
 .../openfga/sdk/api/client/RawApiTest.java    | 19 +++++++++++
 3 files changed, 46 insertions(+), 21 deletions(-)

diff --git a/examples/raw-api/src/main/java/dev/openfga/sdk/example/RawApiExample.java b/examples/raw-api/src/main/java/dev/openfga/sdk/example/RawApiExample.java
index 83e698fb..f9f6b69e 100644
--- a/examples/raw-api/src/main/java/dev/openfga/sdk/example/RawApiExample.java
+++ b/examples/raw-api/src/main/java/dev/openfga/sdk/example/RawApiExample.java
@@ -3,11 +3,12 @@
 import dev.openfga.sdk.api.client.OpenFgaClient;
 import dev.openfga.sdk.api.client.RawRequestBuilder;
 import dev.openfga.sdk.api.configuration.ClientConfiguration;
-import dev.openfga.sdk.api.model.CreateStoreRequest;
+import dev.openfga.sdk.api.model.CreateStoreResponse;
 import dev.openfga.sdk.api.model.ListStoresResponse;
 import dev.openfga.sdk.api.model.Store;
 import java.util.List;
 import java.util.Map;
+import java.util.UUID;
 
 /**
  * Example demonstrating Raw API usage.
@@ -16,6 +17,11 @@
  * that are not yet wrapped by the SDK's typed methods.
  *
  * The example uses real OpenFGA endpoints to demonstrate actual functionality.
+ *
+ * Note: Examples use .get() to block for simplicity. In production, use async patterns:
+ * - thenApply/thenAccept for chaining
+ * - thenCompose for sequential async operations
+ * - CompletableFuture.allOf for parallel operations
  */
 public class RawApiExample {
 
@@ -94,26 +100,14 @@ private static String listStoresExample(OpenFgaClient fgaClient) {
      * Helper method to create a store for examples.
      */
     private static String createStoreForExamples(OpenFgaClient fgaClient) throws Exception {
-        String storeName = "raw-api-example-" + System.currentTimeMillis();
+        String storeName = "raw-api-example-" + UUID.randomUUID().toString().substring(0, 8);
         RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores")
                 .body(Map.of("name", storeName));
 
-        var response = fgaClient.raw().send(request).get();
-        String rawJson = response.getData();
+        // Use typed response instead of manual JSON parsing
+        var response = fgaClient.raw().send(request, CreateStoreResponse.class).get();
         System.out.println("  Created store: " + storeName);
-
-        // Extract store ID from JSON (simple parsing)
-        String idPrefix = "\"id\":\"";
-        int idStart = rawJson.indexOf(idPrefix);
-        if (idStart == -1) {
-            throw new RuntimeException("Could not find store ID in response: " + rawJson);
-        }
-        idStart += idPrefix.length();
-        int idEnd = rawJson.indexOf("\"", idStart);
-        if (idEnd == -1) {
-            throw new RuntimeException("Could not parse store ID from response: " + rawJson);
-        }
-        return rawJson.substring(idStart, idEnd);
+        return response.getData().getId();
     }
 
     /**
@@ -169,10 +163,10 @@ private static void listStoresWithPaginationExample(OpenFgaClient fgaClient) {
      */
     private static void createStoreWithHeadersExample(OpenFgaClient fgaClient) {
         try {
-            String storeName = "raw-api-custom-headers-" + System.currentTimeMillis();
+            String storeName = "raw-api-custom-headers-" + UUID.randomUUID().toString().substring(0, 8);
             RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores")
                     .header("X-Example-Header", "custom-value")
-                    .header("X-Request-ID", "req-" + System.currentTimeMillis())
+                    .header("X-Request-ID", "req-" + UUID.randomUUID())
                     .body(Map.of("name", storeName));
 
             var response = fgaClient.raw().send(request).get();
diff --git a/src/main/java/dev/openfga/sdk/api/client/RawRequestBuilder.java b/src/main/java/dev/openfga/sdk/api/client/RawRequestBuilder.java
index 4eb40aee..2dc2ef08 100644
--- a/src/main/java/dev/openfga/sdk/api/client/RawRequestBuilder.java
+++ b/src/main/java/dev/openfga/sdk/api/client/RawRequestBuilder.java
@@ -2,6 +2,7 @@
 
 import java.util.HashMap;
 import java.util.Map;
+import java.util.Set;
 
 /**
  * Fluent builder for constructing HTTP requests to OpenFGA API endpoints.
@@ -17,6 +18,9 @@
  * }</pre>
  */
 public class RawRequestBuilder {
+    private static final Set<String> VALID_HTTP_METHODS =
+            Set.of("GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS");
+
     private final String method;
     private final String path;
     private final Map<String, String> pathParams;
@@ -36,9 +40,10 @@ private RawRequestBuilder(String method, String path) {
     /**
      * Creates a new RawRequestBuilder instance.
      *
-     * @param method HTTP method (GET, POST, PUT, DELETE, etc.)
+     * @param method HTTP method (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS)
      * @param path API path with optional placeholders like {store_id}
      * @return New RawRequestBuilder instance
+     * @throws IllegalArgumentException if method or path is invalid
      */
     public static RawRequestBuilder builder(String method, String path) {
         if (method == null || method.trim().isEmpty()) {
@@ -47,7 +52,14 @@ public static RawRequestBuilder builder(String method, String path) {
         if (path == null || path.trim().isEmpty()) {
             throw new IllegalArgumentException("Path cannot be null or empty");
         }
-        return new RawRequestBuilder(method.toUpperCase(), path);
+
+        String upperMethod = method.toUpperCase();
+        if (!VALID_HTTP_METHODS.contains(upperMethod)) {
+            throw new IllegalArgumentException(
+                    "Invalid HTTP method: " + method + ". Valid methods: " + VALID_HTTP_METHODS);
+        }
+
+        return new RawRequestBuilder(upperMethod, path);
     }
 
     /**
diff --git a/src/test/java/dev/openfga/sdk/api/client/RawApiTest.java b/src/test/java/dev/openfga/sdk/api/client/RawApiTest.java
index 0301c7b3..f689e293 100644
--- a/src/test/java/dev/openfga/sdk/api/client/RawApiTest.java
+++ b/src/test/java/dev/openfga/sdk/api/client/RawApiTest.java
@@ -134,6 +134,25 @@ public void rawRequestBuilder_throwsExceptionForEmptyPath() {
         assertThrows(IllegalArgumentException.class, () -> RawRequestBuilder.builder("GET", ""));
     }
 
+    @Test
+    public void rawRequestBuilder_throwsExceptionForInvalidHttpMethod() {
+        IllegalArgumentException exception = assertThrows(
+                IllegalArgumentException.class, () -> RawRequestBuilder.builder("INVALID", "/test"));
+        assertTrue(exception.getMessage().contains("Invalid HTTP method"));
+    }
+
+    @Test
+    public void rawRequestBuilder_acceptsValidHttpMethods() {
+        assertDoesNotThrow(() -> RawRequestBuilder.builder("GET", "/test"));
+        assertDoesNotThrow(() -> RawRequestBuilder.builder("POST", "/test"));
+        assertDoesNotThrow(() -> RawRequestBuilder.builder("PUT", "/test"));
+        assertDoesNotThrow(() -> RawRequestBuilder.builder("PATCH", "/test"));
+        assertDoesNotThrow(() -> RawRequestBuilder.builder("DELETE", "/test"));
+        assertDoesNotThrow(() -> RawRequestBuilder.builder("HEAD", "/test"));
+        assertDoesNotThrow(() -> RawRequestBuilder.builder("OPTIONS", "/test"));
+        assertDoesNotThrow(() -> RawRequestBuilder.builder("get", "/test"));
+    }
+
     @Test
     public void rawApi_canSendGetRequestWithTypedResponse() throws Exception {
         // Setup mock server

From 60b69a45d2ae051f6c3c1ac08b50927cdecb33d5 Mon Sep 17 00:00:00 2001
From: SoulPancake <angbpy@gmail.com>
Date: Wed, 14 Jan 2026 19:01:55 +0530
Subject: [PATCH 12/16] fix: spotless fmt

---
 src/test/java/dev/openfga/sdk/api/client/RawApiTest.java | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/test/java/dev/openfga/sdk/api/client/RawApiTest.java b/src/test/java/dev/openfga/sdk/api/client/RawApiTest.java
index f689e293..f2e60833 100644
--- a/src/test/java/dev/openfga/sdk/api/client/RawApiTest.java
+++ b/src/test/java/dev/openfga/sdk/api/client/RawApiTest.java
@@ -136,8 +136,8 @@ public void rawRequestBuilder_throwsExceptionForEmptyPath() {
 
     @Test
     public void rawRequestBuilder_throwsExceptionForInvalidHttpMethod() {
-        IllegalArgumentException exception = assertThrows(
-                IllegalArgumentException.class, () -> RawRequestBuilder.builder("INVALID", "/test"));
+        IllegalArgumentException exception =
+                assertThrows(IllegalArgumentException.class, () -> RawRequestBuilder.builder("INVALID", "/test"));
         assertTrue(exception.getMessage().contains("Invalid HTTP method"));
     }
 

From e1e3f680ed676005aa777d1d7c82e030888cc89a Mon Sep 17 00:00:00 2001
From: Anurag Bandyopadhyay <angbpy@gmail.com>
Date: Wed, 14 Jan 2026 20:54:25 +0530
Subject: [PATCH 13/16] feat: address copilot comments

---
 examples/raw-api/README.md                                    | 4 +---
 .../dev/openfga/sdk/api/client/RawApiIntegrationTest.java     | 2 +-
 2 files changed, 2 insertions(+), 4 deletions(-)

diff --git a/examples/raw-api/README.md b/examples/raw-api/README.md
index c13c7552..93695864 100644
--- a/examples/raw-api/README.md
+++ b/examples/raw-api/README.md
@@ -23,7 +23,6 @@ Use cases:
 docker run -p 8080:8080 openfga/openfga run
 
 # From the SDK root directory, build the SDK
-cd /Users/anurag/openfga/java-sdk
 ./gradlew build
 
 # Then run the example
@@ -62,8 +61,7 @@ RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id
     .queryParam("page_size", "20")
     .queryParam("continuation_token", "eyJwayI6...")
     .body(requestBody)
-    .header("X-Custom-Header", "value")
-    .build();
+    .header("X-Custom-Header", "value");
 ```
 
 ### Response Handling
diff --git a/src/test-integration/java/dev/openfga/sdk/api/client/RawApiIntegrationTest.java b/src/test-integration/java/dev/openfga/sdk/api/client/RawApiIntegrationTest.java
index 868a6d79..d738d68b 100644
--- a/src/test-integration/java/dev/openfga/sdk/api/client/RawApiIntegrationTest.java
+++ b/src/test-integration/java/dev/openfga/sdk/api/client/RawApiIntegrationTest.java
@@ -447,7 +447,7 @@ private void writeTupleUsingRawRequest(String storeId, String user, String relat
         tupleKey.put("object", object);
 
         Map<String, Object> requestBody = new HashMap<>();
-        requestBody.put("writes", List.of(Map.of("tuple_key", tupleKey)));
+        requestBody.put("writes", Map.of("tuple_keys", List.of(tupleKey)));
 
         RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/write")
                 .pathParam("store_id", storeId)

From d7325a25437bcf8c95278e21bc4813eabc4431c3 Mon Sep 17 00:00:00 2001
From: Anurag Bandyopadhyay <angbpy@gmail.com>
Date: Wed, 14 Jan 2026 20:59:26 +0530
Subject: [PATCH 14/16] feat: address coderabbit comments

---
 src/main/java/dev/openfga/sdk/api/client/RawApi.java | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/main/java/dev/openfga/sdk/api/client/RawApi.java b/src/main/java/dev/openfga/sdk/api/client/RawApi.java
index 80a4ebed..2e5424c2 100644
--- a/src/main/java/dev/openfga/sdk/api/client/RawApi.java
+++ b/src/main/java/dev/openfga/sdk/api/client/RawApi.java
@@ -149,7 +149,7 @@ private HttpRequest buildHttpRequest(RawRequestBuilder requestBuilder, String pa
 
             // Handle String body separately
             if (body instanceof String) {
-                bodyBytes = ((String) body).getBytes();
+                bodyBytes = ((String) body).getBytes(java.nio.charset.StandardCharsets.UTF_8);
             } else {
                 bodyBytes = apiClient.getObjectMapper().writeValueAsBytes(body);
             }

From 541be99a67beb7932c2e70d6f18ba7cf83e99884 Mon Sep 17 00:00:00 2001
From: Anurag Bandyopadhyay <angbpy@gmail.com>
Date: Wed, 14 Jan 2026 21:02:22 +0530
Subject: [PATCH 15/16] fix: use gradle 8.2.1 for example

---
 examples/raw-api/gradle/wrapper/gradle-wrapper.properties | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/examples/raw-api/gradle/wrapper/gradle-wrapper.properties b/examples/raw-api/gradle/wrapper/gradle-wrapper.properties
index a80b22ce..c747538f 100644
--- a/examples/raw-api/gradle/wrapper/gradle-wrapper.properties
+++ b/examples/raw-api/gradle/wrapper/gradle-wrapper.properties
@@ -1,6 +1,6 @@
 distributionBase=GRADLE_USER_HOME
 distributionPath=wrapper/dists
-distributionUrl=https\://services.gradle.org/distributions/gradle-8.6-bin.zip
+distributionUrl=https\://services.gradle.org/distributions/gradle-8.2.1-all.zip
 networkTimeout=10000
 validateDistributionUrl=true
 zipStoreBase=GRADLE_USER_HOME

From f16918707fb8d6f7199379f775f9de502da4a510 Mon Sep 17 00:00:00 2001
From: Anurag Bandyopadhyay <angbpy@gmail.com>
Date: Wed, 14 Jan 2026 22:35:40 +0530
Subject: [PATCH 16/16] feat: use build buulder chain for consistency

---
 README.md                                     |  3 +-
 docs/RawApi.md                                | 50 ++++++++++-------
 examples/raw-api/README.md                    |  3 +-
 .../openfga/sdk/example/RawApiExample.java    | 17 +++---
 .../dev/openfga/sdk/api/client/RawApi.java    |  3 +-
 .../sdk/api/client/RawRequestBuilder.java     | 15 +++++-
 .../sdk/api/client/RawApiIntegrationTest.java | 53 +++++++++++--------
 .../openfga/sdk/api/client/RawApiTest.java    | 53 ++++++++++++-------
 8 files changed, 126 insertions(+), 71 deletions(-)

diff --git a/README.md b/README.md
index 0875193b..a3e7bcf3 100644
--- a/README.md
+++ b/README.md
@@ -1199,7 +1199,8 @@ RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id
     .queryParam("page_size", "20")
     .queryParam("continuation_token", "eyJwayI6...")
     .body(requestBody)
-    .header("X-Experimental-Feature", "enabled");
+    .header("X-Experimental-Feature", "enabled")
+    .build();
 ```
 
 #### Example: Calling a new "Custom Endpoint" endpoint and handling raw response
diff --git a/docs/RawApi.md b/docs/RawApi.md
index 93996fd2..240b5192 100644
--- a/docs/RawApi.md
+++ b/docs/RawApi.md
@@ -10,7 +10,8 @@ OpenFgaClient client = new OpenFgaClient(config);
 // Build request
 RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/check")
     .pathParam("store_id", storeId)
-    .body(Map.of("tuple_key", Map.of("user", "user:jon", "relation", "reader", "object", "doc:1")));
+    .body(Map.of("tuple_key", Map.of("user", "user:jon", "relation", "reader", "object", "doc:1")))
+    .build();
 
 // Execute - typed response
 ApiResponse<CheckResponse> response = client.raw().send(request, CheckResponse.class).get();
@@ -34,15 +35,17 @@ RawRequestBuilder.builder(String method, String path)
 .queryParam(String key, String value)     // Add query parameter, URL-encoded
 .header(String key, String value)         // Add HTTP header
 .body(Object body)                        // Set request body (auto-serialized to JSON)
+.build()                                  // Complete the builder (required)
 ```
 
 **Example:**
 ```java
-RawRequestBuilder.builder("POST", "/stores/{store_id}/write")
+RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/write")
     .pathParam("store_id", "01ABC")
     .queryParam("dry_run", "true")
     .header("X-Request-ID", "uuid")
-    .body(requestObject);
+    .body(requestObject)
+    .build();
 ```
 
 ### RawApi
@@ -69,10 +72,11 @@ T getData()                            // Deserialized data
 
 ## Examples
 
-### Typed Response
+### GET Request
 ```java
 RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}/feature")
-    .pathParam("store_id", storeId);
+    .pathParam("store_id", storeId)
+    .build();
 
 client.raw().send(request, FeatureResponse.class)
     .thenAccept(r -> System.out.println("Status: " + r.getStatusCode()));
@@ -83,7 +87,8 @@ client.raw().send(request, FeatureResponse.class)
 RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/bulk-delete")
     .pathParam("store_id", storeId)
     .queryParam("force", "true")
-    .body(new BulkDeleteRequest("2023-01-01", "user", 1000));
+    .body(new BulkDeleteRequest("2023-01-01", "user", 1000))
+    .build();
 
 client.raw().send(request, BulkDeleteResponse.class).get();
 ```
@@ -100,7 +105,8 @@ RawRequestBuilder.builder("GET", "/stores/{store_id}/items")
     .pathParam("store_id", storeId)
     .queryParam("page", "1")
     .queryParam("limit", "50")
-    .queryParam("sort", "created_at");
+    .queryParam("sort", "created_at")
+    .build();
 ```
 
 ### Custom Headers
@@ -108,7 +114,8 @@ RawRequestBuilder.builder("GET", "/stores/{store_id}/items")
 RawRequestBuilder.builder("POST", "/stores/{store_id}/action")
     .header("X-Request-ID", UUID.randomUUID().toString())
     .header("X-Idempotency-Key", "key-123")
-    .body(data);
+    .body(data)
+    .build();
 ```
 
 ### Error Handling
@@ -125,29 +132,34 @@ client.raw().send(request, ResponseType.class)
 
 ### Map as Request Body
 ```java
-.body(Map.of(
-    "setting", "value",
-    "enabled", true,
-    "threshold", 100,
-    "options", List.of("opt1", "opt2")
-))
+RawRequestBuilder.builder("POST", "/stores/{store_id}/settings")
+    .pathParam("store_id", storeId)
+    .body(Map.of(
+        "setting", "value",
+        "enabled", true,
+        "threshold", 100,
+        "options", List.of("opt1", "opt2")
+    ))
+    .build();
 ```
 
 ## Notes
 
 - Path/query parameters are URL-encoded automatically
 - Authentication tokens injected from client config
-- Retries on 429, 5xx errors
 - `{store_id}` auto-replaced if not provided via `.pathParam()`
 
 ## Migration to Typed Methods
 
+When SDK adds typed methods for an endpoint, you can migrate from Raw API:
+
 ```java
 // Raw API
-client.raw().send(
-    RawRequestBuilder.builder("POST", "/stores/{store_id}/check").body(req),
-    CheckResponse.class
-).get();
+RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/check")
+    .body(req)
+    .build();
+    
+client.raw().send(request, CheckResponse.class).get();
 
 // Typed SDK (when available)
 client.check(req).get();
diff --git a/examples/raw-api/README.md b/examples/raw-api/README.md
index 93695864..16178f44 100644
--- a/examples/raw-api/README.md
+++ b/examples/raw-api/README.md
@@ -61,7 +61,8 @@ RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id
     .queryParam("page_size", "20")
     .queryParam("continuation_token", "eyJwayI6...")
     .body(requestBody)
-    .header("X-Custom-Header", "value");
+    .header("X-Custom-Header", "value")
+    .build();
 ```
 
 ### Response Handling
diff --git a/examples/raw-api/src/main/java/dev/openfga/sdk/example/RawApiExample.java b/examples/raw-api/src/main/java/dev/openfga/sdk/example/RawApiExample.java
index f9f6b69e..dfbbd034 100644
--- a/examples/raw-api/src/main/java/dev/openfga/sdk/example/RawApiExample.java
+++ b/examples/raw-api/src/main/java/dev/openfga/sdk/example/RawApiExample.java
@@ -63,7 +63,7 @@ public static void main(String[] args) throws Exception {
     private static String listStoresExample(OpenFgaClient fgaClient) {
         try {
             // Build the raw request for GET /stores
-            RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores");
+            RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores").build();
 
             // Execute with typed response
             var response = fgaClient
@@ -102,7 +102,8 @@ private static String listStoresExample(OpenFgaClient fgaClient) {
     private static String createStoreForExamples(OpenFgaClient fgaClient) throws Exception {
         String storeName = "raw-api-example-" + UUID.randomUUID().toString().substring(0, 8);
         RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores")
-                .body(Map.of("name", storeName));
+                .body(Map.of("name", storeName))
+                .build();
 
         // Use typed response instead of manual JSON parsing
         var response = fgaClient.raw().send(request, CreateStoreResponse.class).get();
@@ -116,7 +117,8 @@ private static String createStoreForExamples(OpenFgaClient fgaClient) throws Exc
     private static void getStoreRawJsonExample(OpenFgaClient fgaClient, String storeId) {
         try {
             RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}")
-                    .pathParam("store_id", storeId);
+                    .pathParam("store_id", storeId)
+                    .build();
 
             // Execute and get raw JSON string
             var response = fgaClient.raw().send(request).get();
@@ -136,7 +138,8 @@ private static void getStoreRawJsonExample(OpenFgaClient fgaClient, String store
     private static void listStoresWithPaginationExample(OpenFgaClient fgaClient) {
         try {
             RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores")
-                    .queryParam("page_size", "2");
+                    .queryParam("page_size", "2")
+                    .build();
 
             var response = fgaClient
                     .raw()
@@ -167,7 +170,8 @@ private static void createStoreWithHeadersExample(OpenFgaClient fgaClient) {
             RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores")
                     .header("X-Example-Header", "custom-value")
                     .header("X-Request-ID", "req-" + UUID.randomUUID())
-                    .body(Map.of("name", storeName));
+                    .body(Map.of("name", storeName))
+                    .build();
 
             var response = fgaClient.raw().send(request).get();
 
@@ -190,7 +194,8 @@ private static void errorHandlingExample(OpenFgaClient fgaClient) {
         try {
             // Try to get a non-existent store
             RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}")
-                    .pathParam("store_id", "01ZZZZZZZZZZZZZZZZZZZZZZZ9");
+                    .pathParam("store_id", "01ZZZZZZZZZZZZZZZZZZZZZZZ9")
+                    .build();
 
             var response = fgaClient.raw().send(request).get();
 
diff --git a/src/main/java/dev/openfga/sdk/api/client/RawApi.java b/src/main/java/dev/openfga/sdk/api/client/RawApi.java
index 2e5424c2..be424b49 100644
--- a/src/main/java/dev/openfga/sdk/api/client/RawApi.java
+++ b/src/main/java/dev/openfga/sdk/api/client/RawApi.java
@@ -16,7 +16,8 @@
  * <pre>{@code
  * RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/endpoint")
  *     .pathParam("store_id", storeId)
- *     .body(requestData);
+ *     .body(requestData)
+ *     .build();
  *
  * // Typed response
  * ApiResponse<ResponseType> response = client.raw().send(request, ResponseType.class).get();
diff --git a/src/main/java/dev/openfga/sdk/api/client/RawRequestBuilder.java b/src/main/java/dev/openfga/sdk/api/client/RawRequestBuilder.java
index 2dc2ef08..709b2c09 100644
--- a/src/main/java/dev/openfga/sdk/api/client/RawRequestBuilder.java
+++ b/src/main/java/dev/openfga/sdk/api/client/RawRequestBuilder.java
@@ -14,7 +14,8 @@
  * RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/endpoint")
  *     .pathParam("store_id", storeId)
  *     .queryParam("limit", "50")
- *     .body(requestObject);
+ *     .body(requestObject)
+ *     .build();
  * }</pre>
  */
 public class RawRequestBuilder {
@@ -114,6 +115,18 @@ public RawRequestBuilder body(Object body) {
         this.body = body;
         return this;
     }
+    /**
+     * Builds and returns the request for use with the Raw API.
+     * This method must be called to complete request construction.
+     *
+     * <p>This is required for consistency with other OpenFGA SDKs (e.g., Go SDK)
+     * and follows the standard builder pattern.</p>
+     *
+     * @return This builder instance (ready to be passed to {@link RawApi#send})
+     */
+    public RawRequestBuilder build() {
+        return this;
+    }
 
     String getMethod() {
         return method;
diff --git a/src/test-integration/java/dev/openfga/sdk/api/client/RawApiIntegrationTest.java b/src/test-integration/java/dev/openfga/sdk/api/client/RawApiIntegrationTest.java
index d738d68b..239b78f7 100644
--- a/src/test-integration/java/dev/openfga/sdk/api/client/RawApiIntegrationTest.java
+++ b/src/test-integration/java/dev/openfga/sdk/api/client/RawApiIntegrationTest.java
@@ -50,7 +50,7 @@ public void rawRequest_listStores() throws Exception {
         createStoreUsingRawRequest(storeName);
 
         // Use raw API to list stores (equivalent to GET /stores)
-        RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores");
+        RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores").build();
 
         ApiResponse<ListStoresResponse> response =
                 fga.raw().send(request, ListStoresResponse.class).get();
@@ -83,7 +83,8 @@ public void rawRequest_createStore_typedResponse() throws Exception {
         requestBody.put("name", storeName);
 
         // Use raw API to create store (equivalent to POST /stores)
-        RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores").body(requestBody);
+        RawRequestBuilder request =
+                RawRequestBuilder.builder("POST", "/stores").body(requestBody).build();
 
         ApiResponse<CreateStoreResponse> response =
                 fga.raw().send(request, CreateStoreResponse.class).get();
@@ -112,7 +113,8 @@ public void rawRequest_createStore_rawJsonResponse() throws Exception {
         requestBody.put("name", storeName);
 
         // Use raw API to create store and get raw JSON response
-        RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores").body(requestBody);
+        RawRequestBuilder request =
+                RawRequestBuilder.builder("POST", "/stores").body(requestBody).build();
 
         ApiResponse<String> response = fga.raw().send(request).get();
 
@@ -142,8 +144,9 @@ public void rawRequest_getStore_withPathParams() throws Exception {
         String storeId = createStoreUsingRawRequest(storeName);
 
         // Use raw API to get store details (equivalent to GET /stores/{store_id})
-        RawRequestBuilder request =
-                RawRequestBuilder.builder("GET", "/stores/{store_id}").pathParam("store_id", storeId);
+        RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}")
+                .pathParam("store_id", storeId)
+                .build();
 
         ApiResponse<GetStoreResponse> response =
                 fga.raw().send(request, GetStoreResponse.class).get();
@@ -170,7 +173,8 @@ public void rawRequest_automaticStoreIdReplacement() throws Exception {
         fga.setStoreId(storeId);
 
         // Use raw API WITHOUT providing store_id path param - it should be auto-replaced
-        RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}");
+        RawRequestBuilder request =
+                RawRequestBuilder.builder("GET", "/stores/{store_id}").build();
 
         ApiResponse<GetStoreResponse> response =
                 fga.raw().send(request, GetStoreResponse.class).get();
@@ -221,7 +225,8 @@ public void rawRequest_writeAuthorizationModel() throws Exception {
 
         // Use raw API to write authorization model
         RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/authorization-models")
-                .body(requestBody);
+                .body(requestBody)
+                .build();
 
         ApiResponse<WriteAuthorizationModelResponse> response =
                 fga.raw().send(request, WriteAuthorizationModelResponse.class).get();
@@ -252,7 +257,8 @@ public void rawRequest_readAuthorizationModels_withQueryParams() throws Exceptio
         // Use raw API to read authorization models with query parameters
         RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}/authorization-models")
                 .queryParam("page_size", "10")
-                .queryParam("continuation_token", "");
+                .queryParam("continuation_token", "")
+                .build();
 
         ApiResponse<ReadAuthorizationModelsResponse> response =
                 fga.raw().send(request, ReadAuthorizationModelsResponse.class).get();
@@ -295,16 +301,12 @@ public void rawRequest_check() throws Exception {
         tupleKey.put("object", "document:budget");
         checkBody.put("tuple_key", tupleKey);
 
-        RawRequestBuilder request =
-                RawRequestBuilder.builder("POST", "/stores/{store_id}/check").body(checkBody);
+        RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/check")
+                .body(checkBody)
+                .build();
 
         ApiResponse<CheckResponse> response =
                 fga.raw().send(request, CheckResponse.class).get();
-
-        // Verify response
-        assertNotNull(response);
-        assertEquals(200, response.getStatusCode());
-        assertNotNull(response.getData());
         assertTrue(response.getData().getAllowed(), "Alice should be allowed to read the document");
 
         System.out.println("✓ Successfully performed check using raw request");
@@ -325,7 +327,8 @@ public void rawRequest_withCustomHeaders() throws Exception {
         RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores")
                 .body(requestBody)
                 .header("X-Custom-Header", "custom-value")
-                .header("X-Request-ID", "test-123");
+                .header("X-Request-ID", "test-123")
+                .build();
 
         ApiResponse<CreateStoreResponse> response =
                 fga.raw().send(request, CreateStoreResponse.class).get();
@@ -343,8 +346,9 @@ public void rawRequest_withCustomHeaders() throws Exception {
     @Test
     public void rawRequest_errorHandling_notFound() throws Exception {
         // Try to get a non-existent store
-        RawRequestBuilder request =
-                RawRequestBuilder.builder("GET", "/stores/{store_id}").pathParam("store_id", "non-existent-store-id");
+        RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}")
+                .pathParam("store_id", "non-existent-store-id")
+                .build();
 
         // Should throw an exception
         try {
@@ -372,7 +376,9 @@ public void rawRequest_listStores_withPagination() throws Exception {
         }
 
         // Use raw API to list stores with pagination
-        RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores").queryParam("page_size", "2");
+        RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores")
+                .queryParam("page_size", "2")
+                .build();
 
         ApiResponse<ListStoresResponse> response =
                 fga.raw().send(request, ListStoresResponse.class).get();
@@ -396,7 +402,8 @@ private String createStoreUsingRawRequest(String storeName) throws Exception {
         Map<String, Object> requestBody = new HashMap<>();
         requestBody.put("name", storeName);
 
-        RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores").body(requestBody);
+        RawRequestBuilder request =
+                RawRequestBuilder.builder("POST", "/stores").body(requestBody).build();
 
         ApiResponse<CreateStoreResponse> response =
                 fga.raw().send(request, CreateStoreResponse.class).get();
@@ -431,7 +438,8 @@ private String writeSimpleAuthorizationModel(String storeId) throws Exception {
 
         RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/authorization-models")
                 .pathParam("store_id", storeId)
-                .body(requestBody);
+                .body(requestBody)
+                .build();
 
         ApiResponse<WriteAuthorizationModelResponse> response =
                 fga.raw().send(request, WriteAuthorizationModelResponse.class).get();
@@ -451,7 +459,8 @@ private void writeTupleUsingRawRequest(String storeId, String user, String relat
 
         RawRequestBuilder request = RawRequestBuilder.builder("POST", "/stores/{store_id}/write")
                 .pathParam("store_id", storeId)
-                .body(requestBody);
+                .body(requestBody)
+                .build();
 
         fga.raw().send(request, Object.class).get();
     }
diff --git a/src/test/java/dev/openfga/sdk/api/client/RawApiTest.java b/src/test/java/dev/openfga/sdk/api/client/RawApiTest.java
index f2e60833..cfddaa39 100644
--- a/src/test/java/dev/openfga/sdk/api/client/RawApiTest.java
+++ b/src/test/java/dev/openfga/sdk/api/client/RawApiTest.java
@@ -65,7 +65,8 @@ public void rawApi_canAccessViaClient() throws Exception {
 
     @Test
     public void rawRequestBuilder_canBuildBasicRequest() {
-        RawRequestBuilder builder = RawRequestBuilder.builder("GET", "/stores/{store_id}/test");
+        RawRequestBuilder builder =
+                RawRequestBuilder.builder("GET", "/stores/{store_id}/test").build();
 
         assertNotNull(builder);
         assertEquals("GET", builder.getMethod());
@@ -74,8 +75,9 @@ public void rawRequestBuilder_canBuildBasicRequest() {
 
     @Test
     public void rawRequestBuilder_canAddPathParameters() {
-        RawRequestBuilder builder =
-                RawRequestBuilder.builder("GET", "/stores/{store_id}/test").pathParam("store_id", "my-store");
+        RawRequestBuilder builder = RawRequestBuilder.builder("GET", "/stores/{store_id}/test")
+                .pathParam("store_id", "my-store")
+                .build();
 
         Map<String, String> pathParams = builder.getPathParams();
         assertEquals(1, pathParams.size());
@@ -86,7 +88,8 @@ public void rawRequestBuilder_canAddPathParameters() {
     public void rawRequestBuilder_canAddQueryParameters() {
         RawRequestBuilder builder = RawRequestBuilder.builder("GET", "/test")
                 .queryParam("page", "1")
-                .queryParam("limit", "10");
+                .queryParam("limit", "10")
+                .build();
 
         Map<String, String> queryParams = builder.getQueryParams();
         assertEquals(2, queryParams.size());
@@ -96,7 +99,9 @@ public void rawRequestBuilder_canAddQueryParameters() {
 
     @Test
     public void rawRequestBuilder_canAddHeaders() {
-        RawRequestBuilder builder = RawRequestBuilder.builder("GET", "/test").header("X-Custom-Header", "custom-value");
+        RawRequestBuilder builder = RawRequestBuilder.builder("GET", "/test")
+                .header("X-Custom-Header", "custom-value")
+                .build();
 
         Map<String, String> headers = builder.getHeaders();
         assertEquals(1, headers.size());
@@ -108,7 +113,8 @@ public void rawRequestBuilder_canAddBody() {
         Map<String, Object> body = new HashMap<>();
         body.put("key", "value");
 
-        RawRequestBuilder builder = RawRequestBuilder.builder("POST", "/test").body(body);
+        RawRequestBuilder builder =
+                RawRequestBuilder.builder("POST", "/test").body(body).build();
 
         assertTrue(builder.hasBody());
         assertEquals(body, builder.getBody());
@@ -165,8 +171,9 @@ public void rawApi_canSendGetRequestWithTypedResponse() throws Exception {
 
         // Build and send request
         OpenFgaClient client = createClient();
-        RawRequestBuilder request =
-                RawRequestBuilder.builder("GET", EXPERIMENTAL_ENDPOINT).pathParam("store_id", DEFAULT_STORE_ID);
+        RawRequestBuilder request = RawRequestBuilder.builder("GET", EXPERIMENTAL_ENDPOINT)
+                .pathParam("store_id", DEFAULT_STORE_ID)
+                .build();
 
         ApiResponse<ExperimentalResponse> response =
                 client.raw().send(request, ExperimentalResponse.class).get();
@@ -201,7 +208,8 @@ public void rawApi_canSendPostRequestWithBody() throws Exception {
 
         RawRequestBuilder request = RawRequestBuilder.builder("POST", EXPERIMENTAL_ENDPOINT)
                 .pathParam("store_id", DEFAULT_STORE_ID)
-                .body(requestBody);
+                .body(requestBody)
+                .build();
 
         ApiResponse<ExperimentalResponse> response =
                 client.raw().send(request, ExperimentalResponse.class).get();
@@ -226,13 +234,13 @@ public void rawApi_canSendRequestWithQueryParameters() throws Exception {
                         .withStatus(200)
                         .withHeader("Content-Type", "application/json")
                         .withBody("{\"success\":true,\"count\":10,\"message\":\"Success\"}")));
-
         // Build and send request
         OpenFgaClient client = createClient();
         RawRequestBuilder request = RawRequestBuilder.builder("GET", EXPERIMENTAL_ENDPOINT)
                 .pathParam("store_id", DEFAULT_STORE_ID)
                 .queryParam("force", "true")
-                .queryParam("limit", "10");
+                .queryParam("limit", "10")
+                .build();
 
         ApiResponse<ExperimentalResponse> response =
                 client.raw().send(request, ExperimentalResponse.class).get();
@@ -259,8 +267,9 @@ public void rawApi_canReturnRawJsonString() throws Exception {
 
         // Build and send request
         OpenFgaClient client = createClient();
-        RawRequestBuilder request =
-                RawRequestBuilder.builder("GET", EXPERIMENTAL_ENDPOINT).pathParam("store_id", DEFAULT_STORE_ID);
+        RawRequestBuilder request = RawRequestBuilder.builder("GET", EXPERIMENTAL_ENDPOINT)
+                .pathParam("store_id", DEFAULT_STORE_ID)
+                .build();
 
         ApiResponse<String> response = client.raw().send(request).get();
 
@@ -280,7 +289,8 @@ public void rawApi_handlesHttpErrors() throws Exception {
         // Build and send request
         OpenFgaClient client = createClient();
         RawRequestBuilder request = RawRequestBuilder.builder("GET", "/stores/{store_id}/non-existent")
-                .pathParam("store_id", DEFAULT_STORE_ID);
+                .pathParam("store_id", DEFAULT_STORE_ID)
+                .build();
 
         // Verify exception is thrown
         ExecutionException exception = assertThrows(
@@ -297,8 +307,9 @@ public void rawApi_handlesServerErrors() throws Exception {
 
         // Build and send request
         OpenFgaClient client = createClient();
-        RawRequestBuilder request =
-                RawRequestBuilder.builder("GET", EXPERIMENTAL_ENDPOINT).pathParam("store_id", DEFAULT_STORE_ID);
+        RawRequestBuilder request = RawRequestBuilder.builder("GET", EXPERIMENTAL_ENDPOINT)
+                .pathParam("store_id", DEFAULT_STORE_ID)
+                .build();
 
         // Verify exception is thrown
         ExecutionException exception = assertThrows(
@@ -321,7 +332,8 @@ public void rawApi_supportsCustomHeaders() throws Exception {
         RawRequestBuilder request = RawRequestBuilder.builder("GET", EXPERIMENTAL_ENDPOINT)
                 .pathParam("store_id", DEFAULT_STORE_ID)
                 .header("X-Custom-Header", "custom-value")
-                .header("X-Request-ID", "12345");
+                .header("X-Request-ID", "12345")
+                .build();
 
         ApiResponse<ExperimentalResponse> response =
                 client.raw().send(request, ExperimentalResponse.class).get();
@@ -350,8 +362,9 @@ public void rawApi_encodesPathParameters() throws Exception {
         ClientConfiguration config = new ClientConfiguration().apiUrl(fgaApiUrl).storeId("store with spaces");
         OpenFgaClient client = new OpenFgaClient(config);
 
-        RawRequestBuilder request =
-                RawRequestBuilder.builder("GET", EXPERIMENTAL_ENDPOINT).pathParam("store_id", "store with spaces");
+        RawRequestBuilder request = RawRequestBuilder.builder("GET", EXPERIMENTAL_ENDPOINT)
+                .pathParam("store_id", "store with spaces")
+                .build();
 
         ApiResponse<ExperimentalResponse> response =
                 client.raw().send(request, ExperimentalResponse.class).get();
@@ -373,7 +386,7 @@ public void rawApi_throwsExceptionForNullBuilder() throws Exception {
     @Test
     public void rawApi_throwsExceptionForNullResponseType() throws Exception {
         OpenFgaClient client = createClient();
-        RawRequestBuilder request = RawRequestBuilder.builder("GET", "/test");
+        RawRequestBuilder request = RawRequestBuilder.builder("GET", "/test").build();
         assertThrows(IllegalArgumentException.class, () -> client.raw().send(request, null));
     }
 }