> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nora.my/llms.txt
> Use this file to discover all available pages before exploring further.

# SDK overview

> TypeScript client for calling Nora Flows, capturing feedback, and embedding the improvement loop in your app

**`@conscience-technology/nora-sdk`** is the TypeScript client for the Nora platform. Agents are defined in Nora (via UI / MCP / CLI); the SDK is where your app code **calls them, watches them, and feeds results back**. It can't change agent definitions — that path stays UI / MCP / CLI → approval → new version — but it can invoke, read decisions, capture feedback, and drive the improvement queue from inside your product.

<Note>
  **Status (2026-09-06)**: implemented and typechecks in the platform repo at `0.0.1`. Publish to a public npm scope is in progress; the contract is stable — swap install URL when the public publish lands without changes.
</Note>

## When to reach for the SDK

Three ways to talk to Nora from code, each right for a different caller:

| Surface                                     | Right for                                                                           | Auth                 |
| ------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------- |
| **SDK** (`@conscience-technology/nora-sdk`) | Your app's backend — full typed surface, error classes, retries, structured logging | PAT + trigger secret |
| **MCP `run_flow`**                          | Coding agents (Claude Desktop, Cursor) invoking Flows on your behalf                | PAT / session        |
| **HTTP**                                    | Anything else — cron jobs, curl, non-JS backends                                    | Trigger secret       |

The SDK is the right choice when your app already runs Node/TS and you want typed results, per-call idempotency, `onBehalfOf` audit trails, and the improvement loop embedded in your admin surface.

## Server-side only

The client carries PATs and trigger secrets, so **initialising in the browser throws** — silent operation is the worst failure mode. If end-user screens need to trigger runs, proxy through your server.

## Get started

1. **[Install](/sdk/install)** — `npm install @conscience-technology/nora-sdk`, prerequisites (Node 18+, ESM), version pinning.
2. **[Auth](/sdk/auth)** — mint PAT + trigger secret, pick the right scopes.
3. **[Client options](/sdk/client-options)** — full `ClientOptions` reference (base URL, retries, logging, custom fetch, trigger header).

## Surfaces

Each surface is a category of methods. Same split as the CLI's command groups.

| Surface                                      | Auth                         | Verbs                                                                                   |
| -------------------------------------------- | ---------------------------- | --------------------------------------------------------------------------------------- |
| [Execution](/sdk/execution)                  | Trigger secret               | `flows.run` · `newTraceRef`                                                             |
| [Feedback](/sdk/feedback)                    | Trigger secret               | `feedback` · `signals.report`                                                           |
| [Transparency](/sdk/transparency)            | PAT `read`                   | `resolve`                                                                               |
| [Improvements & versions](/sdk/improvements) | PAT `read` / `approve`       | `improvements.{list,get,approve,reject,revert,staleFixes}` · `versions.{list,rollback}` |
| [Simulations](/sdk/simulations)              | PAT `simulate`               | `simulations.{estimate,run,get,remaining,requery,promote}`                              |
| [Resources](/sdk/resources)                  | PAT `content` + `onBehalfOf` | `memory.{read,write}` · `knowledge.{upload,list}`                                       |
| [Errors & failure model](/sdk/errors)        | —                            | Typed error classes, 4-layer failure model, logging                                     |

## See also

* [`nora flows run`](/cli/flows) — the CLI equivalent of `flows.run`, useful while the SDK is pre-publish.
* [`nora feedback`](/cli/feedback) — CLI counterpart to `feedback` / `signals.report`.
* [`nora approvals`](/cli/approvals) — approval workflow the improvement queue shares with the platform.