SDK Client
Install @blekline/client or blekline_client, configure options, and call mask, enforce, policy, and cell runs.
The SDK is the programmatic surface for the execution plane: read published policy (compileHash), enforce tools, and record act as workflow runs. Use @blekline/client or blekline_client. Calls carry the workspace token, optional workspace id, and client surface metadata for audit.
Install
npm install @blekline/client
Create a client
Construct one client per process (or per request in serverless). The token must include scopes for the methods you call. Create keys in API keys.
import { BleklineClient } from "@blekline/client";
const client = new BleklineClient({
baseUrl: process.env.BLEKLINE_API_URL ?? "https://app.blekline.com",
workspaceToken: process.env.BLEKLINE_WORKSPACE_TOKEN!,
metadata: { clientSurface: "sdk" },
});
const policy = await client.getExecutionPolicy();
console.log(policy.enforcementStage, policy.policy?.compileHash);
const enforced = await client.enforceToolCall({
toolName: "run_sql",
arguments: { query: userQuery },
platform: "langchain",
clientSurface: "sdk",
});
if (enforced.action === "block") throw new Error("Blocked by policy");
const { run, requiresCell } = await client.createCellRun({
workflowId: "wf_your_workflow_id",
displayName: "SDK act run",
executionTier: "act",
toolCall: true,
});
console.log(run.id, run.compileHash, requiresCell);Client options
The TypeScript client accepts baseUrl or baseUrls for failover, required workspaceToken, optional workspaceId and bearer, metadata.clientSurface (sdk, cursor, and other published surfaces), and an optional fetchImpl for testing.
Python mirrors the same fields: workspace_token, base_url, workspace_id, client_surface, and timeout.
For private or hybrid deployments, point baseUrl at your ingress and keep the same token headers.
const client = new BleklineClient({
baseUrl: process.env.BLEKLINE_API_URL!,
baseUrls: [
process.env.BLEKLINE_API_URL!,
process.env.BLEKLINE_API_URL_FALLBACK!,
].filter(Boolean),
workspaceToken: process.env.BLEKLINE_WORKSPACE_TOKEN!,
metadata: { clientSurface: "sdk" },
});Multiple clients
Use one client instance per environment or team. Each instance should use its own workspace token so revocation and scopes stay isolated.
import { BleklineClient } from "@blekline/client";
const production = new BleklineClient({
baseUrl: "https://app.blekline.com",
workspaceToken: process.env.BLEKLINE_WORKSPACE_TOKEN_PRODUCTION!,
metadata: { clientSurface: "sdk" },
});
const staging = new BleklineClient({
baseUrl: "https://app.blekline.com",
workspaceToken: process.env.BLEKLINE_WORKSPACE_TOKEN_STAGING!,
metadata: { clientSurface: "sdk" },
});SDK surface
Methods map to the same policy decision order as the console. Publish runtime policy first so compileHash on runs matches what enforce uses.
Policy & enforce
| Method | Scope | Purpose |
|---|---|---|
getExecutionPolicy() | — | Read published runtime policy and compileHash (TypeScript). |
enforceToolCall() / enforce_tool_call() | — | Apply published tool policy before side effects. |
simulatePolicy() / simulate_policy() | — | Dry-run policy against a prompt without persisting act. |
Act & runs
| Method | Scope | Purpose |
|---|---|---|
createCellRun() / create_cell_run() | runs:write | Start an act run tied to a workflow; records compileHash. |
listCellRuns() / getCellRun() | runs:read | Inspect run history and status (TypeScript SDK). |
Ingress & audit
| Method | Scope | Purpose |
|---|---|---|
emitEvent() | events:write | Push metadata-only audit events from automation. |
mask() | mask:write | Prompt ingress mask when hooks are not in the path. |
Framework helpers
LangChain and LlamaIndex packages reuse the same client at the tool boundary. Wire @blekline/langchain or @blekline/llamaindex after you have a client and published policy. See Connect agents and clients for framework tabs and ingress patterns.
OSS examples
Headless act runs: clone blekline-oss, set BLEKLINE_WORKSPACE_TOKEN, then run examples/cells/first-act-run (Node, Python, Go, or Rust variants). Ingress samples live under examples/ingress. Quick wire: npx @blekline/init. API shapes track packages/contracts/openapi.yaml (see CHANGELOG on the repo before production upgrades).