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.listandfiles.artifactsPagereturn{ 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-Keyonly for the same request; another request with the same key is409 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.