### Async grant token example

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/auth.md

Asynchronous variant of the grant token example using AsyncDeepgramClient. Sets a TTL of 600 seconds and prints the access token upon completion.

```java
AsyncDeepgramClient asyncClient = AsyncDeepgramClient.builder().build();
asyncClient.auth().v1().tokens().grant(GrantV1Request.builder().ttlSeconds(600.0).build())
        .thenAccept(token -> System.out.println(token.getAccessToken()));
```

--------------------------------

### Manage projects and API keys with Deepgram Java SDK

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

Manage projects, API keys, members, usage, and billing with the Deepgram Java SDK. The example shows how to list projects, list API keys for a project, and get usage statistics.

```java
import com.deepgram.DeepgramClient;

DeepgramClient client = DeepgramClient.builder().build();

// List projects
var projects = client.manage().v1().projects().list();

// List API keys for a project
var keys = client.manage().v1().projects().keys().list("project-id");

// Get usage statistics
var usage = client.manage().v1().projects().usage().get("project-id");
```

--------------------------------

### Synchronous grant token example

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/auth.md

Synchronous example of granting a temporary token with a TTL of 3600 seconds. Prints the access token and the actual expiration duration if present.

```java
DeepgramClient client = DeepgramClient.builder().build();

GrantV1Response granted = client.auth().v1().tokens().grant(
        GrantV1Request.builder()
                .ttlSeconds(3600.0)
                .build());
System.out.println(granted.getAccessToken());
System.out.println(granted.getExpiresIn()); // duration in seconds, if present
```

--------------------------------

### Async transcription example

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/deepgram-client.md

Shows how to build an AsyncDeepgramClient, submit a transcription request for a URL, and handle the result asynchronously with a CompletableFuture callback.

```java
AsyncDeepgramClient asyncClient = AsyncDeepgramClient.builder().build();
CompletableFuture<MediaTranscribeResponse> future = asyncClient.listen().v1().media()
        .transcribeUrl(ListenV1RequestUrl.builder()
                .url("https://static.deepgram.com/examples/Bueller-Life-moves-pretty-fast.wav")
                .build());
future.thenAccept(result -> System.out.println("Transcription complete!"));
```

--------------------------------

### GET /v1/models

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/endpoints.md

Lists all available models.

```APIDOC
## GET /v1/models

### Description
Lists all available models.

### Method
GET

### Endpoint
/v1/models

### Parameters
#### Query Parameters
- **include_outdated** (boolean) - Optional - Whether to include outdated models.

### Response
#### Success Response (200)
- **ListModelsV1Response** - The response object.

```

--------------------------------

### Initialize ReadV1Request with Text

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/read.md

Example of creating a ReadV1Request instance using the ReadV1RequestText builder.

```java
ReadV1Request requestBody = ReadV1Request.of(
        ReadV1RequestText.builder()
                .text("Deepgram's speech recognition is incredibly accurate and fast.")
                .build());
```

--------------------------------

### GET /v1/projects/{project_id}/keys

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/manage.md

Lists API keys for a project.

```APIDOC
## GET /v1/projects/{project_id}/keys

### Description
Lists API keys for a project.

### Method
GET

### Endpoint
/v1/projects/{project_id}/keys

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.

### Response
#### Success Response (200)
- **ListProjectKeysV1Response** - The response containing the list of keys.

```

--------------------------------

### GET /v1/models/{model_id}

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/endpoints.md

Retrieves a specific model.

```APIDOC
## GET /v1/models/{model_id}

### Description
Retrieves a specific model.

### Method
GET

### Endpoint
/v1/models/{model_id}

### Parameters
#### Path Parameters
- **model_id** (string) - Required - The ID of the model.

### Response
#### Success Response (200)
- **GetModelV1Response** - The response object.

```

--------------------------------

### GET /v1/projects/agents/{project_id}

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/voiceagent.md

Lists all agent configurations for a given project.

```APIDOC
## GET /v1/projects/agents/{project_id}

### Description
Lists all agent configurations for a given project.

### Method
GET

### Endpoint
/v1/projects/agents/{project_id}

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.

### Response
#### Success Response (200)
- **ListAgentConfigurationsV1Response** - The list of agent configurations.

### Response Example
```json
{
  "agent_configurations": []
}
```
```

--------------------------------

### ClientOptions.Builder retry tuning example

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/docs/Migrating-v0.7-to-v0.8.md

