API reference
Every endpoint takes and returns JSON over HTTPS. Send your key in the Authorization header.
Authentication
Send your key as Authorization: Bearer followed by the key. BoxAI issues keys on request.
Authorization: Bearer <your key>
Limits
Up to 500 records per table in a seed. Up to 50 files per box by default, 512 KB each. Up to 20,000 characters per script, and 4 MB of files loaded per run. Daily executions depend on your plan.
Errors
Errors return JSON with an error code, for example unauthorized, not_found or daily_limit_reached.
{ "error": "daily_limit_reached" }
Create a box
Creates an empty box and returns its ID.
Response
{ "sandboxId": "k3j9f0a2b7qz" }
Seed with UAE data
Writes synthetic UAE customers, transactions and invoices as JSON files into a box.
Request
{ "sandboxId": "k3j9f0a2b7qz", "preset": "uae-fintech", "count": 50, "tables": ["customers", "invoices"] }
Response
{ "seeded": { "customers": 50, "invoices": 50 }, "files": ["customers.json", "invoices.json"] }
Execute a script
Runs a JavaScript script in a box. Files the script writes are saved to the box.
Request
{ "sandboxId": "k3j9f0a2b7qz", "code": "const c = JSON.parse(readFile(\"customers.json\"));\nconsole.log(c.length);" }
Response
{ "stdout": "50\n", "stderr": "", "exitCode": 0, "durationMs": 4, "filesWritten": [] }
Write a file
Creates or replaces a UTF-8 file in a box.
Request
{ "sandboxId": "k3j9f0a2b7qz", "filename": "notes.txt", "content": "hello" }
Response
{ "ok": true, "name": "notes.txt", "size": 5 }
Read a file
Returns the content of one file in a box.
Response
{ "name": "notes.txt", "size": 5, "content": "hello" }
List files
Lists the files in a box with their sizes.
Response
{ "files": [ { "name": "notes.txt", "size": 5, "uploadedAt": 1791917642179 } ] }
List boxes
Lists your active boxes with file counts and last execution time.
Response
{ "boxes": [ { "id": "k3j9f0a2b7qz", "created_at": 1791917642179, "files_count": 2, "last_execution_at": null } ] }
List executions
Lists the most recent runs of one box, with output and exit code.
Response
{ "executions": [ { "id": "7ca87ea5", "stdout": "50\n", "stderr": "", "exit_code": 0, "duration_ms": 4, "created_at": 1791918270555 } ] }
Usage
Returns today's executions, your plan limit, and file counts across your boxes.
Response
{ "executions_today": 3, "executions_month": 41, "executions_limit": 100, "files_count": 6, "files_size_bytes": 4878, "plan": "free" }
Delete a box
Deletes a box's files and run history. Daily usage counts are kept.
Response
{ "ok": true }
Demo run
Runs one script with no key, no files and no storage. Three runs a day per IP address.
Request
{ "code": "console.log(2 + 3)" }
Response
{ "stdout": "5\n", "stderr": "", "exitCode": 0, "durationMs": 1, "runsLeft": 2 }