cdbx API

openapi: 3.1.0
info:
  title: cdbx API
  version: '2026-11-04'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-04: 17 operation(s) read from 2 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; cdbx has published no machine-readable contract that the pipeline
    could find. Engine: local.'
  x-evidence-tiers:
    code-example: 2
    documentation: 15
    pages-with-code: 2
    pages-read: 2
  x-generated-from: documentation
  x-provenance: generated
  x-authored-by: API Evangelist
  x-generated: '2026-11-04'
  x-generator: generate-contract-from-docs.py
  x-engine: local
  x-sources:
  - https://cdbx.ai/docs/how-to-use-cdbx/runner-api
  - https://cdbx.ai/developers
paths:
  /api/v1/runner:
    get:
      operationId: get_api_v1_runner
      tags:
      - Api
      summary: GET /api/v1/runner
      x-source: https://cdbx.ai/docs/how-to-use-cdbx/runner-api
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1RunnerResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl fetch (Node.js) requests (Python) SDKs Use it from an AI agent (MCP) Service status Scroll to top How to use cdbx Code\
          \ Execution API Copy page Code Execution API \n The cdbx Code Execution API lets you execute code in a secure sandbox from your own\
          \ scripts, agents, or applications. Send code, get output — no infrastructure required. \n Building an AI agent? MCP is the primary\
          \ way to give it thi"
  /api/v1/runner/execute:
    post:
      operationId: post_api_v1_runner_execute
      tags:
      - Api
      summary: POST /api/v1/runner/execute
      x-source: https://cdbx.ai/docs/how-to-use-cdbx/runner-api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1RunnerExecuteRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1RunnerExecuteResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -X POST https://cdbx.ai/api/v1/runner/execute  -H \"Authorization: Bearer cdbx_your_key_here\"  -H \"Content-Type: application/json\"\
          \  -d '{ \n \"language\": \"python\", \n \"files\": { \"main.py\": \"print(\\\"Hello, world!\\\")\" }, \n \"entrypoint\": \"main.py\"\
          \ \n }'  | jq \n fetch (Node.js) \n const res = await fetch ( 'https://cdbx.ai/api/v1/runner/execute' , { \n method: 'POST' , \n headers:\
          \ { \n 'Authorization' : '"
  /api/v1/runner/languages:
    get:
      operationId: get_api_v1_runner_languages
      tags:
      - Api
      summary: List supported languages
      x-source: https://cdbx.ai/docs/how-to-use-cdbx/runner-api
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetApiV1RunnerLanguagesResponse'
      x-evidence:
        kind: documentation
  /api/v1/runner/run/async:
    post:
      operationId: post_api_v1_runner_run_async
      tags:
      - Api
      summary: Async execution (streaming)
      x-source: https://cdbx.ai/docs/how-to-use-cdbx/runner-api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1RunnerRunAsyncRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1RunnerRunAsyncResponse'
      x-evidence:
        kind: documentation
  /api/v1/runner/sessions:
    post:
      operationId: post_api_v1_runner_sessions
      tags:
      - Api
      summary: Create a session
      x-source: https://cdbx.ai/docs/how-to-use-cdbx/runner-api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1RunnerSessionsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1RunnerSessionsResponse'
      x-evidence:
        kind: documentation
  /api/v1/runner/sessions/{id}:
    delete:
      operationId: delete_api_v1_runner_sessions_id
      tags:
      - Api
      summary: Delete a session
      x-source: https://cdbx.ai/docs/how-to-use-cdbx/runner-api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/runner/sessions/{id}/files:
    post:
      operationId: post_api_v1_runner_sessions_id_files
      tags:
      - Api
      summary: Write files to a session
      x-source: https://cdbx.ai/docs/how-to-use-cdbx/runner-api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1RunnerSessionsIdFilesRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /api/v1/runner/sessions/{id}/run:
    post:
      operationId: post_api_v1_runner_sessions_id_run
      tags:
      - Api
      summary: Run in a session
      x-source: https://cdbx.ai/docs/how-to-use-cdbx/runner-api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostApiV1RunnerSessionsIdRunRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostApiV1RunnerSessionsIdRunResponse'
      x-evidence:
        kind: documentation
  /check:
    post:
      operationId: post_check
      tags:
      - Check
      summary: Syntax/type check without executing
      x-source: https://cdbx.ai/docs/how-to-use-cdbx/runner-api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostCheckRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostCheckResponse'
      x-evidence:
        kind: documentation
  /execute:
    post:
      operationId: post_execute
      tags:
      - Execute
      summary: Execute code and return output
      x-source: https://cdbx.ai/docs/how-to-use-cdbx/runner-api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostExecuteRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostExecuteResponse'
      x-evidence:
        kind: documentation
  /languages:
    get:
      operationId: get_languages
      tags:
      - Languages
      summary: List supported languages
      x-source: https://cdbx.ai/docs/how-to-use-cdbx/runner-api
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetLanguagesResponse'
      x-evidence:
        kind: documentation
  /run/async:
    post:
      operationId: post_run_async
      tags:
      - Run
      summary: Start async execution, get job ID
      x-source: https://cdbx.ai/docs/how-to-use-cdbx/runner-api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostRunAsyncRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostRunAsyncResponse'
      x-evidence:
        kind: documentation
  /sessions:
    post:
      operationId: post_sessions
      tags:
      - Sessions
      summary: Create a persistent session (IDE mode)
      x-source: https://cdbx.ai/docs/how-to-use-cdbx/runner-api
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostSessionsRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostSessionsResponse'
      x-evidence:
        kind: documentation
  /sessions/{id}:
    delete:
      operationId: delete_sessions_id
      tags:
      - Sessions
      summary: Delete a session
      x-source: https://cdbx.ai/docs/how-to-use-cdbx/runner-api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /sessions/{id}/files:
    post:
      operationId: post_sessions_id_files
      tags:
      - Sessions
      summary: Write files to a session
      x-source: https://cdbx.ai/docs/how-to-use-cdbx/runner-api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostSessionsIdFilesRequest'
      responses:
        '201':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /sessions/{id}/run:
    post:
      operationId: post_sessions_id_run
      tags:
      - Sessions
      summary: Execute in a session
      x-source: https://cdbx.ai/docs/how-to-use-cdbx/runner-api
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostSessionsIdRunRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostSessionsIdRunResponse'
      x-evidence:
        kind: documentation
  /ws/{jobid}:
    get:
      operationId: get_ws_jobid
      tags:
      - Ws
      summary: WebSocket stream for async job
      x-source: https://cdbx.ai/docs/how-to-use-cdbx/runner-api
      parameters:
      - name: jobid
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetWsJobidResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    GetApiV1RunnerResponse:
      type: object
      properties:
        language:
          type: string
        files:
          type: object
          properties:
            main.py:
              type: string
        entrypoint:
          type: string
        stdin:
          type: string
        timeout:
          type: integer
    PostApiV1RunnerExecuteRequest:
      type: object
      properties:
        language:
          type: string
        files:
          type: object
          properties:
            main.py:
              type: string
        entrypoint:
          type: string
    PostApiV1RunnerExecuteResponse:
      type: object
      properties:
        Authorization:
          type: string
        Content-Type:
          type: string
    GetApiV1RunnerLanguagesResponse:
      type: object
      properties:
        languages:
          type: array
          description: Array of language objects with id, name, version, extension
    PostApiV1RunnerRunAsyncRequest:
      type: object
      properties:
        language:
          type: string
        files:
          type: object
        entrypoint:
          type: string
        stdin:
          type: string
        timeout:
          type: number
      required:
      - language
      - files
      - entrypoint
    PostApiV1RunnerRunAsyncResponse:
      type: object
      properties:
        jobId:
          type: string
        wsUrl:
          type: string
    PostApiV1RunnerSessionsRequest:
      type: object
      properties:
        language:
          type: string
      required:
      - language
    PostApiV1RunnerSessionsResponse:
      type: object
      properties:
        id:
          type: string
        language:
          type: string
    PostApiV1RunnerSessionsIdFilesRequest:
      type: object
      properties:
        files:
          type: object
      required:
      - files
    PostApiV1RunnerSessionsIdRunRequest:
      type: object
      properties:
        files:
          type: object
        entrypoint:
          type: string
        stdin:
          type: string
        timeout:
          type: number
      required:
      - entrypoint
    PostApiV1RunnerSessionsIdRunResponse:
      type: object
      properties:
        stdout:
          type: string
        stderr:
          type: string
        exitCode:
          type: number
        duration:
          type: number
        error:
          type: string
          description: Set if the Code Execution API itself failed (not the user code)
    PostCheckRequest:
      type: object
      properties:
        language:
          type: string
          description: Language ID (see /languages )
        files:
          type: object
          description: Map of filename → source code
        entrypoint:
          type: string
          description: The file to execute
        stdin:
          type: string
          description: Input piped to stdin
        timeout:
          type: number
          description: Max execution seconds (capped by tier)
      required:
      - language
      - files
      - entrypoint
    PostCheckResponse:
      type: object
      properties:
        stdout:
          type: string
          description: Standard output (may be empty)
        stderr:
          type: string
          description: Standard error (may be empty)
        exitCode:
          type: integer
          description: Process exit code (0 = success)
        duration:
          type: integer
          description: Wall‑clock time in milliseconds
        error:
          type: string
          description: Set if the Code Execution API itself failed
    PostExecuteRequest:
      type: object
      properties:
        language:
          type: string
          description: Language ID (see /languages )
        files:
          type: object
          description: Map of filename → source code
        entrypoint:
          type: string
          description: The file to execute
        stdin:
          type: string
          description: Input piped to stdin
        timeout:
          type: number
          description: Max execution seconds (capped by tier)
      required:
      - language
      - files
      - entrypoint
    PostExecuteResponse:
      type: object
      properties:
        stdout:
          type: string
          description: Standard output
        stderr:
          type: string
          description: Standard error
        exitCode:
          type: integer
          description: Process exit code (0 = success)
        duration:
          type: integer
          description: Wall‑clock time in milliseconds
        error:
          type: string
          description: Set if the Code Execution API itself failed (not the user code)
    GetLanguagesResponse:
      type: object
      properties:
        languages:
          type: array
          description: Array of language objects
    PostRunAsyncRequest:
      type: object
      properties:
        language:
          type: string
          description: Language ID (see /languages )
        files:
          type: object
          description: Map of filename → source code
        entrypoint:
          type: string
          description: The file to execute
        stdin:
          type: string
          description: Input piped to stdin
        timeout:
          type: number
          description: Max execution seconds (capped by tier)
      required:
      - language
      - files
      - entrypoint
    PostRunAsyncResponse:
      type: object
      properties:
        jobId:
          type: string
          description: Identifier for the async job
        wsUrl:
          type: string
          description: WebSocket URL path for streaming results
    PostSessionsRequest:
      type: object
      properties:
        language:
          type: string
          description: Language ID for the session
      required:
      - language
    PostSessionsResponse:
      type: object
      properties:
        id:
          type: string
          description: Session identifier
        language:
          type: string
          description: Language of the session
    PostSessionsIdFilesRequest:
      type: object
      properties:
        files:
          type: object
          description: Map of filename → source code to write
      required:
      - files
    PostSessionsIdRunRequest:
      type: object
      properties:
        files:
          type: object
          description: Map of filename → source code (optional if already written)
        entrypoint:
          type: string
          description: The file to execute
        stdin:
          type: string
          description: Input piped to stdin
        timeout:
          type: number
          description: Max execution seconds (capped by tier)
      required:
      - entrypoint
    PostSessionsIdRunResponse:
      type: object
      properties:
        stdout:
          type: string
          description: Standard output
        stderr:
          type: string
          description: Standard error
        exitCode:
          type: integer
          description: Process exit code
        duration:
          type: integer
          description: Wall‑clock time in milliseconds
        error:
          type: string
          description: Set if the API itself failed
    GetWsJobidResponse:
      type: object
      properties:
        type:
          type: string
          description: Event type (stdout, stderr, exit, error)
        data:
          type: string
          description: Payload for stdout/stderr events
        exitCode:
          type: integer
          description: Exit code for exit event
        duration:
          type: integer
          description: Execution duration in milliseconds for exit event
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
security:
- bearer: []
tags:
- name: Api
- name: Check
- name: Execute
- name: Languages
- name: Run
- name: Sessions
- name: Ws