onlinecompiler-io Run API

openapi: 3.2.0
info:
  title: OnlineCompiler.io Run API
  version: '2026-10-24'
  summary: Run code in a sandbox, judge it against test cases, and read limits and usage.
  description: 'Execute source code in isolated, network-less sandboxes in dozens of languages and get stdout, stderr, exit code, time and memory back as JSON. This file describes the native REST API: synchronous runs, asynchronous runs with a callback, judging a program against test cases, the compiler list, execution limits, usage and health.


    **Authentication.** Create an API key (type API) in the dashboard at https://api.onlinecompiler.io/compilers/api-keys/ and send the bare key in the `Authorization` header, for example `Authorization: YOUR_API_KEY`. A `Bearer ` prefix is not accepted on this API. Widget keys cannot call it. `GET /api/compilers/`, `GET /api/limits/` and `GET /api/health/` need no key.


    Paths are written with a trailing slash; every path except `/api/files/{file_id}/` also works without it.


    **Limits.** Per-run limits (memory, CPUs, timeout, output size, file counts) and your plan''s allowance and rate limits change over time and are not repeated here: read `GET /api/limits/` for the defaults and `GET /api/usage/` for your account. A refusal for a limit answers HTTP 429 with `{"error": "..."}` and nothing runs or is counted.


    **Compatible APIs.** Existing clients can also talk to OnlineCompiler.io through compatibility layers that are not part of this description: Judge0 CE (https://onlinecompiler.io/docs/judge0), Piston v2 (https://onlinecompiler.io/docs/piston) and Jobe for Moodle CodeRunner (https://onlinecompiler.io/docs/jobe). The MCP server and WebSocket widget are documented at https://onlinecompiler.io/docs.


    Full documentation: https://onlinecompiler.io/docs'
  termsOfService: https://onlinecompiler.io/terms
  contact:
    name: OnlineCompiler.io
    url: https://onlinecompiler.io/contact
servers:
- url: https://api.onlinecompiler.io
  description: Production
tags:
- name: Run
  description: Run one program.
paths:
  /api/run-code-sync/:
    post:
      operationId: runCodeSync
      tags:
      - Run
      summary: Run code and wait for the result
      description: 'Runs the program and returns when it ends, within the sandbox timeout. Answers 429 when your account''s runs at once or the host''s sandboxes are all busy; retry shortly. A program that fails (non-zero exit, timeout, compile error) is still HTTP 200: read `status` and `exit_code`.'
      security:
      - ApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunRequest'
            examples:
              python:
                summary: Python with stdin
                value:
                  compiler: python-3.14
                  code: 'name = input()

                    print(f"Hello, {name}!")'
                  input: World
              inputFile:
                summary: A CSV in, using files
                value:
                  compiler: python-3.14
                  code: print(open('sales.csv').read())
                  files:
                  - name: sales.csv
                    content: 'region,amount

                      north,10

                      '
      responses:
        '200':
          description: The run finished, successfully or not.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RunResult'
              example:
                output: 'Hello, World!

                  '
                error: ''
                status: success
                exit_code: 0
                signal: null
                truncated: false
                time: '0.0248'
                total: '0.0330'
                memory: '8192'
                files: []
                files_truncated: false
                time_limit: 30
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/InvalidKey'
        '429':
          $ref: '#/components/responses/RateLimited'
  /api/run-code/:
    post:
      operationId: runCodeAsync
      tags:
      - Run
      summary: Queue a run and receive the result by callback
      description: Admits the run and answers 202 at once with a queue id. When it finishes, the result is POSTed as JSON (shape `CallbackBody`, see the `runResult` webhook) to the callback URL set on the API key in the dashboard; the callback carries no id, so pass `extra_params` to correlate it. The key must have a callback URL, which must be a public http(s) address without credentials; redirects are not followed. A failed delivery is retried a few times. Use `/api/run-code-sync/` when you can wait for the result instead.
      security:
      - ApiKey: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AsyncRunRequest'
            example:
              compiler: python-3.14
              code: print(sum(range(10)))
              extra_params:
                job: abc123
      responses:
        '202':
          description: Admitted and queued.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Queued'
              example:
                status: queued
                id: 42
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/InvalidKey'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/Unavailable'
webhooks:
  runResult:
    post:
      operationId: runResultCallback
      tags:
      - Run
      summary: Result of a finished asynchronous run
      description: OnlineCompiler.io POSTs this JSON to the callback URL configured on your API key when a run queued with /api/run-code/ finishes. Any 2xx response acknowledges it; other outcomes are retried a few times.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CallbackBody'
      responses:
        '200':
          description: Acknowledged. Any 2xx status counts.
components:
  schemas:
    CompilerId:
      type: string
      description: A compiler id from GET /api/compilers/. Retired ids (the dotnet-*-9 ids, now dotnet-*-10) are still accepted and run on their successor, but are not listed.
      examples:
      - python-3.14
      - gcc-15
      - nodejs-24
      enum:
      - python-3.14
      - python-3.14-pandas2
      - duckdb-1.5
      - gcc-15
      - g++-15
      - openjdk-25
      - dotnet-csharp-10
      - dotnet-fsharp-10
      - php-8.5
      - ruby-4.0
      - haskell-9.12
      - go-1.26
      - rust-1.93
      - typescript-deno
      - nodejs-24
      - sqlite-3
      - bash-5.2
      - gfortran-15
      - dotnet-vbnet-10
      - kotlin-2.4
      - r-4.6
      - swift-6.4
      - gnucobol-3.2
      - perl-5.44
      - julia-1.13
      - fpc-3.2
      - octave-11
      - nasm-3
      - lua-5.5
      - ocaml-5.4
      - sbcl-2.6
      - erlang-29
      - elixir-1.20
      - swipl-10
      - ldc-1.43
      - fbc-1.10
      - dart-3.13
      - clojure-1.12
      - groovy-6.0
      - scala-3.10
      - zig-0.17
      - nim-2.2
      - crystal-1.22
      - gnat-15
      - powershell-7.6
      - racket-9.3
      - clang-objc-21
    RunRequest:
      type: object
      required:
      - compiler
      - code
      properties:
        compiler:
          $ref: '#/components/schemas/CompilerId'
        code:
          type: string
          minLength: 1
          description: 'Source code: UTF-8 without NUL characters, at most 100,000 bytes (see GET /api/limits/, code_kb).'
        input:
          type: string
          default: ''
          description: 'Standard input for the program: UTF-8 without NUL characters, at most 100,000 bytes. For SQL runs the script reads it with readfile(''input'') (SQLite) or read_text(''input'') (DuckDB).'
        time_limit:
          type: number
          exclusiveMinimum: 0
          maximum: 30
          description: Seconds the program may run, above 0 and at most the sandbox timeout. The run stops at it with exit code 124. Compilation before the run does not count, but Java, Groovy and F# get a start-up allowance on top. Without it the run gets what is left of the sandbox timeout.
        files:
          type: array
          maxItems: 8
          items:
            $ref: '#/components/schemas/InputFile'
          description: Input files for the program, at most 1,000,000 bytes in total once decoded (see GET /api/limits/).
    OutputFile:
      type: object
      required:
      - name
      - mime
      - size
      - content_base64
      - url
      properties:
        name:
          type: string
        mime:
          type: string
        size:
          type: integer
          description: Bytes.
        content_base64:
          type: string
          description: The file's bytes, base64 encoded.
        url:
          type:
          - string
          - 'null'
          format: uri
          description: Where the account that ran it can fetch the file again with its API key (GET /api/files/{file_id}/). Null when the file was not stored, always in run-tests results.
    CallbackBody:
      type: object
      required:
      - output
      - error
      - status
      - exit_code
      - signal
      - truncated
      - time
      - total
      - memory
      - files
      - files_truncated
      - time_limit
      - extra_params
      properties:
        output:
          type: string
          description: Standard output, cut at the output cap (see GET /api/limits/). NUL and invalid UTF-8 bytes come back as U+FFFD.
        error:
          type: string
          description: Standard error, or compiler errors. Same cap and encoding as output.
        status:
          type: string
          enum:
          - success
          - error
          description: success when exit_code is 0, error otherwise.
        exit_code:
          type: integer
          description: The process exit code. 0 is success; 124 means the time limit was exceeded; 137 (signal 9) the memory limit; 153 (signal 25) an output flood; 71 too many processes; -1 means the run failed on our side.
        signal:
          type:
          - integer
          - 'null'
          description: The signal number when the program was killed by one (exit_code minus 128), otherwise null.
        truncated:
          type: boolean
          description: True when output or error went over the cap and was cut.
        time:
          type: string
          description: Wall time of the run command in seconds, as a decimal string. Includes compilation for languages that compile as they run.
        total:
          type: string
          description: Wall time of the whole script in seconds, including separate compilation, excluding container start-up. A decimal string.
        memory:
          type: string
          description: 'Memory use in KB, as a decimal string. Informational: it counts library files the program maps.'
        files:
          type: array
          items:
            $ref: '#/components/schemas/OutputFile'
          description: Files the program wrote to the directory named by the OUTPUT_DIR environment variable. An empty list when there are none.
        files_truncated:
          type: boolean
          description: True when some output files were left out (too many, too large, or of a type that is not returned).
        time_limit:
          type: number
          description: 'The time limit the run had, in seconds: the time_limit you sent, or the sandbox maximum without one.'
        extra_params:
          type: object
          additionalProperties: true
          description: The extra_params of the request, unchanged ({} when none).
    InputFile:
      type: object
      required:
      - name
      - content
      properties:
        name:
          type: string
          maxLength: 100
          pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,99}$
          description: A plain file name. It cannot be input, run.sh, build, build.tar or go-trim.txt, its part before the first dot cannot be code, and names in one request must differ.
        content:
          type: string
          description: 'The file''s content: UTF-8 text without NUL characters, or base64 when encoding is base64.'
        encoding:
          type: string
          enum:
          - utf8
          - base64
          default: utf8
      description: A file placed in the program's working directory.
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: A human-readable reason.
    AsyncRunRequest:
      allOf:
      - $ref: '#/components/schemas/RunRequest'
      - type: object
        properties:
          extra_params:
            type: object
            additionalProperties: true
            description: A JSON object of your own data, at most 8 KB, returned unchanged in the callback.
    RunResult:
      type: object
      required:
      - output
      - error
      - status
      - exit_code
      - signal
      - truncated
      - time
      - total
      - memory
      - files
      - files_truncated
      - time_limit
      properties:
        output:
          type: string
          description: Standard output, cut at the output cap (see GET /api/limits/). NUL and invalid UTF-8 bytes come back as U+FFFD.
        error:
          type: string
          description: Standard error, or compiler errors. Same cap and encoding as output.
        status:
          type: string
          enum:
          - success
          - error
          description: success when exit_code is 0, error otherwise.
        exit_code:
          type: integer
          description: The process exit code. 0 is success; 124 means the time limit was exceeded; 137 (signal 9) the memory limit; 153 (signal 25) an output flood; 71 too many processes; -1 means the run failed on our side.
        signal:
          type:
          - integer
          - 'null'
          description: The signal number when the program was killed by one (exit_code minus 128), otherwise null.
        truncated:
          type: boolean
          description: True when output or error went over the cap and was cut.
        time:
          type: string
          description: Wall time of the run command in seconds, as a decimal string. Includes compilation for languages that compile as they run.
        total:
          type: string
          description: Wall time of the whole script in seconds, including separate compilation, excluding container start-up. A decimal string.
        memory:
          type: string
          description: 'Memory use in KB, as a decimal string. Informational: it counts library files the program maps.'
        files:
          type: array
          items:
            $ref: '#/components/schemas/OutputFile'
          description: Files the program wrote to the directory named by the OUTPUT_DIR environment variable. An empty list when there are none.
        files_truncated:
          type: boolean
          description: True when some output files were left out (too many, too large, or of a type that is not returned).
        time_limit:
          type: number
          description: 'The time limit the run had, in seconds: the time_limit you sent, or the sandbox maximum without one.'
    Queued:
      type: object
      required:
      - status
      - id
      properties:
        status:
          type: string
          const: queued
        id:
          type: integer
          description: The queue id of the run.
  responses:
    RateLimited:
      description: A limit was reached or the sandboxes are busy. Nothing ran and nothing was counted. A spent monthly allowance or key cap will not clear until the month resets; the other causes clear shortly, so retry with backoff. Where a paid plan raises the limit, the message names it with a link.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            month:
              summary: Monthly allowance spent
              value:
                error: Monthly submission limit of 100,000 reached. It resets on 1 November 2026 (UTC).
            key:
              summary: The key's own cap spent
              value:
                error: Monthly limit of 5,000 submissions for this API key reached. It resets on 1 November 2026 (UTC).
            rate:
              summary: Per-minute rate
              value:
                error: Submission rate limit exceeded. Try again shortly.
            pending:
              summary: Too many pending
              value:
                error: Too many pending submissions for this account.
            account:
              summary: The account's runs at once are busy
              value:
                error: Too many runs in progress for this account (limit 2 at once). Please try again shortly.
            host:
              summary: The host's sandboxes are busy
              value:
                error: Too many concurrent requests. Please try again shortly.
    Forbidden:
      description: The Authorization header is missing, the key is not an API key (for example a widget key), or the request comes from an origin the key does not allow.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missing:
              summary: No header
              value:
                error: Missing Authorization header
            type:
              summary: Wrong key type
              value:
                error: This key is not authorized for the REST API
            origin:
              summary: Origin restriction
              value:
                error: Request origin not allowed for this API key
    InvalidKey:
      description: No active API key matches the Authorization header (unknown, deleted or deactivated).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error: Invalid or inactive API key
    Unavailable:
      description: The run could not be queued or its input files could not be stored. It is not counted; retry later.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            queue:
              summary: Queue down
              value:
                error: Execution queue unavailable
            files:
              summary: Files not stored
              value:
                error: Could not store input files
    BadRequest:
      description: 'The request is invalid and nothing ran or was counted: not a JSON object, a missing or bad field, an unsupported compiler, a bad file, an over-budget run-tests request, or (for /api/run-code/) a key with no usable callback URL.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            compiler:
              summary: Unknown compiler
              value:
                error: Unsupported or missing compiler
            code:
              summary: No code
              value:
                error: Missing code field
            json:
              summary: Not JSON
              value:
                error: Invalid JSON body
            time_limit:
              summary: Bad time limit
              value:
                error: time_limit must be a number of seconds above 0 and at most 30
            tests:
              summary: run-tests without tests
              value:
                error: tests must be a list of 1 to 8 tests on this plan
            callback:
              summary: No callback URL on the key (/api/run-code/)
              value:
                error: This API key has no callback URL configured. Set one in your dashboard, or use /api/run-code-sync/ instead.
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: Authorization
      description: Your API key (key type API) from https://api.onlinecompiler.io/compilers/api-keys/, sent as the bare value of the Authorization header. Do not add a Bearer prefix. A key may be restricted to an origin in the dashboard.
externalDocs:
  description: OnlineCompiler.io documentation
  url: https://onlinecompiler.io/docs