SDK Client

Install @blekline/client or blekline_client, configure options, and call mask, enforce, policy, and cell runs.

API keysOpenAPICell examples

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

MethodScopePurpose
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

MethodScopePurpose
createCellRun() / create_cell_run()runs:writeStart an act run tied to a workflow; records compileHash.
listCellRuns() / getCellRun()runs:readInspect run history and status (TypeScript SDK).

Ingress & audit

MethodScopePurpose
emitEvent()events:writePush metadata-only audit events from automation.
mask()mask:writePrompt ingress mask when hooks are not in the path.
Run first workflow

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).