{ "openapi": "3.1.0", "info": { "title": "CodeForge Execution API", "version": "1.0.0-beta", "summary": "Run untrusted Python, JavaScript, Java and C++ code in isolated, network-free sandboxes.", "description": "Submit source code and optional stdin, receive an execution ID immediately, then poll for the result.\n\nExecutions are asynchronous: `POST /v1/executions` returns `202` with status `QUEUED`; poll `GET /v1/executions/{executionId}` until the status is terminal.\n\n**Beta:** CodeForge is in private beta. Limits and runtime versions may change; changes are announced before they take effect.", "contact": { "name": "CodeForge support" } }, "servers": [ { "url": "https://api.tatvastack.com", "description": "Beta (us-east-1)" } ], "security": [{ "apiKey": [] }], "tags": [ { "name": "Executions", "description": "Submit code and read results." }, { "name": "Usage", "description": "Quota and usage for your account." } ], "paths": { "/v1/executions": { "post": { "tags": ["Executions"], "operationId": "createExecution", "summary": "Submit code for execution", "description": "Queues one execution. Counts as one run against your monthly allowance and occupies one concurrency slot until it finishes.\n\nSend an `Idempotency-Key` to make retries safe: the same key with the same request returns the original execution without a new run or charge.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Unique key for this logical request (recommended: a UUID). Valid for 24 hours. Reusing it with a different request body returns `409`.", "schema": { "type": "string", "pattern": "^[A-Za-z0-9._:-]{1,255}$" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionRequest" }, "examples": { "python": { "summary": "Python with stdin", "value": { "language": "python", "source": "name = input()\nprint(f\"Hello, {name}!\")", "stdin": "World" } }, "java": { "summary": "Java", "value": { "language": "java", "source": "public class Main {\n public static void main(String[] args) {\n System.out.println(\"Hello from Java\");\n }\n}" } }, "timeLimit": { "summary": "Custom time limit", "value": { "language": "cpp", "source": "#include \nint main(){ std::cout << 42 << std::endl; }", "limits": { "timeMs": 2000 } } } } } } }, "responses": { "202": { "description": "Accepted and queued (or an idempotent replay of an earlier request).", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" }, "X-Quota-Limit": { "description": "Monthly run allowance.", "schema": { "type": "integer" } }, "X-Quota-Remaining": { "description": "Runs left this month after this one.", "schema": { "type": "integer" } }, "Idempotent-Replayed": { "description": "`true` when this response replays an earlier request with the same Idempotency-Key.", "schema": { "type": "string", "enum": ["true"] } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExecutionAccepted" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "409": { "$ref": "#/components/responses/IdempotencyConflict" }, "413": { "$ref": "#/components/responses/PayloadTooLarge" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/executions/{executionId}": { "get": { "tags": ["Executions"], "operationId": "getExecution", "summary": "Get an execution's status and result", "description": "Poll until `status` is terminal (anything other than `QUEUED` or `RUNNING`). Polling does not use quota. A sensible interval is 500–1000 ms. Results are kept for 24 hours after submission and then deleted; after that this returns `404`. Source code and stdin are deleted as soon as the execution finishes.", "parameters": [ { "name": "executionId", "in": "path", "required": true, "schema": { "type": "string", "pattern": "^exe_[a-f0-9]{32}$" } } ], "responses": { "200": { "description": "The execution.", "headers": { "X-Request-Id": { "$ref": "#/components/headers/RequestId" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Execution" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/usage": { "get": { "tags": ["Usage"], "operationId": "getUsage", "summary": "Get quota and usage", "description": "This month's allowance and usage, current concurrency, and a daily breakdown for the last 30 days (UTC).", "responses": { "200": { "description": "Usage summary.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Usage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "$ref": "#/components/responses/InternalError" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "Your API key, e.g. `Authorization: Bearer cf_live_…`. Create and revoke keys in the dashboard. Keys are shown once; keep them on your server, never in browser or mobile code." } }, "headers": { "RequestId": { "description": "Unique ID for this request. Include it when contacting support.", "schema": { "type": "string" } } }, "schemas": { "Language": { "type": "string", "enum": ["python", "javascript", "java", "cpp"], "description": "`python` (CPython 3.12), `javascript` (Node.js 24), `java` (OpenJDK 21), `cpp` (g++ 11, C++17, -O2)." }, "ExecutionRequest": { "type": "object", "required": ["language", "source"], "properties": { "language": { "$ref": "#/components/schemas/Language" }, "source": { "type": "string", "maxLength": 65536, "description": "Program source (UTF-8, up to 64 KiB). Java: the class with `main` may have any name; a `public class` must match its name automatically." }, "stdin": { "type": "string", "maxLength": 65536, "default": "", "description": "Standard input (up to 64 KiB)." }, "limits": { "type": "object", "properties": { "timeMs": { "type": "integer", "minimum": 100, "maximum": 10000, "default": 5000, "description": "Wall-clock limit for running the program. Compilation (Java/C++) has a separate budget and is not counted." } } } } }, "ExecutionAccepted": { "type": "object", "required": ["executionId", "status", "createdAt", "statusUrl"], "properties": { "executionId": { "type": "string", "examples": ["exe_2415f1d958bd4bbfb4cbbe34ccd42e7f"] }, "status": { "$ref": "#/components/schemas/Status" }, "createdAt": { "type": "string", "format": "date-time" }, "statusUrl": { "type": "string", "examples": ["/v1/executions/exe_2415f1d958bd4bbfb4cbbe34ccd42e7f"] } } }, "Status": { "type": "string", "enum": ["QUEUED", "RUNNING", "SUCCEEDED", "COMPILE_ERROR", "RUNTIME_ERROR", "TIMED_OUT", "PLATFORM_ERROR"], "description": "`QUEUED`/`RUNNING` are in progress; the rest are terminal.\n- `SUCCEEDED`: exited with code 0.\n- `COMPILE_ERROR`: Java/C++ failed to compile; see `compileOutput`.\n- `RUNTIME_ERROR`: non-zero exit, exception or crash; see `stderr` and `exitCode`.\n- `TIMED_OUT`: exceeded `limits.timeMs`.\n- `PLATFORM_ERROR`: our failure. Not charged; retry." }, "Execution": { "type": "object", "required": ["executionId", "status", "language", "stdout", "stderr", "compileOutput", "exitCode", "durationMs", "truncated", "createdAt"], "properties": { "executionId": { "type": "string" }, "status": { "$ref": "#/components/schemas/Status" }, "language": { "$ref": "#/components/schemas/Language" }, "stdout": { "type": "string", "description": "Standard output, up to 64 KiB." }, "stderr": { "type": "string", "description": "Standard error, up to 64 KiB." }, "compileOutput": { "type": "string", "description": "Compiler messages (Java/C++), up to 64 KiB." }, "exitCode": { "type": ["integer", "null"], "description": "Process exit code; null if it did not exit normally (e.g. timeout)." }, "durationMs": { "type": ["integer", "null"], "description": "Program run time in milliseconds, excluding compilation and queueing." }, "truncated": { "type": "boolean", "description": "True if any output was cut at 64 KiB." }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": ["string", "null"], "format": "date-time" }, "completedAt": { "type": ["string", "null"], "format": "date-time" } } }, "Usage": { "type": "object", "required": ["plan", "period", "used", "limit", "remaining", "resetsAt", "concurrency", "daily"], "properties": { "plan": { "type": "string", "examples": ["free"] }, "period": { "type": "string", "description": "Current UTC month.", "examples": ["2026-11"] }, "used": { "type": "integer" }, "limit": { "type": "integer" }, "remaining": { "type": "integer" }, "resetsAt": { "type": "string", "format": "date-time" }, "concurrency": { "type": "object", "properties": { "inFlight": { "type": "integer" }, "max": { "type": "integer" } } }, "daily": { "type": "array", "items": { "type": "object", "properties": { "date": { "type": "string", "format": "date" }, "runs": { "type": "integer" }, "billedMs": { "type": "integer" }, "byLanguage": { "type": "object", "additionalProperties": { "type": "integer" } }, "byStatus": { "type": "object", "additionalProperties": { "type": "integer" } }, "byOrigin": { "type": "object", "additionalProperties": { "type": "integer" } } } } } } }, "Error": { "type": "object", "required": ["error"], "properties": { "error": { "type": "object", "required": ["code", "message", "requestId", "retryable"], "properties": { "code": { "type": "string", "enum": ["VALIDATION_ERROR", "INVALID_IDEMPOTENCY_KEY", "BAD_REQUEST", "UNAUTHORIZED", "NOT_FOUND", "IDEMPOTENCY_CONFLICT", "PAYLOAD_TOO_LARGE", "QUOTA_EXCEEDED", "CONCURRENCY_LIMIT", "INTERNAL_ERROR"] }, "message": { "type": "string" }, "requestId": { "type": "string" }, "retryable": { "type": "boolean", "description": "Whether retrying the same request later may succeed." }, "limit": { "type": "integer", "description": "QUOTA_EXCEEDED only." }, "used": { "type": "integer", "description": "QUOTA_EXCEEDED only." }, "resetsAt": { "type": "string", "format": "date-time", "description": "QUOTA_EXCEEDED only." }, "maxConcurrency": { "type": "integer", "description": "CONCURRENCY_LIMIT only." } } } } } }, "responses": { "BadRequest": { "description": "Invalid body (`VALIDATION_ERROR`) or Idempotency-Key (`INVALID_IDEMPOTENCY_KEY`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing, invalid or revoked API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "No such execution in your account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "IdempotencyConflict": { "description": "The Idempotency-Key was already used with a different request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "PayloadTooLarge": { "description": "Request body too large.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooManyRequests": { "description": "`CONCURRENCY_LIMIT` (retryable: wait for a running job to finish) or `QUOTA_EXCEEDED` (not retryable until `resetsAt`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "InternalError": { "description": "Unexpected server error. Safe to retry with the same Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }