TypeScript SDK

Use the TypeScript SDK to connect a provider account, save a model, submit a run (one task you send to Millwork; the API calls it an execution), and read its result and receipt. You can also register, test, and connect an output check (a verifier in the API). It provides typed requests and responses for TypeScript and JavaScript on Node.js.

Install

Requires Node.js 20 or later (Millwork tests 20 and 22) and an organization API key.

npm install @millwork/solver@0.1.21

The package is @millwork/solver on npm. The same package includes both the typed SDK and the millwork command-line tool, so this page and the CLI setup use the same version. The tool reads SOLVERAPI_API_KEY and optional SOLVERAPI_BASE_URL; Set up with the CLI covers it. For the shared setup and private key-entry rules, follow Connect an output check. Use the generated REST lifecycle reference for exact API fields and the verifier-dock contract for the endpoint request and response. The installed CLI reports its supported commands and flags offline with millwork verifier capabilities --json.

Make a test run

First configure your organization key in this terminal. The SDK accepts the key and base URL as arguments; it does not choose an organization for you. Save this JavaScript example as example.mjs next to the package.json where you installed the SDK. It runs with Node directly and uses the same client and methods as TypeScript. It submits a free test run and reads its receipt.

import { Solver } from "@millwork/solver";

const solver = new Solver({
  apiKey: process.env.SOLVERAPI_API_KEY,
  baseUrl: "https://api.getmillwork.dev/v1"
});

const run = await solver.executions.create(
  {
    mode: "echo",
    task: { objective: "Check the Millwork API lifecycle." },
    policy: { data_classes: ["public"], budget: { max_cost_usd: 1, max_runtime_s: 30 } },
  },
  { idempotencyKey: `echo-${Date.now()}` },
);

console.log("Run ID:", run.execution_id);
let status = run.status;
const deadline = Date.now() + 90_000;
while (!["completed", "failed", "cancelled", "expired"].includes(status)) {
  if (Date.now() >= deadline) {
    throw new Error(`Still waiting. Keep run ID ${run.execution_id} and inspect it later.`);
  }
  await new Promise((resolve) => setTimeout(resolve, 1000));
  status = (await solver.executions.get(run.execution_id)).status;
}

const receipt = await solver.receipts.get(run.execution_id);
console.log(status, receipt.mode);

Run it from the same terminal:

node example.mjs

Expected result: completed echo. For another outcome, keep the run ID and follow Errors and retries. To get a model answer, continue with Run a model. A test run (the API calls it Echo, mode: "echo") has no platform fee or model cost. It takes no output check, a check applied to a run’s output, so the example omits verifier_id.

Register and test an output check

Start with a running endpoint that implements the output-check contract. Set VERIFIER_URL to its HTTPS address. Save this as output-check.mjs next to the installed package and run node output-check.mjs from the terminal with your organization key configured:

import { randomUUID } from "node:crypto";
import { Solver } from "@millwork/solver";

const solver = new Solver({
  apiKey: process.env.SOLVERAPI_API_KEY,
  baseUrl: "https://api.getmillwork.dev/v1",
});
const registered = await solver.verifiers.create({
  display_name: "My output check",
  version: "1.0.0",
  kind: "endpoint",
  endpoint: { url: process.env.VERIFIER_URL, auth_ref: "" },
  input_data_classes: ["public"],
  scoring: { correctness: "boolean_anchors", quality: "scalar_0_1" },
}, { idempotencyKey: randomUUID() });

const report = await solver.verifiers.test(registered.verifier_id,
  { idempotencyKey: randomUUID() });
console.log(registered.verifier_id, report);

Keep the returned verifier_id. The test reports endpoint health; it does not authorize a paid run. If the endpoint needs a key, continue with the private handoff below. Do not put that key in verifiers.create.

Use an output check on a run

First save a model and keep its arm_id. Connect and test the check above, then keep its verifier_id. A live run has a platform fee when accepted and may incur model usage. Review the exact task, model, limits, check, and charge before authorizing this run; the shared run procedure owns approval and recovery. Set ARM_ID, VERIFIER_ID, MAX_COST_USD, MAX_RUNTIME_S, and a unique RUN_REQUEST_KEY in your terminal. Record that key with the exact request before submitting; reuse it only for an uncertain retry of the same request. Choose positive limits for the task you reviewed; the model budget is separate from the platform fee. Save this as checked-run.mjs next to the installed package. Run node checked-run.mjs only for the run you have authorized:

import { Solver } from "@millwork/solver";

