Skip to content

Files and documents from a run

Which API lets an agent run code that produces PNG charts, PDFs or other files and returns them in the response? Shotcup's run API. The program writes its files under /out, and the answer to POST /api/v1/runs lists every one with its path, type and size: a file up to 32 KiB comes back inside the answer, and a file up to 16 MiB also gets a link. The MCP tools and the SDK answer the same way.

An artifact is a file the run hands back for people or programs, such as a chart, a PDF, a spreadsheet or a data file. It is not a build output.

Shell
curl https://shotcup.dev/api/v1/runs \
  -H "Authorization: Bearer $SHOTCUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"engine": {"canvas": true}, "entry": "/main.js", "code": "import { createCanvas } from \"shotcup:canvas\";\nconst chart = createCanvas(320, 160, \"#ffffff\");\nchart.fillRect(40, 40, 240, 80, \"#577111\");\nchart.save(\"/out/bar.png\");"}'

The answer's run.artifacts lists each file. This is the entry of the chart in the files below, recorded on 1 November 2026, its base64 and link cut short:

JSON
{
  "path": "/out/chart.png",
  "bytes": 29604,
  "contentType": "image/png",
  "inlineBase64": "iVBORw0KGgo…",
  "url": "https://shotcup.page/a/….png",
  "urlExpiresAt": "…"
}

What a run can write

FileWhat makes itWhere it is described
PNG, JPEGshotcup:canvas (engine: { canvas: true }): canvas.save("/out/chart.png"), toPNG(), toJPEG()Canvas
GIF, APNGshotcup:canvas: encodeGIF, encodeAPNG, saveAnimationCanvas: animation
SVG, and SVG rendered to PNGSVG is text the program writes; decodeImage of an SVG and .render() draws it into a canvasSVG
PDFa JavaScript writer sent with the runbelow
Word, Excel, PowerPointJavaScript writers sent with the run, on shotcup:zipbelow
ZIPshotcup:zip: zip(entries), and unzip(bytes) to read onebelow
HTML, Markdown, CSV, JSON, any textthe program writes the string; React or MDX render HTML from a copy sent with the runbelow
Any other bytesfs.writeFileSync(path, bytes) with a Uint8Array

Shotcup has no built-in PDF or Office module: those files come from code that travels with the run, so you can read and change it, and nothing is installed. A link serves its file with the type the file's extension names.

How a script writes a file

Anything the program writes under /out comes back with the answer. Create the directory first:

JavaScript
import fs from "fs";

fs.mkdirSync("/out", { recursive: true });
fs.writeFileSync("/out/summary.csv", "region,total\nDACH,39847.50\n");

Files elsewhere in the run's filesystem stay in the run: they show in its diff, not as artifacts. A canvas's save writes the file in one call, and a writer's bytes go out with fs.writeFileSync.

Images: PNG, JPEG, GIF and SVG

shotcup:canvas draws with a Canvas 2D context, real fonts and colour emoji, and encodes PNG, JPEG, GIF and APNG itself; it exists in a run that sends engine: { canvas: true }. It also reads SVG: decodeImage of an SVG file's bytes returns an image that drawImage takes and .render({ width }) turns into a canvas, so a run can write an SVG and hand back a PNG of it. The Canvas and SVG pages have every call and limit.

PDF, Word, Excel and PowerPoint

These files are written by JavaScript writers that you send with the run as files, next to the program. A PDF writer puts the document's objects and its cross-reference table into bytes; Word, Excel and PowerPoint files are zip archives of XML parts, so their writers build the parts and pack them with shotcup:zip. The launch templates carry small ones: lib/pdf.js in SVG, PDF and Markdown report (text, lines, rectangles and an image), lib/docx.js in Word report (.docx), lib/xlsx.js in Excel sheet (.xlsx) (strings, numbers and formulas with their cached values) and lib/pptx.js in PowerPoint deck (.pptx). The templates live in the @shotcup/templates package, which is not published to npm yet.

JavaScript
import fs from "fs";
import { buildXlsx } from "./lib/xlsx.js";

const bytes = buildXlsx({
  title: "Orders", author: "Shotcup", created: "2026-11-01T00:00:00Z",
  sheets: [{ name: "Orders", rows: [["Region", "Revenue"], ["DACH", 39847.5]] }],
});
fs.mkdirSync("/out", { recursive: true });
fs.writeFileSync("/out/orders.xlsx", bytes);

