Golden Image

What the SDK gives you

Data, state, files, AI, knowledge search, Runtime, connectors and jobs, all from the frontend. Look here before building a backend.

Need SDK Note
Store and read records ctx.data record_schema in the manifest. List filters are eq only; sort on the client
Key/value state ctx.storage.state state_namespaces + value_schema; key prefix filter
Files ctx.files Files people give, and blobs handed to other features (AI attachments, knowledge, conversion)
App-owned blobs ctx.storage.objects Logical keys and versions; declare in the manifest
AI ctx.api.ai.generate / stream / embeddings Tiers fast, smart, deep
Knowledge search (RAG) ctx.knowledge Chunking and embedding are the gateway's job
Other apps' capabilities and data ctx.api.capabilities.invoke, ctx.data.list("<provider>/<res>") capabilities.requires, resource_requests in the manifest
External tools (MCP) ctx.api.connectors.listTools / invoke An admin-registered connector + connector_requests
Long-running work ctx.api.runtime.start / subscribe / resume / cancel runtime_profiles
Waiting for jobs ctx.jobs.wait / subscribe / cancel Conversion, ingestion, backend jobs

AI

ts
const { text } = await ctx.api.ai.generate({
  profile: "smart",                                  // smart when omitted
  messages: [{ role: "user", content: "List the risky clauses in this contract" }],
  attachments: [{ fileId }],                         // attach files instead of pasting their content
  responseSchema: { type: "object", properties: { risks: { type: "array", items: { type: "string" } } } },
});

for await (const e of ctx.api.ai.stream({ profile: "fast", messages })) {
  if (e.type === "response.delta") append(e.delta);
}

Knowledge

ts
const file = await ctx.files.upload(selectedFile);
const queued = await ctx.knowledge.ingest(
  { collectionId: "review-documents", fileId: file.fileId, title: file.name, scope: "user_private" },
  { idempotencyKey: `ingest:${file.fileId}` },
);
await ctx.jobs.wait(queued.jobId);
const document = await ctx.knowledge.get(queued.documentId);
if (document.status !== "ready") throw new Error(document.error?.message ?? document.status);
const results = await ctx.knowledge.search({
  collections: ["review-documents"], documentIds: [document.documentId],
  query: "What requires approval?", topK: 6,
});
  • files.list, knowledge.list and files.artifactsPage return { items, nextCursor }; pass the cursor back unchanged.
  • A finished job isn't a success. Check the job's or document's status.
  • Reuse an Idempotency-Key only for the same request; another request with the same key is 409 idempotency_conflict.

Runtime

ts
const run = await ctx.api.runtime.start({ profile: "review", input: { question: "Summarize the uploaded report" } });
for await (const event of ctx.api.runtime.subscribe(run.runId, { transport: "sse", signal })) {
  // keep event.sequence to reconnect with afterSequence
}
const latest = await ctx.api.runtime.get(run.runId);

Question interrupts resume with decision: "submit" and an input matching inputSchema; approval and consent with "approve" / "deny". Ending a subscription is not cancelling the run (runtime.cancel).

Connectors and artifacts

ts
const { tools } = await ctx.api.connectors.listTools("search");
const result = await ctx.api.connectors.invoke("search", "find", { query: "report" });
const converted = await ctx.files.convert(file.fileId, "application/pdf");
const job = await ctx.jobs.wait(converted.jobId);
const generated = await ctx.files.artifacts({ jobId: job.jobId });

Behaviour and limits are covered in Mothership's AI, Knowledge, Runtime and automation and External tools and files.

Esc