Skip to main content

DIAL Code Interpreter API

This reference distinguishes Core 0.49.4's public interpreter session API from Code Interpreter 0.2.0's private container API. It is for platform engineers verifying the configured interpreter. Quick Apps calls the Core API, which manages session ownership, workload lifecycle, and file transfers.

Core session API​

Paths below are relative to the DIAL Core base URL and require DIAL authentication with an API key or bearer token. Opening a session and executing code also check access.createCodeAppRoles; the check passes when the setting is unset or the request carries a per-request key.

MethodPathInputResponse
POST/v1/ops/code_interpreter/open_sessionJSON with optional sessionId; {} generates an IDJSON containing sessionId
POST/v1/ops/code_interpreter/get_sessionsessionIdSession metadata visible to the caller
POST/v1/ops/code_interpreter/close_sessionsessionIdClosed session's public metadata
POST/v1/ops/code_interpreter/execute_codecode, optional sessionId, inputFiles, and outputFilesExecution result
POST/v1/ops/code_interpreter/upload_fileMultipart file and required session_id query parameterFile path and size
POST/v1/ops/code_interpreter/download_filesessionId and pathFile bytes
POST/v1/ops/code_interpreter/list_filessessionIdJSON files array
POST/v1/ops/code_interpreter/transfer_input_filesessionId, DIAL sourceUrl, and session targetPathFile path and size
POST/v1/ops/code_interpreter/transfer_output_filesessionId, session sourcePath, and DIAL targetUrlDIAL file metadata

The released Core controller defines these operations. Private deployment URLs and deployment IDs are removed from session responses.

Execution and session behavior​

FieldRequiredDescription
codeYesPython source string.
sessionIdNoExisting session ID. Without it, Core opens a temporary session and closes it after the execution request completes.
inputFilesNoFiles copied from DIAL storage before execution, using sourceUrl and targetPath. Core supplies the active session ID.
outputFilesNoFiles copied into DIAL storage after execution, using sourcePath and targetUrl. Core supplies the active session ID.

With an explicit session, subsequent calls reuse kernel variables and files. Idle sessions expire according to Core settings. File transfers check read or write access to the corresponding DIAL resource. See execution lifecycle and file authorization.

Example single calculation through Core:

curl --request POST \
  'https://<DIAL_HOST>/v1/ops/code_interpreter/execute_code' \
  --header 'Api-Key: <DIAL_API_KEY>' \
  --header 'Content-Type: application/json' \
  --data '{"code":"print(6 * 7)"}'

The successful result has this shape:

{
  "status": "SUCCESS",
  "stdout": "42\n",
  "stderr": "",
  "result": "",
  "display": []
}

Core closes this request's temporary session. A stateful caller first opens a session with {} and passes its returned sessionId on later requests:

{"sessionId": "<SESSION_ID>", "code": "values = [12, 18, 24]; print(sum(values) / len(values))"}

Execution response​

FieldDescription
statusSUCCESS or FAILURE. A Python exception can produce HTTP 200 with FAILURE; the caller must inspect this field.
stdoutCaptured standard output with ANSI escapes removed.
stderrCaptured standard error and Python traceback content, with ANSI escapes removed.
resultJupyter execution-result MIME data when present; otherwise an empty string in the interpreter implementation.
displayA list of Jupyter display-data objects, such as image or Plotly MIME data.

The service does not stream token-by-token output. It waits for execution to finish and returns one result. Sources: response model and kernel message handling.

Core errors​

HTTP statusMeaning
400Invalid JSON or a missing or invalid operation field, such as code or sessionId.
403Interpreter permission is denied, or a DIAL file transfer lacks the required access.
404The requested session or file cannot be found. An idle session may already have expired.
503Core's interpreter or application controller configuration is unavailable.
500Unhandled infrastructure or execution-service failure.

Core maps errors in CodeInterpreterController. Authentication and gateway limits also apply before these handlers. Full API schemas are in the Unified API specification.

Private container API​

These endpoints belong to one running interpreter process on port 8080. They do not create or close sessions and do not accept Core's sessionId field as a session-management mechanism.

MethodPathRequestResponse
GET/healthNone{"status":"HEALTHY"}
POST/execute_codeJSON {"code":"<PYTHON_CODE>"}Execution result described above
POST/upload_fileMultipart field file{"path":"<RELATIVE_PATH>","size":<BYTES>}
POST/download_fileJSON {"path":"<FILE_PATH>"}application/octet-stream bytes
POST/list_filesJSON {}; optional comment is accepted but unused{"files":[{"path":"<RELATIVE_PATH>","size":<BYTES>}]}

When SESSION_ID is configured, every operation except /health requires matching x-dial-session-id. That value is Core's private deployment ID in pod-backed mode, not the public session ID. Missing headers return 400; mismatches return 503.

Uploads replace any existing target file. If an upload fails, the target is removed; previous contents are not restored. Uploads exceeding UPLOAD_MAX_SIZE return 413. Missing downloads return 404, and missing or rejected file paths return 400. Request-model validation can return 422. See app.py and request models.

Warning

Direct access bypasses Core's user permissions and resource checks. The interpreter API must remain within the protected execution infrastructure. Its optional session header is not a replacement for user authentication or network isolation.

Further reading​