Resources
The five resources hanging off a Convilyn client: files, convert, goals, workflows, and account.
files — upload
Register a file before converting it or feeding it to a goal.
const fromPath = await client.files.upload({ path: "a.pdf" }); // Node
const fromBytes = await client.files.upload({
content: bytes,
filename: "a.pdf",
}); // browser-safeconvert — document conversion
Single-step document conversion jobs.
const job = await client.convert.create({ file, targetFormat: "pdf" });
const done = await client.convert.wait(job.jobId); // poll to terminal
const url = await client.convert.downloadUrl(done); // presigned URL
await client.convert.downloadTo(done, { to: "out.pdf" }); // Node: stream to diskcreateAndWait is the create + wait shortcut. A failed job throws JobFailedError; an elapsed deadline throws JobTimeoutError.
goals — agentic goal workflows
Multi-step agentic workflows. wait stops at a terminal status or at a human-in-the-loop (HITL) slot.
const job = await client.goals.start({
goalText: "Summarise this",
files: [file.fileId],
});
const state = await client.goals.wait(job.jobSpecId); // stops at terminal OR a HITL slot
if (state.status === "slots_pending") {
await client.goals.fillSlot(state.jobSpecId, {
slotId: state.pendingSlots[0]!.slotId,
value: "March 2026",
});
await client.goals.confirm(state.jobSpecId);
}Other methods: retrieve, run (start + wait), fillSlots, cancel, retry, and events().
start (and run) accept an optional llmConfigId to run the job on one of your
stored BYO-LLM provider configs (created in the console); omit it to use your
account default. It is honoured only when BYO-LLM is enabled for your account —
otherwise the run uses the platform provider.
WebSocket events
goals.events() streams live execution events as an async iterator:
for await (const event of client.goals.events(job.jobSpecId)) {
console.log(event.type, event.data); // 'tool_started' | 'progress' | 'completed' | …
}workflows — community marketplace
Search, fork, publish, and like community workflows. fork and publish are Pro-tier.
const page = await client.workflows.search({ tag: "finance", sort: "popular" });
const wf = await client.workflows.get(page.items[0]!.workflowId);
const mine = await client.workflows.fork({
sourceSpecId: wf.specId,
name: "My copy",
}); // Pro
await client.workflows.publish(mine.workflowId, {
itemVersion: mine.itemVersion,
}); // Pro
await client.workflows.like(wf.workflowId);account — plan, cost preview & usage (read-only)
const plan = await client.account.getPlan(); // { tier: 'free' | 'pro' }
const estimate = await client.account.getQuota({
tools: ["pdf-mcp:extract_text"],
});
console.log(estimate.estimatedCredits, estimate.quotaCheck.state);
const history = await client.account.usageHistory({
since: new Date("2026-06-01"),
});