SDK API
Curated reference for the main Captar SDK entrypoints used in v1.
SDK API
These are the core v1 entrypoints you should know.
createCaptar(options)
Creates a project-scoped runtime with pricing, exporter, and optional control-plane policy sync configuration.
Use this once near app startup. It is the root object that everything else hangs off, so the configuration should stay small and obvious.
Options
| Property | Type | Description |
|---|---|---|
project | string | Required. Project slug for grouping traces. |
exporter | { url: string; apiKey?: string } | Exporter | Optional batch exporter or HTTP endpoint. |
controlPlane | ControlPlaneOptions | Optional hook ID and policy sync URL. |
pricing | "builtin" | PricingEntry[] | Pricing table to use for cost estimation. |
defaultPolicy | SessionPolicy | Default policy merged into every session. |
onBudgetExceeded | (ctx) => void | Optional hook called when a request exceeds the session budget. |
onPolicyViolation | (ctx) => void | Optional hook called when a request is blocked by policy. |
Hooks
onBudgetExceeded receives:
| Property | Type | Description |
|---|---|---|
sessionId | string | The active session trace ID. |
budgetUsd | number | Total reserved USD at the point of failure. |
attemptedUsd | number | Estimated cost of the blocked request. |
onPolicyViolation receives:
| Property | Type | Description |
|---|---|---|
sessionId | string | The active session trace ID. |
reason | string | Human-readable violation reason. |
type | string | Violation category (e.g. "blocked"). |
startSession(options)
Starts a session with merged budget, metadata, and policy.
This is where you set the rules for one request, job, or task. Put the metadata you will want to see again in the trace here.
wrapOpenAI(client, options)
Wraps an existing OpenAI client so requests inherit the active session context.
It should preserve the API shape you already use, which keeps adoption low-risk.
trackTool(name, options)
Runs a tool inside the same runtime trace and applies tool policy before execution.
Use this for any external action that should show up alongside the model request that caused it.
Returns a ToolHandle — call .run(work) to execute the wrapped work.
flush()
Flushes exporter buffers when the request or job is done.
You usually want it in scripts, short-lived workers, and serverless handlers.