> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strait.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK Integration

> Integrating your job code with Strait using official SDK client libraries.

Strait provides official SDKs for **TypeScript**, **Python**, **Go**, **Ruby**, and **Rust** — all with full feature parity. This guide covers how to use the SDKs to interact with the Strait API and integrate SDK endpoints into your job code.

<Info>
  For detailed per-language documentation, see the [SDK Reference](/sdks/overview).
</Info>

## Installing an SDK

<CodeGroup>
  ```bash TypeScript theme={null}
  npm install @strait/ts
  ```

  ```bash Python theme={null}
  pip install strait-python
  ```

  ```bash Go theme={null}
  go get github.com/strait-dev/strait-go
  ```
</CodeGroup>

Ruby and Rust SDKs are available in their dedicated repositories:

* [strait-dev/strait-ruby](https://github.com/strait-dev/strait-ruby)
* [strait-dev/strait-rust](https://github.com/strait-dev/strait-rust)

## Configuration

The recommended approach is a `strait.json` file at your project root plus the `STRAIT_API_KEY` environment variable:

```bash theme={null}
# Create config file
strait init

# Set API key
export STRAIT_API_KEY="sk_live_..."
```

Then create a client from the config file:

<CodeGroup>
  ```ts TypeScript theme={null}
  import { createClientFromConfigFile } from "@strait/ts/node";
  const client = await createClientFromConfigFile();
  ```

  ```python Python theme={null}
  from strait import Client
  client = Client.from_file()
  ```

  ```go Go theme={null}
  client, err := strait.NewClientFromFile(nil)
  ```
</CodeGroup>

See [SDK Configuration](/sdks/configuration) for full details on `strait.json`, environment variable overrides, and alternative configuration methods.

## SDK Run Endpoints

Strait provides specialized endpoints under `/sdk/v1/runs/{runID}/` for job executors to communicate progress, logs, and state back to the system.

### Authentication

SDK run endpoints require a **JWT Run Token**:

* **Header**: `Authorization: Bearer <run_token>`
* **Token Source**: Provided in the response when a job is triggered

### Available Endpoints

| Endpoint          | Method | Description                                                            |
| ----------------- | ------ | ---------------------------------------------------------------------- |
| `/log`            | POST   | Send structured logs (`message`, `level`, `type`, `data`)              |
| `/progress`       | POST   | Report completion percentage (`percent`, `message`, `step`)            |
| `/annotate`       | POST   | Add metadata annotations (max 50 per run)                              |
| `/heartbeat`      | POST   | Signal the job is alive (prevents timeout)                             |
| `/checkpoint`     | POST   | Save resumable state (`state` JSON)                                    |
| `/usage`          | POST   | Report AI model usage (`provider`, `model`, `tokens`, `cost_microusd`) |
| `/tool-call`      | POST   | Record external tool invocation                                        |
| `/output`         | POST   | Store structured results/artifacts                                     |
| `/complete`       | POST   | Mark run as successfully completed                                     |
| `/fail`           | POST   | Mark run as failed                                                     |
| `/wait-for-event` | POST   | Pause run until external event arrives                                 |
| `/spawn`          | POST   | Create a child job run                                                 |
| `/continue`       | POST   | Create a continuation run                                              |

### Using SDK Run Endpoints

<CodeGroup>
  ```ts TypeScript theme={null}
  import { createClient } from "@strait/ts";

  // Create a client with the run token
  const runClient = createClient({
    baseUrl: "https://api.strait.dev",
    auth: { type: "runToken", token: process.env.RUN_TOKEN! },
  });

  // Log progress
  await runClient.logRun({
    pathParams: { runID: "run-123" },
    body: { message: "Processing batch 3/10", level: "info" },
  });

  // Report progress
  await runClient.reportProgress({
    pathParams: { runID: "run-123" },
    body: { percent: 30, message: "Processing..." },
  });

  // Complete the run
  await runClient.completeRun({
    pathParams: { runID: "run-123" },
    body: { result: { processed: 100 } },
  });
  ```

  ```python Python theme={null}
  from strait import Client

  run_client = Client(
      base_url="https://api.strait.dev",
      run_token=os.environ["RUN_TOKEN"],
  )

  # Log progress
  run_client.sdk_runs.log_run("run-123", {
      "message": "Processing batch 3/10",
      "level": "info",
  })

  # Report progress
  run_client.sdk_runs.progress_run("run-123", {
      "percent": 30,
      "message": "Processing...",
  })

  # Complete the run
  run_client.sdk_runs.complete_run("run-123", {
      "result": {"processed": 100},
  })
  ```

  ```go Go theme={null}
  import (
      strait "github.com/strait-dev/strait-go"
      "github.com/strait-dev/strait-go/operations"
  )

  runClient := strait.NewClient(
      strait.WithBaseURL("https://api.strait.dev"),
      strait.WithRunToken(os.Getenv("RUN_TOKEN")),
  )
  sdkRuns := operations.NewSDKRunsService(runClient)

  // Log progress
  sdkRuns.LogRun(ctx, "run-123", map[string]any{
      "message": "Processing batch 3/10",
      "level":   "info",
  })

  // Complete the run
  sdkRuns.CompleteRun(ctx, "run-123", map[string]any{
      "result": map[string]any{"processed": 100},
  })
  ```
</CodeGroup>

### Wait for External Events

Pause a run and wait for an external event (approvals, webhooks, third-party callbacks):

<CodeGroup>
  ```ts TypeScript theme={null}
  // Pause the run
  await runClient.waitForEvent({
    pathParams: { runID: "run-123" },
    body: {
      event_key: "approval:order-789",
      timeout_secs: 7200,
    },
  });

  // Later, send the event (using an API key client)
  const apiClient = createClient({
    baseUrl: "https://api.strait.dev",
    auth: { type: "bearer", token: process.env.STRAIT_API_KEY! },
  });

  await apiClient.sendEvent({
    pathParams: { eventKey: "approval:order-789" },
    body: { payload: { approved: true } },
  });
  ```

  ```python Python theme={null}
  # Pause the run
  run_client.sdk_runs.wait_for_event("run-123", {
      "event_key": "approval:order-789",
      "timeout_secs": 7200,
  })

  # Later, send the event
  api_client = Client.from_file()
  api_client.event_triggers.send("approval:order-789", {
      "payload": {"approved": True},
  })
  ```
</CodeGroup>

<Tip>
  Use the `heartbeat` endpoint regularly (every 30 seconds) in long-running jobs to prevent timeout.
</Tip>

## What's Next?

<CardGroup cols={2}>
  <Card title="SDK Reference" icon="code" href="/sdks/overview">
    Full SDK documentation — feature parity table, architecture, and per-language guides.
  </Card>

  <Card title="Configuration" icon="gear" href="/sdks/configuration">
    `strait.json` schema reference, environment variable overrides, and migration guide.
  </Card>
</CardGroup>