Configure optional client-level retry tuning on ClientOptions.Builder. All methods are optional and default to preserve prior behavior.

```java
DeepgramClient.builder()
    .apiKey("YOUR_API_KEY")
    // all optional; defaults preserve prior behavior
    .initialRetryDelayMillis(1000)
    .maxRetryDelayMillis(60000)
    .retryJitterFactor(0.2)
    .build();
```

--------------------------------

### GET /v1/projects

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/manage.md

Lists all projects accessible to the authenticated user. Returns a list of project summaries.

```APIDOC
## GET /v1/projects

### Description
Lists all projects accessible to the authenticated user.

### Method
GET

### Endpoint
/v1/projects

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - Maximum number of projects to return.
- **page** (integer) - Optional - Page number for pagination.

### Request Example
No request body required.

### Response
#### Success Response (200)
- **projects** (array) - List of project objects.

#### Response Example
{
  "projects": []
}
```

--------------------------------

### GET /v1/projects/{project_id}/agents

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/endpoints.md

Lists agent configurations for a project.

```APIDOC
## GET /v1/projects/{project_id}/agents

### Description
Lists agent configurations for a project.

### Method
GET

### Endpoint
/v1/projects/{project_id}/agents

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.

### Response
#### Success Response (200)
- **ListAgentConfigurationsV1Response** - The response object.

```

--------------------------------

### GET /v1/projects/{project_id}/agent-variables

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/endpoints.md

Lists agent variables for a project.

```APIDOC
## GET /v1/projects/{project_id}/agent-variables

### Description
Lists agent variables for a project.

### Method
GET

### Endpoint
/v1/projects/{project_id}/agent-variables

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.

### Response
#### Success Response (200)
- **ListAgentVariablesV1Response** - The response object.

```

--------------------------------

### GET /v1/projects/{project_id}/self-hosted/distribution/credentials

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/endpoints.md

Lists distribution credentials for a self-hosted project.

```APIDOC
## GET /v1/projects/{project_id}/self-hosted/distribution/credentials

### Description
Lists distribution credentials for a self-hosted project.

### Method
GET

### Endpoint
/v1/projects/{project_id}/self-hosted/distribution/credentials

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.

### Response
#### Success Response (200)
- **ListProjectDistributionCredentialsV1Response** - The response object.

#### Response Example
```json
{}
```
```

--------------------------------

### GET /v1/projects/{project_id}/agents/{agent_id}

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/endpoints.md

Retrieves a specific agent configuration.

```APIDOC
## GET /v1/projects/{project_id}/agents/{agent_id}

### Description
Retrieves a specific agent configuration.

### Method
GET

### Endpoint
/v1/projects/{project_id}/agents/{agent_id}

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.
- **agent_id** (string) - Required - The ID of the agent.

### Response
#### Success Response (200)
- **AgentConfigurationV1** - The response object.

```

--------------------------------

### GET /v1/projects/{project_id}/agent-variables/{variable_id}

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/endpoints.md

Retrieves a specific agent variable.

```APIDOC
## GET /v1/projects/{project_id}/agent-variables/{variable_id}

### Description
Retrieves a specific agent variable.

### Method
GET

### Endpoint
/v1/projects/{project_id}/agent-variables/{variable_id}

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.
- **variable_id** (string) - Required - The ID of the variable.

### Response
#### Success Response (200)
- **AgentVariableV1** - The response object.

```

--------------------------------

### GET /v1/projects/{project_id}/self-hosted/distribution/credentials/{credentials_id}

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/endpoints.md

Retrieves a specific distribution credential by its ID.

```APIDOC
## GET /v1/projects/{project_id}/self-hosted/distribution/credentials/{credentials_id}

### Description
Retrieves a specific distribution credential by its ID.

### Method
GET

### Endpoint
/v1/projects/{project_id}/self-hosted/distribution/credentials/{credentials_id}

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.
- **credentials_id** (string) - Required - The ID of the credentials.

### Response
#### Success Response (200)
- **GetProjectDistributionCredentialsV1Response** - The response object.

#### Response Example
```json
{}
```
```

--------------------------------

### Manage API example: projects, keys, and usage

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/manage.md

Demonstrates listing projects, listing API keys for the first project, and retrieving usage data for a date range. All methods throw `DeepgramHttpException` (5xx etc.) and `BadRequestError` (400) — see `errors.md`.

