Guides
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.
For detailed per-language documentation, see the SDK Reference.
Installing an SDK
npm install @strait/tspip install strait-pythongo get github.com/strait-dev/go-sdkgem install straitcargo add straitConfiguration
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)client = Strait::Client.from_filelet client = Client::from_file(None).await?;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/go-sdk"
"github.com/strait-dev/go-sdk/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},
})require "strait"
run_client = Strait::Client.new(
base_url: "https://api.strait.dev",
run_token: ENV["RUN_TOKEN"]
)
sdk_runs = Strait::Operations::SDKRuns.new(run_client)
# Log progress
sdk_runs.log_run("run-123", {
message: "Processing batch 3/10",
level: "info"
})
# Report progress
sdk_runs.progress_run("run-123", {
percent: 30,
message: "Processing..."
})
# Complete the run
sdk_runs.complete_run("run-123", {
result: { processed: 100 }
})use strait::Client;
use strait::operations::SdkRuns;
let run_client = Client::builder()
.base_url("https://api.strait.dev")
.run_token(std::env::var("RUN_TOKEN")?)
.build()?;
let sdk_runs = SdkRuns::new(&run_client);
// Log progress
sdk_runs.log_run("run-123", serde_json::json!({
"message": "Processing batch 3/10",
"level": "info",
})).await?;
// Report progress
sdk_runs.progress_run("run-123", serde_json::json!({
"percent": 30,
"message": "Processing...",
})).await?;
// Complete the run
sdk_runs.complete_run("run-123", serde_json::json!({
"result": { "processed": 100 },
})).await?;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.
Was this page helpful?