const armId = process.env.ARM_ID;
const verifierId = process.env.VERIFIER_ID;
const requestKey = process.env.RUN_REQUEST_KEY;
if (!armId || !verifierId || !requestKey) {
  throw new Error("Set ARM_ID, VERIFIER_ID, and RUN_REQUEST_KEY first");
}
const maxCostUsd = Number(process.env.MAX_COST_USD);
const maxRuntimeS = Number(process.env.MAX_RUNTIME_S);
if (!Number.isFinite(maxCostUsd) || maxCostUsd <= 0 ||
    !Number.isInteger(maxRuntimeS) || maxRuntimeS <= 0) {
  throw new Error("Set positive MAX_COST_USD and whole-second MAX_RUNTIME_S limits");
}
const solver = new Solver({
  apiKey: process.env.SOLVERAPI_API_KEY,
  baseUrl: "https://api.getmillwork.dev/v1",
});
const run = await solver.executions.create({
  mode: "live",
  task: { objective: "Reply with the single word: ok" },
  policy: {
    data_classes: ["public"],
    budget: { max_cost_usd: maxCostUsd, max_runtime_s: maxRuntimeS },
    on_eval: [],
  },
  routing: { required_arm_id: armId },
  verifier_id: verifierId,
}, { idempotencyKey: requestKey });
console.log(run.execution_id, run.status);

Expected result: an execution_id and an initial status. Keep the request key unchanged if you need to recover an uncertain submission. Read the result and receipt by that ID; a completed run can still have a rejected or unavailable check.

Connect, replace, or restore a protected output check

@millwork/solver@0.1.21 includes verifierConnection. Register the endpoint as above, then start the private handoff from your server. This example uses Response.redirect to send the intended person’s browser to Millwork’s private page. Keep verifierOperationKey in that person’s server-side session between the two requests. Do not log or retain the private URL. The person enters the endpoint key on that page; the key is never an SDK argument.

import { randomUUID } from "node:crypto";
import { Solver } from "@millwork/solver";

const solver = new Solver({
  apiKey: process.env.SOLVERAPI_API_KEY,
  baseUrl: "https://api.getmillwork.dev/v1",
});

// Wire this to your server's Connect action; return its Response to the browser.
export async function beginProtected(verifierId, session) {
  const intent = await solver.verifierConnection.createIntent(verifierId,
    { kind: "preset_days", days: 90 }, { idempotencyKey: randomUUID() });
  if (new URL(intent.continue_url).origin !== "https://app.getmillwork.dev") {
    throw new Error("Unexpected private-entry origin");
  }
  session.verifierOperationKey = intent.intent_id;
  return Response.redirect(intent.continue_url, 303);
}

// After private entry, wire this to a separate, user-initiated Continue action.
export async function finishProtected(verifierId, session) {
  const operationKey = session.verifierOperationKey;
  if (!operationKey) throw new Error("No pending output-check connection");
  const outcome = await solver.verifierConnection.continue(verifierId, operationKey, randomUUID());
  if (outcome.state === "done") delete session.verifierOperationKey;
  return outcome;
}

The Connect action calls beginProtected(verifierId, session) and returns its redirect response. After private entry, the person returns to your app manually and uses Continue, which calls finishProtected(verifierId, session). The intent_id saved by the first action is the operation key used by the second. The 90-day stop choice is an example; choose a supported stop policy for your application. For a replacement or restoration, create a new intent for the same verifier_id and repeat the handoff. Read solver.verifiers.connection(verifierId) or solver.verifierConnection.inspect(verifierId, { operationKey }) to see the current state. The SDK also exposes testAndPromote and revoke as lower-level operations; use continue and disconnect for read-backed lifecycle results.

Returned field	What to do
`next_action: "enter_key"`	Finish private entry, then continue the same operation.
`next_action: "resume"`	Keep the operation key; retry the same `continue` or `disconnect` action with a fresh request key.
`next_action: "start_again"`	Fix the endpoint or key and create a new intent.
`next_action: "inspect"`	Read `verifierConnection.inspect(verifierId, { operationKey })` before another change.
`state: "refused"`	Read `error.status` and `error.title`, inspect the operation, and correct the cause. A `401` or `403` throws `SolverApiError` instead.
`state: "done"`	The connection read confirms the change; `next_action` is `null`.

To disconnect, obtain explicit confirmation from the person who owns the connection, then save a new operation key for this disconnect:

const disconnectKey = randomUUID();
const outcome = await solver.verifierConnection.disconnect(
  verifierId, disconnectKey, randomUUID(), true);

Keep disconnectKey unchanged if the result asks you to resume. Set the last argument to true only after that explicit confirmation. Millwork stopping use of its key does not revoke that key at your endpoint. The shared connection guide owns the deployment, private entry, governed-run approval, and receipt sequence. Connecting or testing a check never authorizes a paid run.

What the client does

You construct one Solver with apiKey and baseUrl. The client never changes the base URL you give it. Each resource below calls one API endpoint and returns the response typed. A saved model is an arm in the API, an output check is a verifier, and an organization is a tenant. These methods return newest first: receipts.list(), arms.list(), verifiers.list(), and proposals.list(). For arms, verifiers, and proposals, use nextCursor and .next() to fetch older items. The receipts list has no next page.

