API documentation

Run untrusted Python, JavaScript, Java and C++ code from your product with one REST API. Send source code and stdin; get stdout, stderr, compiler output and exit codes from an isolated sandbox with no network access.

Overview

Executions are asynchronous: POST /v1/executions returns 202 immediately with an executionId; poll GET /v1/executions/{executionId} until the status is terminal.

Base URL: https://api.tatvastack.com

Quickstart

1. Sign in to the dashboard and create an API key under API keys. It is shown once; store it on your server.
2. Submit code, then poll for the result:

export CODEFORGE_API_KEY=cf_live_...   # from the dashboard

curl -s -X POST https://api.tatvastack.com/v1/executions \
  -H "Authorization: Bearer $CODEFORGE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"language":"python","source":"print(input()[::-1])","stdin":"hello"}'
# {"executionId":"exe_…","status":"QUEUED","createdAt":"…","statusUrl":"/v1/executions/exe_…"}

curl -s https://api.tatvastack.com/v1/executions/exe_… \
  -H "Authorization: Bearer $CODEFORGE_API_KEY"
# {"executionId":"exe_…","status":"SUCCEEDED","stdout":"olleh\n","exitCode":0, …}

import os, time, uuid, requests

API = "https://api.tatvastack.com"
HEADERS = {"Authorization": f"Bearer {os.environ['CODEFORGE_API_KEY']}"}

def run(language, source, stdin=""):
    r = requests.post(f"{API}/v1/executions", json={"language": language, "source": source, "stdin": stdin},
                      headers={**HEADERS, "Idempotency-Key": str(uuid.uuid4())}, timeout=10)
    r.raise_for_status()
    execution_id = r.json()["executionId"]
    while True:
        result = requests.get(f"{API}/v1/executions/{execution_id}", headers=HEADERS, timeout=10).json()
        if result["status"] not in ("QUEUED", "RUNNING"):
            return result
        time.sleep(0.75)

result = run("python", "print(sum(range(10)))")
print(result["status"], result["stdout"])   # SUCCEEDED 45

// Node.js 18+ (built-in fetch)
const API = 'https://api.tatvastack.com';
const headers = { Authorization: `Bearer ${process.env.CODEFORGE_API_KEY}`, 'Content-Type': 'application/json' };

async function run(language, source, stdin = '') {
  const res = await fetch(`${API}/v1/executions`, {
    method: 'POST',
    headers: { ...headers, 'Idempotency-Key': crypto.randomUUID() },
    body: JSON.stringify({ language, source, stdin }),
  });
  if (!res.ok) throw new Error((await res.json()).error.message);
  const { executionId } = await res.json();
  for (;;) {
    const result = await (await fetch(`${API}/v1/executions/${executionId}`, { headers })).json();
    if (!['QUEUED', 'RUNNING'].includes(result.status)) return result;
    await new Promise((r) => setTimeout(r, 750));
  }
}

const result = await run('javascript', 'console.log(6 * 7)');
console.log(result.status, result.stdout); // SUCCEEDED 42

Authentication

Send your key as a bearer token: Authorization: Bearer cf_live_…. Keys belong to your account; revoking one in the dashboard rejects it on the next request. Never put an API key in browser or mobile code: call CodeForge from your backend.

Languages & runtimes

name = input()
print(f"Hello, {name}!")

const name = require('fs').readFileSync(0, 'utf8').trim();
console.log(`Hello, ${name}!`);

import java.util.Scanner;

public class Main {
    public static void main(String[] args) {
        System.out.println("Hello, " + new Scanner(System.in).nextLine() + "!");
    }
}

#include <iostream>
#include <string>
int main() {
    std::string name;
    std::getline(std::cin, name);
    std::cout << "Hello, " << name << "!" << std::endl;
}

Standard library only: no package installation and no network access. Java: put main in any class; the file is named after your public class automatically. Java and C++ are compiled first; compiler errors return COMPILE_ERROR with compileOutput.

Execution lifecycle

QUEUED/RUNNING are in progress; the rest are terminal.

• SUCCEEDED: exited with code 0.
• COMPILE_ERROR: Java/C++ failed to compile; see compileOutput.
• RUNTIME_ERROR: non-zero exit, exception or crash; see stderr and exitCode.
• TIMED_OUT: exceeded limits.timeMs.
• PLATFORM_ERROR: our failure. Not charged; retry.

Poll every 500–1000 ms; polling does not use quota. Measured median time from request to result for a short program on a warm sandbox, from a client in India to us-east-1: Python 966 ms, JavaScript 900 ms, Java 1.3 s, C++ 846 ms (Java and C++ include compilation). The first run after an idle period starts a fresh sandbox and can take a few seconds longer.

Retries & idempotency

Send an Idempotency-Key header (a UUID per logical request) with every POST, and retry with the same key: you get the original execution back (header Idempotent-Replayed: true), with no second run and no extra charge. Reusing a key with a different body returns 409 IDEMPOTENCY_CONFLICT. Keys are remembered for 24 hours.

Limits & quotas

Every accepted POST counts as one run, except executions that end in PLATFORM_ERROR, which are refunded. Rejected requests (4xx) are never charged. Check usage with GET /v1/usage or in the dashboard. Responses include X-Quota-Limit and X-Quota-Remaining.

Errors

Every error has the same shape. Include requestId (also in the X-Request-Id header) when contacting support at bhaskar@tatvastack.com.

{
  "error": {
    "code": "CONCURRENCY_LIMIT",
    "message": "Your free plan allows 1 execution at a time. …",
    "requestId": "req_…",
    "retryable": true
  }
}

Data retention

Sandbox & security

Each language runs in its own isolated micro-VM-based sandbox with no network route out (no internet, no DNS), no cloud credentials, process and memory limits, a wall-clock kill, and capped output. Jobs are encrypted for the sandbox and results are signed, and leftover files and processes are removed between runs. During the beta, CodeForge is invite-only while an independent security review is completed; we make no certification claims.

API reference

Machine-readable spec: OpenAPI 3.1 (JSON). Import it into Postman, Insomnia or a client generator.