```java
var manage = client.manage().v1();

// List projects
var projects = manage.projects().list();
projects.getProjects().ifPresent(list ->
        list.forEach(p -> System.out.println(p.getProjectId() + " " + p.getName())));

// List API keys for the first project
projects.getProjects().ifPresent(ps -> ps.stream().findFirst().ifPresent(p -> {
    manage.projects().keys().list(p.getProjectId().orElse("")).getApiKeys()
            .ifPresent(keys -> keys.forEach(k -> k.getApiKey().ifPresent(
                    apiKey -> System.out.println(apiKey.getApiKeyId()))));
}));

// Usage for a date range
var usage = manage.projects().usage().get(projectId, UsageGetRequest.builder()
        .start("2024-01-01")
        .end("2024-02-01")
        .build());
usage.getResolution().ifPresent(r -> System.out.println(r.getUnits()));

// Hourly usage breakdown carries the per-hour results list
UsageBreakdownV1Response breakdown = manage.projects().usage().breakdown().get(projectId);
breakdown.getResults().forEach(r -> System.out.println(r.getStart() + " total_hours=" + r.getTotalHours()));
```

--------------------------------

### RequestsClient list and get operations

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/manage.md

Shows how to use RequestsClient to list and get requests for a project. The list method returns all requests, and the get method retrieves a specific request by ID.

```java
RequestsClient reqs = client.manage().v1().projects().requests();
reqs.list("projectId");                      // GET /v1/projects/{project_id}/requests
reqs.get("projectId", "requestId");          // GET /v1/projects/{project_id}/requests/{request_id}
```

--------------------------------

### Example — transcribe from URL

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/listen-rest.md

Builds a ListenV1RequestUrl with a public audio URL and transcription options, then calls transcribeUrl on the media client. Uses a visitor to handle both the normal response and the accepted (callback) response.

```java
DeepgramClient client = DeepgramClient.builder().build();

MediaTranscribeResponse result = client.listen().v1().media().transcribeUrl(
        ListenV1RequestUrl.builder()
                .url("https://static.deepgram.com/examples/Bueller-Life-moves-pretty-fast.wav")
                .smartFormat(true)
                .punctuate(true)
                .model(MediaTranscribeRequestModel.NOVA3)  // see request types below
                .build());

result.visit(new MediaTranscribeResponse.Visitor<Void>() {
    @Override public Void visit(ListenV1Response response) {
        response.getResults().getChannels().get(0).getAlternatives().ifPresent(alts ->
                alts.get(0).getTranscript().ifPresent(System.out::println));
        return null;
    }
    @Override public Void visit(ListenV1AcceptedResponse accepted) {
        System.out.println("accepted (callback mode)");
        return null;
    }
});
```

--------------------------------

### ModelsClient list and get operations

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/manage.md

Shows how to use ModelsClient to list and get models for a project. The list method returns all models, and the get method retrieves a specific model by ID.

```java
ModelsClient pmodels = client.manage().v1().projects().models();
pmodels.list("projectId");              // GET /v1/projects/{project_id}/models
pmodels.get("projectId", "modelId");    // GET /v1/projects/{project_id}/models/{model_id}
```

--------------------------------

### Listen V1 WebSocket implementation

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/listen-v1-websocket.md

Demonstrates initializing the client, setting up event listeners for results, errors, and disconnection, and managing the lifecycle of a WebSocket stream.

```java
DeepgramClient client = DeepgramClient.builder().build();

try (V1WebSocketClient ws = client.listen().v1().v1WebSocket()) {
    ws.onResults(results -> results.getChannel().getAlternatives().stream()
            .findFirst().ifPresent(alt ->
                    System.out.println("Transcript: " + alt.getTranscript())));
    ws.onError(err -> System.err.println("Error: " + err.getMessage()));
    ws.onDisconnected(reason -> System.out.println("Closed: " + reason.getCode()));

    ws.connect(V1ConnectOptions.builder()
            .model(ListenV1Model.NOVA3)
            .punctuate(true)
            .interimResults(true)
            .build()).get(10, TimeUnit.SECONDS);

    ws.sendMedia(ByteString.of(audioBytes)).get(5, TimeUnit.SECONDS);
    ws.sendFinalize(ListenV1Finalize.builder().type(ListenV1FinalizeType.FINALIZE).build()).get(5, TimeUnit.SECONDS);

    Thread.sleep(2000);
    ws.sendCloseStream(ListenV1CloseStream.builder().type(ListenV1CloseStreamType.CLOSE_STREAM).build())
            .get(5, TimeUnit.SECONDS);
}  // close() → disconnect()
```