Client method or resource	REST endpoint	What it does
`executions.create(request, { idempotencyKey })`	`POST /v1/executions`	Submits a run.
`executions.get(id)`	`GET /v1/executions/{id}`	Reads a run’s status.
`executions.events(id)`	`GET /v1/executions/{id}/events`	Polls the run’s events and stops after the final status event.
`executions.result(id)`	`GET /v1/executions/{id}/result`	Reads the model output of a completed live run.
`executions.cancel(id)`	`POST /v1/executions/{id}/cancel`	Cancels a run.
`receipts.get(id)`, `receipts.list(filter)`	`GET /v1/receipts/{id}`, `GET /v1/receipts`	Reads one receipt, or lists receipts by time, status, or saved model.
`arms` create, list, get, update, disable	`/v1/arms`	Manages your saved models.
`verifiers.create()`, `.list()`, `.get()`, `.connection()`, `.update()`, `.test()`, `.retire()`	`/v1/verifiers`	Registers, reads, changes, tests, and retires output checks; `connection()` reads its current key state.
`verifierConnection.createIntent()`, `.inspect()`, `.testAndPromote()`, `.revoke()`, `.continue()`, `.disconnect()`	`/v1/verifiers/{verifierId}/connection*`	Starts and continues private key entry, reads state, and disconnects with confirmation.
`modelSourceProfiles.list()`	`GET /v1/model-source-profiles`	Lists available providers and their authentication methods.
`sourceCredentialHandoffs` start, poll	`/v1/source-credential-handoffs`	Starts the provider’s browser setup: approval or private key entry, depending on the enabled method. `poll` reads its state once; inspect that state before continuing. Credentials never pass through the client.
`sourceConnections` create, list, get, test, rotate, revoke, syncDeployments	`/v1/source-connections`	Manages a provider connection and loads its models.
`modelDeployments` list, get	`/v1/model-deployments`	Reads the models loaded from your connections.
`modelCatalog.get()`, `modelCatalog.definitions()`	`GET /v1/model-catalog`, `GET /v1/model-definitions`	Reads the models you can save now, and model identity records.
`apiKeys` create, list, update, revoke	`/v1/api-keys`	Manages organization API keys.
`proposals` list, get, approve, reject	`/v1/proposals`	Reads and decides proposed follow-up actions.
`usage.get(period)`	`GET /v1/usage`	Reads usage for a period.
`account.get()`	`GET /v1/account`	Reads your account, quota, and balance.
`evalSummary.get(window)`	`GET /v1/eval-summary`	Reads the evaluation summary for a time window.
`complianceExports.get(period)`	`GET /v1/compliance-export`	Reads a period’s compliance export.
`tenantTemplates` list, plan, apply, get, recover, resume	`/v1/tenant-templates`, `/v1/tenant-template-plans`, `/v1/tenant-template-applications`	The setup path the CLI uses. Present from 0.1.2 on.
`bootstrapTenant({ baseUrl, displayName })`	`POST /v1/tenants`	Creates an organization and its first API key. A standalone function, because it runs before you have a key. It takes no request key and does not replay: a same-name retry is refused, a different name creates a second organization.

Run submission takes a request key, sent as the Idempotency-Key header. You own the key; the client forwards it unchanged, so a retry with the same key returns the same run instead of starting a second one. Most other writes accept a request key as an option. The client offers no request-key option for cancel, proposal decisions, and template plans, so each of those gets one attempt. Template apply and template resume require a request key. The client retries on its own only when a replay cannot apply work twice: a read, or a write that carries your request key. It retries those after a network failure or a 5xx response, up to two more attempts by default (maxRetries), with exponential backoff from 500 ms (retryBackoffMs), and replays the same bytes each time. It never retries a 4xx response, and a write without a request key gets exactly one attempt.

Connect your provider account

Call modelSourceProfiles.list() before requesting a provider credential. Follow Connect a provider account for the returned method and the handoff, test and model-refresh sequence. A browser step finishing does not mean the connection passed its test or a paid run started. For replacement or removal, sourceConnections.rotate() and sourceConnections.revoke() operate on the existing connection ID. The replacement guide explains when to remove old provider access and how to recover a response you did not receive.

Errors

Every non-2xx response throws SolverApiError. It carries the API’s error object as fields, so you never parse the message: type (the error code), status, detail, instance, errors (per-field messages, when present), and retryAfterS (the seconds to wait, when the API sends one). A network failure, or an error response whose body is not valid JSON, throws SolverApiNetworkError with the underlying cause. Errors and retries lists each error code and the next step. If a run was accepted and the provider later failed, inspect its status, events and receipt. That is a run failure, not necessarily an SDK transport failure; repeat browser setup only when access needs replacement.

API basics

The base URL, bearer authentication, request keys, polling, and the error format.

Make your first API call

Send a free test run with curl and read its receipt.

Get started

Provide models

Build

Build safely

SDK and MCP

Install

Make a test run

Register and test an output check

Use an output check on a run

Connect, replace, or restore a protected output check

What the client does

Connect your provider account

Errors

API basics

Make your first API call

​Install

​Make a test run

​Register and test an output check

​Use an output check on a run

​Connect, replace, or restore a protected output check

​What the client does

​Connect your provider account

​Errors

API basics

Make your first API call

Install

Make a test run

Register and test an output check

Use an output check on a run

Connect, replace, or restore a protected output check

What the client does

Connect your provider account

Errors