Lifecycle

A push is a request, not a render. The call returns as soon as inklet has your assets; reading, planning, and rendering happen after — and a display only shows the result once it wakes and confirms it.

This page is the difference between "the call succeeded" and "it is on the wall".

Three objects, in order

Content  ──→  Analysis  ──→  Presentation  ──→  the panel
(storage)     (the work)     (the result)       (delivery)

Uploading spends nothing. A Content sits in storage until an Analysis references it, which is the call that actually does work.

Content states

pending ──→ ready
        └─→ failed

Text and link Contents are ready immediately. Binary assets are pending until inklet has verified the uploads.

Analysis states

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

completed has two outcomes. presentations means presentationIds is populated; no_change means the agent looked and decided nothing was worth showing, with noChangeReason saying why. no_change 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.

Presentation states

The two kinds of Presentation use two vocabularies. A generated Presentation has no panel, so most of the delivery words do not apply to it.

generated:  preparing ──→ ready
                      └─→ failed

display:    preparing ──→ queued ──→ published ──→ confirmed
                                               └─→ expired
                                               └─→ failed

Waiting for it

const analysis = await inklet.analyze({ contentIds: [content.id] });

const done = await inklet.analyses.wait(analysis, { timeoutMs: 120_000 });

if (done.outcome === "no_change") {
  console.log("nothing worth showing:", done.noChangeReason);
} else {
  console.log("presentations:", done.presentationIds);
}

for (const id of done.presentationIds) {
  const presentation = await inklet.presentations.retrieve(id, { format: "png" });
  const url = presentation.renditions[0]?.url ?? presentation.image?.url;

  if (url) console.log(url);
}

await inklet.displays.waitUntilCurrent(display.id, presentationId, {
  timeoutMs: 10 * 60_000,
});

Watching instead of polling

Every Analysis publishes an ordered event stream while it works, and watch() ends on its own once the run is terminal:

import { describeEvent } from "@inklethq/sdk";

for await (const event of inklet.analyses.watch(analysis.id)) {
  console.log(describeEvent(event));
}

The stream is a progress report, not the run's log: what the agent was given, what it is working on, what it planned, and how the result was rendered and delivered. Individual tool calls and model text are not part of it.

Idempotency

POST /contents and POST /analyses both require an Idempotency-Key header. The SDK generates one when you do not supply it, and returns the key it used:

const { content, idempotencyKey } = await inklet.contents.upload({ assets });
const result = await inklet.push.auto({ assets });

console.log(result.idempotencyKey); // "sdk-4f3c…"

push.* and presentations.generate() reuse one key for both the Content and the Analysis they start from it. The two endpoints keep separate key namespaces, so the same string means two different things on each.

To make your own retries safe, supply and reuse your own key:

const key = `daily-brief-${new Date().toISOString().slice(0, 10)}`;

await inklet.push.auto({ idempotencyKey: key, assets });
await inklet.push.auto({ idempotencyKey: key, assets }); // same push, not a second one

Keys must be 8–128 printable ASCII characters with no spaces. Anything else throws a ConfigurationError locally, and would be a 400 at the service.

Keys are remembered for 24 hours.

Retrying a call that failed

The SDK never retries a call that creates or changes something on its own. A call that fails after sending — a timeout, a dropped connection, a 5xx — may already have created something, so retry it with the key it used, not a fresh one. Every error such a call throws carries that key, including one the SDK generated:

import { NetworkError } from "@inklethq/sdk";

try {
  await inklet.push.auto({ assets });
} catch (error) {
  if (error instanceof NetworkError && error.idempotencyKey) {
    // Same input, same key: picks up what the first attempt created.
    await inklet.push.auto({ assets, idempotencyKey: error.idempotencyKey });
  } else {
    throw error;
  }
}

Uploads, retries, and missing assets

For binary assets, contents.upload() — and therefore push.* — does more than one round trip:

If assets are still missing after that, the SDK throws:

import { AssetUploadError } from "@inklethq/sdk";

try {
  await inklet.push.manual({ displayId, assets });
} catch (error) {
  if (error instanceof AssetUploadError) {
    console.error(error.contentId, error.failedAssetIndexes, error.cause);
  }
}

failedAssetIndexes maps back to the positions in the array you passed, so you can identify exactly which files did not make it; cause is the underlying failure of the first one. The error carries idempotencyKey too, so calling again with it picks the same Content back up.