--------------------------------

### Global models: list and get models

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/manage.md

Shows how to access the models client and list or get models. The list method returns a `ListModelsV1Response` containing `stt_models` and `tts_models`, while get returns a `GetModelV1Response`.

```java
ModelsClient models = client.manage().v1().models();
models.list();                                    // GET /v1/models
models.list(ModelsListRequest.builder().includeOutdated(false).build());
models.get("modelId");                            // GET /v1/models/{model_id}
```

--------------------------------

### ConfigurationsClient CRUD methods

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/voiceagent.md

Client for CRUD operations on agent configurations. Methods map to HTTP routes: list (GET), create (POST), get (GET), update (PUT), delete (DELETE). The delete method returns an arbitrary JSON body as a Map.

```java
public class ConfigurationsClient {
    public ConfigurationsClient(ClientOptions clientOptions);
    public RawConfigurationsClient withRawResponse();
    public ListAgentConfigurationsV1Response list(String projectId);
    public ListAgentConfigurationsV1Response list(String projectId, RequestOptions requestOptions);
    public CreateAgentConfigurationV1Response create(String projectId, CreateAgentConfigurationV1Request request);
    public CreateAgentConfigurationV1Response create(String projectId, CreateAgentConfigurationV1Request request, RequestOptions requestOptions);
    public AgentConfigurationV1 get(String projectId, String agentId);
    public AgentConfigurationV1 get(String projectId, String agentId, RequestOptions requestOptions);
    public AgentConfigurationV1 update(String projectId, String agentId, UpdateAgentMetadataV1Request request);
    public AgentConfigurationV1 update(String projectId, String agentId, UpdateAgentMetadataV1Request request, RequestOptions requestOptions);
    public Map<String, Object> delete(String projectId, String agentId);
    public Map<String, Object> delete(String projectId, String agentId, RequestOptions requestOptions);
}
```

--------------------------------

### V1WebSocketClient connection and send methods

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/agent.md

Declares the V1WebSocketClient class with its constructor and all connection and send methods. connect() takes no options object; use the onWelcome handler for session setup. sendMedia accepts binary audio as a ByteString.

```java
public class V1WebSocketClient implements AutoCloseable {
    public V1WebSocketClient(ClientOptions clientOptions);
    public CompletableFuture<Void> connect();                     // no options object — use onWelcome
    public void disconnect();
    public WebSocketReadyState getReadyState();
    public CompletableFuture<Void> sendSettings(AgentV1Settings message);
    public CompletableFuture<Void> sendUpdateListen(AgentV1UpdateListen message);
    public CompletableFuture<Void> sendUpdateThink(AgentV1UpdateThink message);
    public CompletableFuture<Void> sendUpdateSpeak(AgentV1UpdateSpeak message);
    public CompletableFuture<Void> sendInjectUserMessage(AgentV1InjectUserMessage message);
    public CompletableFuture<Void> sendInjectAgentMessage(AgentV1InjectAgentMessage message);
    public CompletableFuture<Void> sendFunctionCallResponse(AgentV1SendFunctionCallResponse message);
    public CompletableFuture<Void> sendKeepAlive(AgentV1KeepAlive message);
    public CompletableFuture<Void> sendUpdatePrompt(AgentV1UpdatePrompt message);
    public CompletableFuture<Void> sendForceEndTurn(AgentV1ForceEndTurn message);
    public CompletableFuture<Void> sendMedia(ByteString message);
    @Override public void close();
}
```

--------------------------------

### Build AgentV1Settings with audio and agent context

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/agent.md

Builds an AgentV1Settings instance with required audio and agent stages. The agent uses an AgentV1SettingsAgentContext with a think provider (OpenAI GPT-4o mini) and a greeting. All builder fields are optional except audio and agent.