A link to a .docx, .xlsx, .pptx or .zip file downloads it instead of opening it in the browser.

ZIP

import { zip, unzip } from "shotcup:zip" needs no engine switch. zip([{ path, data }]) returns the archive's bytes, data as text or bytes; unzip(bytes) reads one (an upload, a URL import, a .docx) and refuses an archive that does not add up, naming the entry.

HTML, text and data

Text is the program's own string: CSV, JSON, Markdown or HTML written with fs.writeFileSync. A page rendered with React or MDX needs the library's copy sent with the run as files, as the React server-rendered document template does with React 19's renderToStaticMarkup. shotcup:html reads HTML and writes it as Markdown (HTML).

  • A file up to 32 KiB comes back inside the answer: inline as text when it is UTF-8, else inlineBase64.
  • Every file up to 16 MiB gets a url on Shotcup's artifact host, shotcup.page, which serves user files and nothing else. The link may answer 202 for a moment while a large file is stored.
  • A run's files carry at most 24 MiB of content together, counted as it travels (base64 is a third larger). A file past either limit comes back by path and size alone, and the run's warnings include artifact-content-omitted.
  • A run's files together stay within the plan's filesystem quota: Free 4 MiB, Pro 16 MiB, Scale 64 MiB, Platform 64 MiB.

A link is a capability URL: anyone holding it can fetch the file without your API key until the plan's retention ends (Free 1 day, Pro 7 days, Scale 30 days, Platform 90 days), so treat it as private. Send "artifacts": "private" with the run and the links answer only your API key (Authorization: Bearer); everyone else gets 404. With "retention": "none" nothing is kept: files come back inline only, and a larger one by path and size without a link.

Over MCP: images in the answer

The MCP tools answer with the run as text, every file with its link, and add each PNG, JPEG, GIF, WebP and APNG file under /out up to 1 MiB as an image the client can show, at most 4 of them. Private images still come back inline. The MCP guide has the tools.

The data goes to the run as a file

The data goes to the run as a file, never through the model: a short program turns a thousand rows into a chart, a report or a spreadsheet. The model writes the program; your code attaches the data, and only the program's output goes back to the model. A run gets files four ways:

  • in the request's files, as text or base64 ({ path, content, encoding });
  • as an upload: POST /api/v1/uploads gives an upload URL, and the request names the stored file as { path, upload }, which keeps large files out of the request body;
  • by URL: { path, url } is downloaded before the run, per file at most Free 2 MiB, Pro 10 MiB, Scale 12 MiB, Platform 12 MiB;
  • from a drive mounted into the run, read-only or read-write, with versions.

Files from real runs

Each file below came from a real run on Shotcup, recorded through the API, run twice with the same answer and the same bytes. A picture of a PNG, JPEG or GIF is the file itself; a PDF's page was rendered with pdftoppm, an Office file's first page with LibreOffice and an HTML page's top in Chromium, and a ZIP is shown as its listing.

PNG: a chart

The chart the run drew: revenue by region for the third quarter as bars, green where a region met its target and grey where it fell short, each with its target tick and value, and a total of 5,686.91
  • Made by: shotcup:canvas
  • Program: 87 lines; input: /data/revenue.json, 590 bytes
  • File: /out/chart.png, 29,604 bytes, inline in the answer and as a link
  • A real run on 1 November 2026. The picture: the file itself.

JPEG: a card with real fonts and colour emoji

The card the run drew: Release 4.2, the headline Real fonts and colour emoji for every chart, badge and card you render, a line of code, and colour emoji, flags and keycaps along the foot
  • Made by: shotcup:canvas
  • Program: 76 lines; input: /data/release.json, 498 bytes
  • File: /out/card.jpg, 84,920 bytes, as a link
  • A real run on 1 November 2026. The picture: the file itself.

GIF: an animation

An animation: a paper cup with a green band filling with espresso, frame by frame
  • Made by: shotcup:canvas
  • Program: 36 lines; input: none, the data is in the program
  • File: /out/cup.gif, 27,800 bytes, inline in the answer and as a link
  • A real run on 1 November 2026. The picture: the file itself.

SVG to PNG: an SVG, rendered

The SVG rendered to PNG: Runs this week, a ring at 88 per cent and six green bars for Monday to Saturday
  • Made by: shotcup:canvas
  • Program: 8 lines; input: /art/runs.svg, 1,375 bytes
  • File: /out/runs.png, 25,721 bytes, inline in the answer and as a link
  • A real run on 1 November 2026. The picture: the file itself, the PNG the run rendered from the SVG.

PDF: a one-page report

The PDF's page: Quarterly sales report for the third quarter, with a bar and a euro total for each of five regions, DACH the longest in green
  • Made by: a JavaScript writer sent with the run (lib/pdf.js)
  • Program: 25 lines; input: /data/quarter.json, 914 bytes
  • File: /out/quarter.pdf, 2,015 bytes, inline in the answer and as a link
  • A real run on 1 November 2026. The picture: its page, rendered with pdftoppm and cropped.

Word: a quarterly report

The Word document's first page: Quarterly sales report, a summary paragraph and a table of revenue by region with a total of 119,454.50 euros
  • Made by: a JavaScript writer sent with the run (lib/docx.js, on shotcup:zip)
  • Program: 64 lines; input: /data/quarter.json, 914 bytes
  • File: /out/report.docx, 3,713 bytes, inline in the answer and as a link
  • A real run on 1 November 2026. The picture: its first page, rendered with LibreOffice and cropped.

Excel: a sheet with formulas

The workbook's sheet: six products by region with units, unit price and revenue, and a total row of 1,920 units and 17,045.70
  • Made by: a JavaScript writer sent with the run (lib/xlsx.js, on shotcup:zip)
  • Program: 56 lines; input: /data/sales.json, 611 bytes
  • File: /out/sales.xlsx, 3,591 bytes, inline in the answer and as a link
  • A real run on 1 November 2026. The picture: its sheet, rendered with LibreOffice and cropped.

PowerPoint: a four-slide deck

The deck's first slide: Office files from a sandbox, with a sky blue rule under the title and the subtitle Word, Excel and PowerPoint written by a script with shotcup:zip
  • Made by: a JavaScript writer sent with the run (lib/pptx.js, on shotcup:zip)
  • Program: 19 lines; input: /data/deck.json, 1,039 bytes
  • File: /out/deck.pptx, 9,878 bytes, inline in the answer and as a link
  • A real run on 1 November 2026. The picture: its first slide, rendered with LibreOffice.

ZIP: an export of three files

text
orders.csv  42,405 bytes
by-region.json  159 bytes
README.txt  32 bytes
  • Made by: shotcup:zip
  • Program: 20 lines; input: /data/orders.csv, 42,405 bytes
  • File: /out/orders-export.zip, 7,061 bytes, inline in the answer and as a link
  • A real run on 1 November 2026. The picture: its listing, read from the file.

HTML: a page rendered with React

The HTML page's top in a browser: Service health report, a summary row with a ring, a sparkline and flags, a bar chart of traffic by service and the start of a table of services
  • Made by: React 19, sent with the run
  • Program: 105 lines; input: none, the data is in the program
  • File: /out/static.html, 12,848 bytes, inline in the answer and as a link
  • A real run on 1 November 2026. The picture: the top of the page, opened in Chromium.

From a thousand rows

Both runs were sent the same thousand orders as /data/orders.csv in the request's files.

PNG: a chart from a thousand orders

The chart the run drew: revenue by month from January to October across 1000 orders, rising from 5k in January to 24k in October, October in green
  • Made by: shotcup:canvas
  • Program: 32 lines; input: /data/orders.csv, 42,405 bytes
  • File: /out/revenue-by-month.png, 14,370 bytes, inline in the answer and as a link
  • A real run on 1 November 2026. The picture: the file itself.

Excel: a workbook from the same thousand orders

The workbook's first sheet: six regions with their number of orders and revenue, from Benelux with 149 orders to the UK with 156
  • Made by: a JavaScript writer sent with the run (lib/xlsx.js, on shotcup:zip)
  • Program: 33 lines; input: /data/orders.csv, 42,405 bytes
  • File: /out/orders.xlsx, 43,542 bytes, as a link
  • A real run on 1 November 2026. The picture: its first sheet, rendered with LibreOffice and cropped.

This page as Markdown: /docs/artifacts.md