inklet Portal SDK

Pipeline

A Content is what you sent. An Analysis is what inklet did with it.

Uploading and analyzing are separate steps. A Content is just the stored assets: no AI runs and nothing is spent until an Analysis references it. The Analysis produces Presentations, and a display shows one once it wakes and confirms it. Waiting returns when the run is over, or throws with the backend's code when it failed.

Events

Watch the agent work, as it works.

An Analysis publishes an ordered event stream: what the agent was given, what it is reading, what it planned, and how the result was rendered and delivered — or, for a question, the answer as it is written. It streams over server-sent events, resumes from the last event if the connection drops, falls back to polling behind a proxy that cannot stream, and ends on its own when the run does. Every event also reads as one plain English line, ready to put in front of a person.

• Acceptedanalysis.createdanalysis.dispatchedanalysis.leasedanalysis.lease_expired
• Workingcontext.materializedagent.activity
• Planningplan.submittedplan.rejectedplan.accepted
• Resultrender.finishedrender.faileddelivery.publisheddelivery.confirmeddelivery.failed
• Finishedanalysis.completedanalysis.failed
• Ask inkletassistant.deltaassistant.citationaction.card_createdaction.display_switched

A progress report, not the run's log. The agent's own working notes — each tool call, its arguments, the model's text — are not part of the public API at any depth, so a UI built on the stream survives a release that changes nothing you can see. The Result row lands after the run is already over, days later for a sleeping panel; read it back from the timeline.

Ask

A conversation with everything you saved.

A Conversation is a chat with the knowledge base. Every message starts one round: the agent searches and reads the notes, answers with the ones it drew on, and — only when asked to — starts a card or puts an earlier Presentation back on a display. Behind each answer is an ordinary Analysis with mode chat, so the same event stream applies, and chat rounds stay out of the history of cards unless you ask for them.

• reply()Sends, then follows the round until the answer is final
• send()Returns the reply's analysisId at once, for your own watch()
• retrieve()A Conversation with its last fifty Messages
• listMessages({ before })Pages further back
• rename() · delete()A manual title is never replaced by automatic naming

Asking is a Pro capability. A message is trimmed and refused before any request if it is blank or longer than 4,000 characters, and a second message while the previous round is still running is a conflict rather than a queue.

Switch the image on a display

Pick what is on the panel by hand. Any Presentation that has already been delivered there and rendered can go back up — including one that has expired — or you can simply move to the next queued one. Both land as pending until the panel confirms, and a panel's full history is one list call away.

// Everything this panel has shown before, newest first.
const shown = await inklet.presentations.list({
  displayId,
  state: "expired",
});

// Put an earlier card back. It confirms on its next sync.
const previous = shown.items[0].id;
await inklet.displays.setCurrent(displayId, previous);
await inklet.displays.waitUntilCurrent(displayId, previous);

// Or just move on to whatever is queued next.
const { changed } = await inklet.displays.advance(displayId);

Generate a Presentation without a display

For software-only surfaces — a widget, a screensaver, a test. Generating is an upload plus an analysis with an output target: it registers nothing, queues nothing, and produces versioned Scene JSON with PNG renditions. Hand it a finished image instead and no AI runs at all. A stored Scene renders again at another size without a second AI run.

const generation = await inklet.presentations.generate({
  intent: "Create a calm, glanceable summary",
  assets: [
    inklet.assets.text("Revenue increased 12% this week."),
  ],
  output: {
    preset: "macos-widget-medium",
    formats: ["scene", "png"],
  },
});

const presentation =
  await inklet.presentations.waitUntilReady(generation);
console.log(presentation.scene?.data);
console.log(presentation.renditions[0]?.url);

// Another size from the same Scene. No second AI run.
await inklet.presentations.render(presentation.id, {
  viewport: { width: 720, height: 340 },
});