```java
AgentV1Settings settings = AgentV1Settings.builder()
        .audio(AgentV1SettingsAudio.builder().build())
        .agent(AgentV1SettingsAgent.of(
                AgentV1SettingsAgentContext.builder()
                        .think(AgentV1SettingsAgentContextThink.of(
                                ThinkSettingsV1.builder()
                                        .provider(ThinkSettingsV1Provider.openAi(
                                                OpenAiThinkProvider.builder()
                                                        .model(OpenAiThinkProviderModel.GPT4O_MINI)
                                                        .build()))
                                        .prompt("You are a helpful voice assistant. Keep responses brief.")
                                        .build()))
                        .greeting("Hello! How can I help you today?")
                        .build()))
        .build();
```

--------------------------------

### Example: Building a DeepgramClient with accessToken and custom options

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/deepgram-client.md

Demonstrates building a DeepgramClient using the builder pattern with an access token, session ID, timeout, max retries, and a custom header. The accessToken takes precedence over apiKey, and the sessionId is sent as x-deepgram-session-id.

```java
DeepgramClient client = DeepgramClient.builder()
        .accessToken("jwt")
        .sessionId("session-123")
        .timeout(30)
        .maxRetries(3)
        .addHeader("X-Custom-Header", "custom-value")
        .build();
```

--------------------------------

### Java example: Connect to V2 WebSocket, send audio, configure, and close

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/listen-v2-websocket.md

Shows idiomatic usage of the Deepgram Java SDK: builds a DeepgramClient, creates a V2WebSocketClient, sets up event handlers, connects with V2ConnectOptions, sends audio chunks, sends a configure request to change numerals, and closes the stream. All send methods return CompletableFuture; failures surface as exceptional completion (ExecutionException via .get()), and connection errors also invoke the onError handler. sendMedia fails with IllegalStateException if the socket is not connected or not OPEN.

```java
try (DeepgramClient client = DeepgramClient.builder().build();
     V2WebSocketClient fluxWs = client.listen().v2().v2WebSocket()) {

    fluxWs.onConnected(connected -> System.out.println("request_id=" + connected.getRequestId()));
    fluxWs.onConfigureSuccess(success -> System.out.println("configured: " + success.getRequestId()));
    fluxWs.onConfigureFailure(failure -> System.out.println("rejected: " + failure.getCode() + " " + failure.getDescription()));
    fluxWs.onError(err -> System.err.println("Error: " + err.getMessage()));

    fluxWs.connect(V2ConnectOptions.builder()
            .model(ListenV2Model.FLUX_GENERAL_EN)
            .numerals(ListenV2Numerals.FALSE)
            .build())
            .get(10, TimeUnit.SECONDS);

    for (byte[] chunk : audioChunks) {
        fluxWs.sendMedia(ByteString.of(chunk)).get(5, TimeUnit.SECONDS);
    }

    // change numerals for future turns without reconnecting
    fluxWs.sendConfigure(ListenV2Configure.builder().numerals(true).build()).get(10, TimeUnit.SECONDS);

    fluxWs.sendCloseStream(ListenV2CloseStream.builder()
            .type(ListenV2CloseStreamType.CLOSE_STREAM)
            .build()).get(5, TimeUnit.SECONDS);
}
```

--------------------------------

### Manage API: projects, keys, members, usage, models

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/README.md

Shows the main entry points for the Manage (Project Management) API, covering projects, API keys, members, usage, and models.

```java
// Projects
client.manage().v1().projects().list()                 // List all projects
client.manage().v1().projects().get(projectId)         // Get project details
client.manage().v1().projects().update(projectId, req) // Update project
client.manage().v1().projects().delete(projectId)      // Delete project

// API Keys
client.manage().v1().projects().keys().list(projectId) // List API keys
client.manage().v1().projects().keys().create(id, req) // Create new key
client.manage().v1().projects().keys().get(id, keyId)  // Get key details
client.manage().v1().projects().keys().delete(id, key) // Delete key

// Members
client.manage().v1().projects().members().list(id)     // List members
client.manage().v1().projects().members().delete(p, m) // Remove member

// Usage
client.manage().v1().projects().usage().get(projectId) // Get usage summary

// Models
client.manage().v1().projects().models().list(id)      // List project models
client.manage().v1().models().list()                   // List all models
```

--------------------------------

### Streaming TTS WebSocket example

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/speak-v1-websocket.md

Complete example of streaming text-to-speech over WebSocket: connects with V1ConnectOptions (AURA_ZEUS_EN model), sends text, flushes, waits, writes the received audio to output.wav, then closes. Uses the V1WebSocketClient from client.speak().v1().v1WebSocket().

