Skip to main content

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.

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
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();
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

EndpointMethodDescription
/logPOSTSend structured logs (message, level, type, data)
/progressPOSTReport completion percentage (percent, message, step)
/annotatePOSTAdd metadata annotations (max 50 per run)
/heartbeatPOSTSignal the job is alive (prevents timeout)
/checkpointPOSTSave resumable state (state JSON)
/usagePOSTReport AI model usage (provider, model, tokens, cost_microusd)
/tool-callPOSTRecord external tool invocation
/outputPOSTStore structured results/artifacts
/completePOSTMark run as successfully completed
/failPOSTMark run as failed
/wait-for-eventPOSTPause run until external event arrives
/spawnPOSTCreate a child job run
/continuePOSTCreate 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 } },
});

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