Skip to main content

​
API Reference

Use this page when you are integrating from a language without a first-party SDK. The generated endpoint reference is built from openapi.yaml, which is a symlink to the repository’s canonical specs/openapi.yaml contract.
Nullspace does not ship a first-party JavaScript or TypeScript SDK yet. The JavaScript examples below use the platform fetch API against the raw HTTP contract.

​
Setup

export NULLSPACE_API_KEY=ns_live_...
export NULLSPACE_API_URL=https://api.your-nullspace-domain
The API expects a bearer token on customer-facing routes: 
Authorization: Bearer ${NULLSPACE_API_KEY}

​
Create A Sandbox

SANDBOX_JSON="$(
  curl -fsS -X POST "${NULLSPACE_API_URL}/v1/sandboxes" \
    -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
    -H "Content-Type: application/json" \
    --data '{"template":"base","timeout_ms":300000}'
)"

SANDBOX_ID="$(printf '%s' "${SANDBOX_JSON}" | jq -r '.id')"
echo "${SANDBOX_ID}"

const apiUrl = process.env.NULLSPACE_API_URL;
const apiKey = process.env.NULLSPACE_API_KEY;

const createResponse = await fetch(`${apiUrl}/v1/sandboxes`, {
  method: "POST",
  headers: {
    authorization: `Bearer ${apiKey}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({ template: "base", timeout_ms: 300_000 }),
});

if (!createResponse.ok) {
  throw new Error(await createResponse.text());
}

const sandbox = await createResponse.json();
console.log(sandbox.id);

​
Execute A Command

curl -fsS -X POST "${NULLSPACE_API_URL}/v1/sandboxes/${SANDBOX_ID}/exec" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"command":"echo hello from nullspace","shell":true,"timeout_secs":30}'

const execResponse = await fetch(`${apiUrl}/v1/sandboxes/${sandbox.id}/exec`, {
  method: "POST",
  headers: {
    authorization: `Bearer ${apiKey}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    command: "echo hello from nullspace",
    shell: true,
    timeout_secs: 30,
  }),
});

const execResult = await execResponse.json();
console.log(execResult.stdout);

​
Expose A Port

Start a background process, then request signed preview URL metadata for the port: 
curl -fsS -X POST "${NULLSPACE_API_URL}/v1/sandboxes/${SANDBOX_ID}/exec" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"command":"cd /workspace && python3 -m http.server 8080","shell":true,"background":true}'

curl -fsS -X POST "${NULLSPACE_API_URL}/v1/sandboxes/${SANDBOX_ID}/host" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}" \
  -H "Content-Type: application/json" \
  --data '{"port":8080}'

await fetch(`${apiUrl}/v1/sandboxes/${sandbox.id}/exec`, {
  method: "POST",
  headers: {
    authorization: `Bearer ${apiKey}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({
    command: "cd /workspace && python3 -m http.server 8080",
    shell: true,
    background: true,
  }),
});

const hostResponse = await fetch(`${apiUrl}/v1/sandboxes/${sandbox.id}/host`, {
  method: "POST",
  headers: {
    authorization: `Bearer ${apiKey}`,
    "content-type": "application/json",
  },
  body: JSON.stringify({ port: 8080 }),
});

const host = await hostResponse.json();
console.log(host.url ?? host.host);

​
Destroy The Sandbox

curl -fsS -X DELETE "${NULLSPACE_API_URL}/v1/sandboxes/${SANDBOX_ID}" \
  -H "Authorization: Bearer ${NULLSPACE_API_KEY}"

await fetch(`${apiUrl}/v1/sandboxes/${sandbox.id}`, {
  method: "DELETE",
  headers: { authorization: `Bearer ${apiKey}` },
});

​
Response And Error Shape

Successful responses are JSON unless the endpoint explicitly documents a download stream or WebSocket upgrade. Errors use the standard error envelope documented in Error codes. Use API Reference Scope before building against account, Auth, admin, or operator-only routes. Use the API Reference section in the sidebar for endpoint schemas, generated examples, status codes, and field constraints.