```java
DeepgramClient client = DeepgramClient.builder().build();
ByteArrayOutputStream audioBuffer = new ByteArrayOutputStream();

V1WebSocketClient ttsWs = client.speak().v1().v1WebSocket();
ttsWs.onSpeakV1Audio(audioData -> audioBuffer.writeBytes(audioData.toByteArray()));
ttsWs.onFlushed(flushed -> System.out.println("flushed"));
ttsWs.onWarning(warning -> System.err.println("warn: " + warning.getMessage()));
ttsWs.onError(err -> System.err.println("Error: " + err.getMessage()));

ttsWs.connect(V1ConnectOptions.builder()
        .model(AudioGenerateRequestModel.AURA_ZEUS_EN)
        .build())
        .get(10, TimeUnit.SECONDS);

ttsWs.sendText(SpeakV1Text.builder().text("Hello, this is streamed text-to-speech.").build())
        .get(5, TimeUnit.SECONDS);
ttsWs.sendFlush(SpeakV1Flush.builder().type(SpeakV1FlushType.FLUSH).build())
        .get(5, TimeUnit.SECONDS);

Thread.sleep(2000);
Files.write(Path.of("output.wav"), audioBuffer.toByteArray());

ttsWs.sendClose(SpeakV1Close.builder().type(SpeakV1CloseType.CLOSE).build()).get(5, TimeUnit.SECONDS);
ttsWs.close();
```

--------------------------------

### Verify the build

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/CONTRIBUTING.md

Verifies the build works, skipping tests and Spotless checks.

```bash
./gradlew build -x test -x spotlessCheck
```

--------------------------------

### GET /v1/projects/{project_id}/requests

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/manage.md

Lists requests for a project.

```APIDOC
## GET /v1/projects/{project_id}/requests

### Description
Lists requests for a project.

### Method
GET

### Endpoint
/v1/projects/{project_id}/requests

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.

### Response
#### Success Response (200)
- **ListProjectRequestsV1Response** - The response containing the list of requests.

```

--------------------------------

### Barge-in example with V2WebSocketClient

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/speak-v2-websocket.md

Connects a V2WebSocketClient with the required model 'flux-alexis-en', configures speed, sends speech, and interrupts playback after a 1.2-second offset. Uses onConfigureSuccess, onConfigureFailure, and onSpeechInterrupted callbacks.

```java
V2WebSocketClient ttsWs = client.speak().v2().v2WebSocket();

ttsWs.onConfigureSuccess(success -> System.out.println("configured: " + success.getApplied()));
ttsWs.onConfigureFailure(failure ->
        System.out.println("rejected [" + failure.getCode() + "]: " + failure.getDescription()));

ttsWs.onSpeechInterrupted(interrupted -> {
    interrupted.getTextSpoken().ifPresent(spoken -> System.out.println("spoken: " + spoken));
    interrupted.getTextRemaining().ifPresent(remaining -> System.out.println("remaining: " + remaining));
});

ttsWs.connect(V2ConnectOptions.builder().model("flux-alexis-en").build()).get(10, TimeUnit.SECONDS);

ttsWs.sendConfigure(SpeakV2Configure.builder().speed(1.05).build());
ttsWs.sendSpeak(SpeakV2Speak.builder().text("This is a longer sentence we can barge in on.").build());

// Stop playback after ~1.2s of audio has played (offset is cumulative from session start)
Thread.sleep(1200);
ttsWs.sendInterrupt(SpeakV2Interrupt.builder()
        .playbackOffset(SpeakV2InterruptPlaybackOffset.builder().value(1200).build())
        .build());

ttsWs.close();
```

--------------------------------

### Set up the pre-commit hook

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/CONTRIBUTING.md

Configures Git to use the project's pre-commit hooks.

```bash
git config core.hooksPath .githooks
```

--------------------------------

### GET /v1/projects/{project_id}/models

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/manage.md

Lists models for a project.

```APIDOC
## GET /v1/projects/{project_id}/models

### Description
Lists models for a project.

### Method
GET

### Endpoint
/v1/projects/{project_id}/models

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.

### Response
#### Success Response (200)
- **ListProjectModelsV1Response** - The response containing the list of models.

```

--------------------------------

### GET /v1/projects/{project_id}/invites

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/manage.md

Lists invites for a project.

