onlinecompiler-io Account API

openapi: 3.2.0
info:
  title: OnlineCompiler.io Account 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: Account
  description: Usage and stored files of the calling key's account.
paths:
  /api/usage/:
    get:
      operationId: getUsage
      tags:
      - Account
      summary: This month's runs and the limits that apply to the calling key
      description: Counts runs of the calling key's account in the current calendar month (UTC), with the account's limits and, separately, the calling key's own count and monthly limit.
      security:
      - ApiKey: []
      responses:
        '200':
          description: Usage and limits.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Usage'
              example:
                month: 2026-10
                submissions: 1520
                monthly_limit: 100000
                remaining: 98480
                resets_at: '2026-11-01T00:00:00Z'
                submissions_per_minute: 30
                pending_submissions: 8
                running_submissions: 2
                key:
                  submissions: 1200
                  monthly_limit: 5000
                  remaining: 3800
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/InvalidKey'
  /api/files/{file_id}/:
    get:
      operationId: downloadFile
      tags:
      - Account
      summary: Download a stored output file
      description: Serves an output file a run stored, to any API key of the account that ran it. The `url` of an entry in a run's `files` is this path. Files are kept for a limited time (see `GET /api/limits/`, `file_retention_days`). Other accounts, expired files and files that were never stored answer 404. The trailing slash is required on this path.
      security:
      - ApiKey: []
      parameters:
      - name: file_id
        in: path
        required: true
        schema:
          type: integer
        description: The number at the end of a file's `url`.
      responses:
        '200':
          description: The file's bytes, as an attachment, with the MIME type the run reported.
          headers:
            Content-Disposition:
              schema:
                type: string
              description: attachment; filename*=UTF-8''<name>
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: Unknown key, or the file is not found (not yours, expired, or never stored).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                key:
                  summary: Unknown key
                  value:
                    error: Invalid or inactive API key
                file:
                  summary: No such file
                  value:
                    error: File not found
components:
  responses:
    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
    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
  schemas:
    Usage:
      type: object
      required:
      - month
      - submissions
      - monthly_limit
      - remaining
      - resets_at
      - submissions_per_minute
      - pending_submissions
      - running_submissions
      properties:
        month:
          type: string
          pattern: ^[0-9]{4}-[0-9]{2}$
          description: The calendar month (UTC) being counted.
        submissions:
          type: integer
          description: Runs this month by the account. Each test of run-tests is one run.
        monthly_limit:
          type: integer
        remaining:
          type: integer
        resets_at:
          type: string
          format: date-time
        submissions_per_minute:
          type: integer
        pending_submissions:
          type: integer
        running_submissions:
          type: integer
        key:
          type: object
          required:
          - submissions
          - monthly_limit
          - remaining
          properties:
            submissions:
              type: integer
              description: Runs this month through the calling key.
            monthly_limit:
              type:
              - integer
              - 'null'
              description: The key's own monthly cap, null when it has none.
            remaining:
              type:
              - integer
              - 'null'
              description: Null when the key has no cap.
          description: The calling key's own count and limit.
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: string
          description: A human-readable reason.
  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