# Quickstart: the API and the SDK

Shotcup runs JavaScript in a fresh, sandboxed GocciaScript engine per run and
answers with the output, a diff of the virtual filesystem and the files the
code wrote under `/out`.

## 1. Get an API key

Sign in at [shotcup.dev/dashboard](/dashboard) and create a key. The key
(`sk_…`) is shown once; Shotcup stores only its SHA-256 hash, so copy it
then. Every account starts on Free: 5 s per run,
32 MiB of JS heap, 1 run at a time, no network, and each month
30,000 runs and 3 h of compute included.
Run history is kept for Free 1 day, Pro 7 days, Scale 30 days, Platform 90 days.

## 2. Run code over HTTP

```sh
curl https://shotcup.dev/api/v1/runs \
  -H "Authorization: Bearer $SHOTCUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "console.log(\"hello from a sandbox\");"}'
```

The answer is `{ "run": { "status", "stdout", "stderr", "diff",
"artifacts", "metrics", "hint", ... } }`, and the `Server-Timing` header
says where the request's time went. Files the code writes under `/out`
come back as artifacts with a link:

```sh
curl https://shotcup.dev/api/v1/runs \
  -H "Authorization: Bearer $SHOTCUP_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"code": "import fs from \"fs\";\nfs.mkdirSync(\"/out\", { recursive: true });\nfs.writeFileSync(\"/out/hello.txt\", \"hi\");"}'
```

## 3. Mind the language profile

The engine runs modern JavaScript as ES modules in GocciaScript's default
profile: arrow functions, `const`/`let` and `for...of`; no `function`
keyword, `var`, `while` or C-style `for`, and no semicolon insertion at
line breaks. A run that trips over one of these fails with a `hint` that
says what to write instead. There is no npm and no Node API besides `fs`.

## 4. Connect an agent over MCP

The MCP server is `https://shotcup.dev/api/mcp/mcp` with the header
`Authorization: Bearer sk_…`. Claude Code:

```sh
claude mcp add --transport http shotcup https://shotcup.dev/api/mcp/mcp \
  --header "Authorization: Bearer sk_…"
```

The [MCP guide](/docs/mcp) covers Cursor, VS Code, Grok and Claude Desktop.

## 5. The TypeScript SDK

The SDK `shotcup` is a client of the hosted platform: every run happens on
Shotcup, nothing runs on your machine. It is not published to npm yet. Once it is:

```ts
import { createClient } from "shotcup";

const shotcup = createClient({ apiKey: process.env.SHOTCUP_API_KEY, baseUrl: "https://shotcup.dev" });
const run = await shotcup.runs.create({ code: 'console.log("hello")' });
console.log(run.status, run.stdout);
```

Until then the REST API above and MCP are the ways in.

## Limits and history

Plans and their limits are on the [pricing page](/pricing). Your runs,
their output, source, timings and artifacts are in the
[dashboard](/dashboard/runs) for as long as your plan keeps them.