```APIDOC
## GET /v1/projects/{project_id}/invites

### Description
Lists invites for a project.

### Method
GET

### Endpoint
/v1/projects/{project_id}/invites

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.

### Response
#### Success Response (200)
- **ListProjectInvitesV1Response** - The response containing the list of invites.

```

--------------------------------

### Custom Environment example

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/core-options.md

Builds a custom Environment with base, production, and agent URLs, then passes it to DeepgramClient.builder().environment(). The agentRest URL is optional and defaults to the production agent REST endpoint.

```java
Environment env = Environment.custom()
        .base("https://your-rest-endpoint.com")
        .production("wss://your-listen-websocket-endpoint.com")
        .agent("wss://your-agent-websocket-endpoint.com")
        .build();
DeepgramClient client = DeepgramClient.builder().environment(env).build();
```

--------------------------------

### Error handling for connect and configure failures

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/speak-v2-websocket.md

Shows how to handle connection failures via ExecutionException and configure rejections via the onConfigureFailure callback. Configure rejections are delivered as typed callbacks, not exceptions.

```java
try {
    ttsWs.connect(V2ConnectOptions.builder().model("flux-alexis-en").build()).get(10, TimeUnit.SECONDS);
} catch (ExecutionException e) {
    System.err.println("connect failed: " + e.getCause());
}
ttsWs.onConfigureFailure(f -> {
    // typed rejection: f.getCode() is SpeakV2ConfigureFailureCode, f.getDescription() the human-readable reason
});
```

--------------------------------

### GET /v1/projects/{project_id}/members

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/manage.md

Lists members of a project.

```APIDOC
## GET /v1/projects/{project_id}/members

### Description
Lists members of a project.

### Method
GET

### Endpoint
/v1/projects/{project_id}/members

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.

### Response
#### Success Response (200)
- **ListProjectMembersV1Response** - The response containing the list of members.

```

--------------------------------

### GET /v1/projects/{project_id}/purchases

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/api-reference/manage.md

Lists purchases for a project.

```APIDOC
## GET /v1/projects/{project_id}/purchases

### Description
Lists purchases for a project.

### Method
GET

### Endpoint
/v1/projects/{project_id}/purchases

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The ID of the project.

### Response
#### Success Response (200)
- **ListProjectPurchasesV1Response** - The response containing the list of purchases.

```

--------------------------------

### GET /v1/projects/{project_id}

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/endpoints.md

Retrieves details of a specific project by its ID.

```APIDOC
## GET /v1/projects/{project_id}

### Description
Retrieves details of a specific project by its ID.

### Method
GET

### Endpoint
/v1/projects/{project_id}

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The unique identifier of the project.

#### Query Parameters
- **limit** (integer) - Optional - The maximum number of items to return.
- **page** (integer) - Optional - The page number to retrieve.

### Response
#### Success Response (200)
- **GetProjectV1Response** - The response object containing project details.

#### Response Example
```json
{
  "project": {}
}
```
```

--------------------------------

### GET /v1/agent/settings/think/models

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/_autodocs/endpoints.md

Lists available think models for agent settings.

```APIDOC
## GET /v1/agent/settings/think/models

### Description
Lists available think models for agent settings.

### Method
GET

### Endpoint
/v1/agent/settings/think/models

### Parameters
No parameters.

### Response
#### Success Response (200)
- **AgentThinkModelsV1Response** - List of think models.

#### Response Example
{
  "models": []
}
```

--------------------------------

### Project structure

Source: https://github.com/deepgram/deepgram-java-sdk/blob/main/CONTRIBUTING.md

Shows the project directory structure, highlighting the main source directories and key files.

```text
deepgram-java-sdk/
  src/
    main/java/
      core/                  # HTTP client, options, utilities
      errors/                # Error types
      resources/             # API resource clients
        agent/               # Voice Agent API
        auth/                # Authentication API
        listen/              # Speech-to-Text API (REST + WebSocket)
        manage/              # Management API
        read/                # Text Intelligence API
        selfhosted/          # Self-Hosted API
        speak/               # Text-to-Speech API (REST + WebSocket)
      types/                 # Shared request/response types
      DeepgramApiClient.java # Main sync client
      AsyncDeepgramApiClient.java # Main async client
    test/java/               # Test files
  build.gradle               # Build configuration
  Makefile                   # Build automation
```