Tools Test

Test a small program against a package without running it on the caller’s machine. The endpoint creates an isolated Upstash Box, installs the listed packages, writes your files, runs the entry file, and returns structured stdout/stderr. The response includes a sessionId you can pass on the next call to reuse the same box. The box is paused between runs so it has no hard TTL.

Endpoint

POST /tools/test

Base URL:

https://api.useagents.site

Pass config and secrets through optional env as { name, value?, secret? }. Each item needs a value or a secret. Logs store env names only. The sandbox allows outbound network so live vendor API calls can run. JavaScript and TypeScript (runtime: node) use the Bun runtime to add packages and run files. Pass sessionId from a previous result to reuse the same sandbox. The box is paused between runs and has no hard TTL.

Request body

Field	Type	Required	Description
`language`	string	Yes	Snippet language, for example `typescript` or `python`
`runtime`	string	Yes	`node`, `python`, `golang`, `ruby`, or `rust`
`files`	array	Yes*	1–20 objects with `path` (relative) and `code`. Required unless `sessionId` is set
`packages`	string[]	No	Package names to install (`bun add`, `pip install`, `go get`, `gem install`, or `cargo add`)
`entry`	string	No	File to execute. Defaults to the first `files` path. Required when `files` is empty
`sessionId`	string	No	Previous `test_tool` session. Reuses packages and files; the box is paused between runs
`slug`	string	No	Registry slug this snippet is testing (used for analytics)
`env`	array	No	Optional `{ name, value?, secret? }` pairs. Omit or pass `[]` for none
`timeoutMs`	number	No	Wall-clock timeout, 1000–60000. Default 30000

Query parameter format is json (default) or toon, same as the other tools endpoints.

Example request

curl -X POST "https://api.useagents.site/tools/test" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "resend",
    "language": "typescript",
    "runtime": "node",
    "packages": ["resend"],
    "env": [{ "name": "RESEND_API_KEY", "secret": "re_test" }],
    "files": [
      {
        "path": "src/index.ts",
        "code": "import { Resend } from \"resend\";\nconsole.log(typeof new Resend(\"re_test\").emails.send);\n"
      }
    ]
  }'

Response

Field	Description
`ok`	`true` when `status` is `ran`
`status`	`ran`, `failed_install`, `failed_run`, `timeout`, `blocked`, or `unavailable`
`phases`	Timing for provision, install, and run
`stdout` / `stderr`	Truncated to 8 KB and redacted
`sessionId`	Returned session to pass on the next call
`sessionExpiresAt`	Always `null` for durable paused boxes
`sessionReused`	`true` when this call attached to an existing session
`error`	Present when the sandbox or input is invalid

A failed snippet is still HTTP 200 with ok: false. HTTP 422 is invalid input. HTTP 503 means the sandbox provider is unavailable. HTTP 429 is the dedicated 5 requests/minute limiter.

Typical workflow

Call GET /tools/search.
Call GET /tools/context/:slug for install and usage context.
Write a small program from that context.
Call POST /tools/test with runtime, packages, and files.

Getting Started

Endpoints

Endpoint

Request body

Example request

Response

Typical workflow

​Endpoint

​Request body

​Example request

​Response

​Typical workflow

​Related

Endpoint

Request body

Example request

Response

Typical workflow

Related