SDK Integration

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.

For detailed per-language documentation, see the SDK Reference.

Installing an SDK

npm install @strait/ts

pip install strait-python

go get github.com/strait-dev/strait-go

Ruby and Rust SDKs are available in their dedicated repositories:

Configuration

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

# Create config file
strait init

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

Then create a client from the config file:

import { createClientFromConfigFile } from "@strait/ts/node";
const client = await createClientFromConfigFile();

from strait import Client
client = Client.from_file()

client, err := strait.NewClientFromFile(nil)

See SDK 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

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 } },
});

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},
})

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},
})

Wait for External Events

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

// 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 } },
});

# 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},
})

Use the heartbeat endpoint regularly (every 30 seconds) in long-running jobs to prevent timeout.

What’s Next?

SDK Reference

Full SDK documentation — feature parity table, architecture, and per-language guides.

Configuration

strait.json schema reference, environment variable overrides, and migration guide.

Getting Started

Core Concepts

More Concepts

Configuration

Guides

AI Agents

Integrations

Operations

Development

SDK Integration

Installing an SDK

Configuration

SDK Run Endpoints

Authentication

Available Endpoints

Using SDK Run Endpoints

Wait for External Events

What’s Next?

SDK Reference

Configuration

​Installing an SDK

​Configuration

​SDK Run Endpoints

​Authentication

​Available Endpoints

​Using SDK Run Endpoints

​Wait for External Events

​What’s Next?

SDK Reference

Configuration

Installing an SDK

Configuration

SDK Run Endpoints

Authentication

Available Endpoints

Using SDK Run Endpoints

Wait for External Events

What’s Next?