SDK

Use the Tenzarch SDK from server-side applications.

The Tenzarch SDK is the typed server-side interface to the Tenzarch Developer Platform for discovering AI Executions, submitting workloads, tracking Jobs, inspecting logs and telemetry, and reading usage data.

OVERVIEW

The SDK improves developer ergonomics without replacing network state.

The Tenzarch SDK is the typed server-side interface to the Tenzarch Developer Platform. It wraps authentication, AI Execution discovery, execution submission, Jobs, pagination, logs, telemetry, usage, idempotency, retries, cancellation, and structured errors while preserving the backend as the source of truth.

Typed access

Use Tenzarch and TenzarchError exports from @tenzarchsdk/sdk.

Execution operations

Discover AI Executions, submit workloads, persist Job references, and track lifecycle state.

Operational inspection

Read logs, telemetry, usage, and metrics through Developer Platform routes.

Safety controls

Use Idempotency-Key, AbortSignal, retries, pagination, and structured errors intentionally.

REQUIREMENTS

Use the SDK only from a server-side runtime.

Node.js

Node.js >=18.

API Key

A Tenzarch developer API Key.

Base URL

The Tenzarch API base URL for the environment you are integrating with.

Runtime boundary

A backend/server runtime, not browser JavaScript.

INSTALLATION

Install the SDK package when published.

Package command
npm install @tenzarchsdk/sdk

Current package version: 0.1.0. This is the intended installation command for the published package; confirm publication status in your package registry before using it in production installs.

CLIENT SETUP

Create a typed Tenzarch client.

Server-side setup
import { Tenzarch } from "@tenzarchsdk/sdk";

const tenzarch = new Tenzarch({
  apiKey: process.env.TENZARCH_API_KEY!,
  baseUrl: process.env.TENZARCH_API_URL!,
  timeoutMs: 30_000,
  maxRetries: 2,
});

Optional constructor values are timeoutMs, maxRetries, and fetch. The SDK automatically sends x-api-key on requests.

AI EXECUTION DISCOVERY

List available AI Executions.

services.list()
const services = await tenzarch.services.list();

for (const service of services) {
  console.log(service.serviceId, service.name, service.creditCost);
}
GET/api/marketplace/services

Lists AI Executions available for integration.

Authentication
Public route in the current mounted backend; SDK still sends x-api-key because the SDK client is keyed.
Scope
No services:read requirement is claimed for the public service-list route.
Request
None
Response
ExecutionService[]
Errors
SUBMIT AI EXECUTION

Submit an AI Execution idempotently.

services.execute()
const job = await tenzarch.services.execute(
  "code-gen",
  {
    prompt: "Generate a TypeScript utility for validating execution payloads.",
    language: "typescript",
  },
  { idempotencyKey: crypto.randomUUID() }
);

console.log(job.jobId, job.workflowRunId, job.status);
Canonical backend body
{
  "input": {
    "prompt": "Generate a TypeScript utility for validating execution payloads.",
    "language": "typescript"
  }
}
POST/api/marketplace/services/:id/execute

Creates an execution from an AI Execution capability.

Authentication
x-api-key
Scope
services:execute
Request
{ input: <user input> }
Response
ExecutionJob with jobId, workflowRunId, status, progress, and related execution fields.
Errors
INVALID_API_KEY, INSUFFICIENT_SCOPE, INSUFFICIENT_CREDITS, IDEMPOTENCY_CONFLICT, SERVICE_NOT_FOUND, SERVICE_DISABLED, INVALID_SERVICE_INPUT
IDEMPOTENCY

Use one key for one logical request.

For supported workload creation requests, the SDK sends Idempotency-Key when options.idempotencyKey is provided. The SDK does not invent local idempotency; it passes the key to the backend.

Same key + same logical request

The backend can replay the existing response instead of creating another workload.

Same key + materially different request

The backend can reject the request with IDEMPOTENCY_CONFLICT.

DEVELOPER JOBS

Create and inspect developer Jobs.

jobs.create()
const job = await tenzarch.jobs.create(
  {
    type: "developer_job",
    payload: { prompt: "Summarize this report." },
  },
  { idempotencyKey: crypto.randomUUID() }
);
jobs.list()
const result = await tenzarch.jobs.list({
  page: 1,
  limit: 20,
  status: "completed",
  serviceId: "code-gen",
  dateFrom: new Date("2026-01-01T00:00:00.000Z"),
  dateTo: new Date(),
});

console.log(result.data);
console.log(result.pagination);

jobs.list() returns { data, pagination }. Do not flatten pagination; persist and display it explicitly when building developer tooling.

JOB DETAILS

Read a Job and wait for terminal state.

jobs.get() and jobs.wait()
const job = await tenzarch.jobs.get("job_123");

const completedOrFailed = await tenzarch.jobs.wait("job_123", {
  timeoutMs: 120_000,
  intervalMs: 1_500,
});

jobs.wait() is SDK-side polling. It is not a backend endpoint. It repeatedly calls jobs.get() until the Job status is completed or failed, or until timeoutMs is reached.

LOGS & TELEMETRY

Inspect operational evidence.

Logs and telemetry
const logs = await tenzarch.jobs.logs("job_123");

const telemetry = await tenzarch.jobs.telemetry("job_123", {
  page: 1,
  limit: 50,
});

console.log(telemetry.data);
console.log(telemetry.pagination);

jobs.telemetry() returns { data, pagination }. Logs return ExecutionLog[]. Telemetry access should use the telemetry:read scope when enforced for the mounted backend route.

USAGE

Read usage summaries and metrics.

Usage
const usage = await tenzarch.usage.get({
  periodStart: "2026-01-01T00:00:00.000Z",
  periodEnd: new Date(),
});

const metrics = await tenzarch.usage.metrics();

The current metrics method calls GET /api/developers/metrics and returns the same UsageSummary shape as usage.get(). Do not document a separate metrics schema unless the backend introduces one.

CONTROL & ERRORS

Cancel, retry, and handle errors deliberately.

AbortSignal
const controller = new AbortController();

const promise = tenzarch.jobs.wait("job_123", {
  signal: controller.signal,
});

controller.abort();

Retries

The SDK retries transient failures: 429, 502, 503, 504, and network errors.

Defaults

timeoutMs defaults to 30000 for HTTP requests, maxRetries defaults to 2, jobs.wait() defaults to 120000 timeoutMs and 1500 intervalMs.

TenzarchError

Structured errors expose status, code, message, requestId, retryAfterSeconds, and response.

TenzarchError
import { TenzarchError } from "@tenzarchsdk/sdk";

try {
  await tenzarch.services.execute("code-gen", input, {
    idempotencyKey: crypto.randomUUID(),
  });
} catch (error) {
  if (error instanceof TenzarchError) {
    console.error(error.status, error.code, error.requestId);
  }
  throw error;
}
SCOPES & PRODUCTION PATTERN

Use scoped keys and persist execution references.

services:read

SDK type support exists, but the current service-list route is public; do not claim this scope is required for that route unless the backend enforces it.

services:execute

Required for executing AI Executions when scope enforcement is enabled.

jobs:read

Used for Job history and Job detail access where enforced.

telemetry:read

Used for telemetry access where enforced.

01Initialize
02Discover
03Submit idempotently
04Persist jobId
05Track lifecycle
06Inspect logs / telemetry
07Consume result