Get from zero to your first decision in 5 minutes.

Installation

The DecisionsLayer SDK is a thin integration layer: validate, serialize, send, retry. It sends data to the platform and exposes helpers for workspace, telemetry, intelligence, and optimization APIs. It does not execute decisions locally.

npm install @decisionslayer/ingestion-ts

Supported runtime: Node 18+. The package name remains ingestion-oriented for compatibility, but the current client also exposes auth, workspace, analytics, observability, intelligence, and optimization namespaces. Python and Go SDKs should stay on the roadmap until shipped — see github.com/decisionslayer.

Authentication

Generate an API key from your workspace settings. Keys are tenant-scoped and rotate independently.

import { createDecisionIngestionClient } from "@decisionslayer/ingestion-ts";

const client = createDecisionIngestionClient({
  apiKey: process.env.DL_API_KEY,
  baseUrl: "https://api.decisionslayer.com",
  timeoutMs: 5000,
});

Quickstart

Log a decision the moment it happens. Outcomes can be attached later by using the platform decision ID returned by client.decisions.log.

const decision = await client.decisions.log({
  external_decision_id: "dec-ext-001",
  decision_type: "transaction_review",
  subject:  { type: "transaction", id: "txn_123" },
  decision: { action: "reject", status: "final" },
  actors:   [{ type: "rule_engine", id: "fraud-rules", version: "v12" }],
  evidence: [{ type: "rule_hit", key: "velocity_rule", value: "triggered" }],
  inputs:   { amount: 420, currency: "USD" },
  metadata: { customer_id: "cust_77" },
  occurred_at: new Date().toISOString(),
});

Data model

Every record follows the lifecycle Decision → Evidence → Context → Outcome. Five top-level fields shape every event:

• subject — what the decision is about (transaction, customer, claim, listing)
• decision — the action taken (approve, reject, review, etc.) and its status
• actors — who or what decided (rule engine, model version, human reviewer, service)
• evidence — the inputs that mattered (rule hits, scores, policy refs, provider responses)
• outcome — what eventually happened (chargeback, conversion, escalation), attached later

Logging decisions

Decisions are append-only. Once written, they cannot be edited. Replays with the same tenant and external_decision_id are idempotent: the API returns the existing decision ID with status: "idempotent" and idempotent: true.

Required fields

• external_decision_id — your stable identifier; used for idempotent replay detection when present
• decision_type — taxonomy label (e.g. transaction_review, kyc_check)
• subject.type & subject.id
• decision.action & decision.status
• occurred_at — ISO 8601 timestamp

Optional fields

Everything else — context, actors, evidence, inputs, metadata — is optional and JSONB. We are strict on known fields, flexible on metadata.

Linking outcomes

An outcome is the eventual result of a decision — chargeback, conversion, regulator finding, verification, fulfillment, or any other downstream result. Outcomes are linked by platform decision ID and arrive whenever they're known (minutes, days, or weeks later).

await client.outcomes.log(decision.id, {
  outcome_type:  "fraud_resolution",
  outcome_value: "true_positive",
  payload: { chargeback_id: "cb_001" },
  occurred_at: new Date().toISOString(),
});

Idempotency

The SDK derives an idempotency key from external_decision_id by default. Replays are safe — duplicate decision writes return the original record without duplicating actors, evidence, or outbox events.

Decision configuration

DecisionsLayer is domain-agnostic. Workspace decision configuration defines action semantics, outcome mappings, quality score weights, observability thresholds, optimization guardrails, simulation field paths, threshold definitions, policies, actor groups, and pattern dimensions.

const record = await client.workspace.getDecisionConfig();
const coverage = await client.workspace.getDecisionConfigCoverage();

await client.workspace.saveDecisionConfig({
  config: record.config,
  completed: true,
  change_summary: "Reviewed workspace defaults",
});

Saved configuration is versioned and audited. Quality, simulation, and recommendation payloads include config_version so reviewers can trace which assumptions produced a result.

Retries & errors

The SDK retries 5xx and connection errors with exponential backoff (jittered, capped at 30s). 4xx errors are surfaced immediately as structured exceptions:

• ValidationError — schema or required-field violation
• ApiError — non-2xx API response with status, code, details, request ID, and correlation ID
• TransportError — network failure after exhausted retries
• RetryExhaustedError — retry budget consumed

Complete references

Use this page for the first integration pass. The complete SDK and REST API references live on dedicated pages so each method and endpoint can be documented independently.