Analyses

An Analysis is the unit of work. A Content is only the material you submitted; nothing is read, laid out, or rendered until an Analysis references it.

const { content } = await inklet.contents.upload({
  assets: [inklet.assets.text("Dentist at 9am tomorrow")],
});

const analysis = await inklet.analyze({
  contentIds: [content.id],
  intent: "Make a reminder card",
});

const done = await inklet.analyses.wait(analysis);
console.log(done.outcome, done.presentationIds);

inklet.analyze() and inklet.direct() are shorthands for inklet.analyses.analyze() and inklet.analyses.direct().

analyze()

analyze(input?: AnalyzeInput): Promise<Analysis>

context defaults to submitted when contentIds is non-empty and to history when it is empty. context: "submitted" with no contentIds throws ConfigurationError, and so does scope on anything but history.

analyze() is never retried automatically. If it fails — a timeout, a dropped connection, a 5xx — the Analysis may already exist, so call it again with error.idempotencyKey, the key it sent (generated when you passed none), rather than a fresh one.

direct()

One uploaded image shown as sent, with no AI:

direct(input: DirectInput): Promise<Analysis>

A direct Analysis requires exactly one contentId, context: "submitted", and a target. inklet scales the image to the target geometry server-side, which is what Hardcode Push uses underneath.

create()

create(input: CreateAnalysisRequest, idempotencyKey: string): Promise<Analysis>

The same request with mode explicit and the key required — analyze() and direct() are wrappers over it that generate a key when you do not supply one.

Targets

type AnalysisTargetInput =
  | { displayId: string }
  | { displayIds: readonly string[] }
  | { output: PresentationOutputRequest };

Exactly one of the three keys, or ConfigurationError. Omitting target entirely is the fourth option, and the one that lets the agent route for you.

An { output } target produces a display-free Presentation — Scene JSON and PNG renditions, no panel involved. See Generating without a display.

retrieve() and list()

const analysis = await inklet.analyses.retrieve("analysis_123");

const page = await inklet.analyses.list({
  state: "completed",
  trigger: "scheduled",
  limit: 20,
});

trigger is api for the ones you started and scheduled for the ones inklet runs on the user's behalf. An out-of-range state, trigger, or limit throws ConfigurationError locally.

wait()

wait(
  analysisOrId: Analysis | string,
  options?: WaitForAnalysisOptions,
): Promise<Analysis>

Polls until the Analysis is completed and returns it. A failed Analysis throws AnalysisFailedError, with the backend's own code on error.details.backendCode.

A state this SDK does not know is not treated as final. Up to three failed reads in a row — a dropped connection, a timeout, or HTTP 408, 429, 500, 502, 503, or 504 — are retried with back-off before the error is thrown.

The Analysis type

States

queued ──→ running ──→ completed
                   └─→ failed

queued and running are not terminal; completed and failed are. See Lifecycle.

Outcome

outcome is null until the Analysis finishes, then one of two answers.

no_change is a normal completion, not a failure, and it is only reachable when the Analysis named no contentIds. Name a Content and inklet either covers it or fails the Analysis with no_presentable_content.

Scope and the history window

since is resolved to an absolute sinceAt when the Analysis is created, so an Analysis that sits in queued still reads the window it was created with. The plan caps how far back history reaches, and an earlier since is clamped to that floor rather than rejected — compare scope.sinceAt against what you asked for when you need to tell a user how much was really covered. See Plans.

Following a run

An Analysis publishes an ordered event stream while it works. It has its own page:

archive()

const { url, expiresAt } = await inklet.analyses.archive("analysis_123");

A short-lived download URL for the run archive. Throws NotFoundError with code: "archive_not_found" when there is none — while the Analysis is still running, or after retention has expired.