> For the complete documentation index, see [llms.txt](https://docs.otari.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.otari.ai/reference/api-reference/code-execution.md). # Code execution ## Execute Code > Run code in the gateway's sandbox and return its output.\ > \ > The run is admitted as an \`\`otari\_code\_execution\`\` call is: a workspace whose\ > code execution policy is off is refused, and its execution ceiling and pinned\ > image apply. It is priced under \`\`otari:code\_execution\`\` and reserved against\ > the caller's budgets. \`\`file\_ids\`\` puts uploads in the working directory, and\ > each file the code writes comes back with a \`\`file\_id\`\`. \`\`container: "auto"\`\`\ > holds the sandbox after the run and names it in \`\`Otari-Container-Id\`\`;\ > sending that id back runs in the same sandbox, with its files and\ > interpreter state.\ > \ > Authentication modes:\ > \- Master key: the \`\`user\`\` field is required and may name any existing user.\ > \- API key: usage and spend bind to the key's own user. A \`\`user\`\` field\ > naming a different user is rejected with 403 (or ignored, when the key's\ > own \`\`reject\_user\_mismatch\`\` is false, or the deployment-wide setting is\ > disabled and the key does not override it); it is never billed to that\ > user.\ > \- Service key: a \`\`user\`\` field names one of the key owner's end users,\ > created on first use on the budget \`\`Otari-End-User-Budget\`\` names (or\ > the key's default), and is billed and rate limited as that end user. ```json {"openapi":"3.1.0","info":{"title":"otari","version":"0.36.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"CodeExecuteRequest":{"description":"A direct code execution request: the code to run, and the sandbox to run it in.","properties":{"code":{"description":"Python source to run in the sandbox","minLength":1,"title":"Code","type":"string"},"container":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"'auto' to hold the sandbox after the run, or a container id an earlier response named in Otari-Container-Id to run in that sandbox again, with its files and interpreter state. Omitted, the sandbox is released when the run ends.","title":"Container"},"file_ids":{"anyOf":[{"items":{"type":"string"},"maxItems":32,"type":"array"},{"type":"null"}],"description":"Uploads from POST /api/v1/files to put in the working directory before the code runs, each under its own filename.","title":"File Ids"},"timeout_seconds":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"description":"How long the code may run. Never more than the workspace's code execution ceiling, or 60 seconds when it sets none.","title":"Timeout Seconds"},"user":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"User ID for usage attribution","title":"User"}},"required":["code"],"title":"CodeExecuteRequest","type":"object"},"CodeExecuteResponse":{"description":"A completed code execution. Code that failed is a completed execution with a nonzero ``return_code``.","properties":{"files":{"description":"The files the code wrote. Empty when it wrote none, or where the Files API is off.","items":{"$ref":"#/components/schemas/CodeExecutionOutputFile"},"title":"Files","type":"array"},"object":{"const":"code_execution.result","default":"code_execution.result","title":"Object","type":"string"},"return_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The program's exit status; null when the sandbox did not report one.","title":"Return Code"},"stderr":{"title":"Stderr","type":"string"},"stdout":{"title":"Stdout","type":"string"}},"required":["stdout","stderr","return_code","files"],"title":"CodeExecuteResponse","type":"object"},"CodeExecutionOutputFile":{"description":"A file the code wrote, stored in the Files API.","properties":{"file_id":{"description":"Download it from GET /api/v1/files/{file_id}/content","title":"File Id","type":"string"},"filename":{"description":"The name the code gave it in the working directory","title":"Filename","type":"string"}},"required":["file_id","filename"],"title":"CodeExecutionOutputFile","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/code/execute":{"post":{"description":"Run code in the gateway's sandbox and return its output.\n\nThe run is admitted as an ``otari_code_execution`` call is: a workspace whose\ncode execution policy is off is refused, and its execution ceiling and pinned\nimage apply. It is priced under ``otari:code_execution`` and reserved against\nthe caller's budgets. ``file_ids`` puts uploads in the working directory, and\neach file the code writes comes back with a ``file_id``. ``container: \"auto\"``\nholds the sandbox after the run and names it in ``Otari-Container-Id``;\nsending that id back runs in the same sandbox, with its files and\ninterpreter state.\n\nAuthentication modes:\n- Master key: the ``user`` field is required and may name any existing user.\n- API key: usage and spend bind to the key's own user. A ``user`` field\n naming a different user is rejected with 403 (or ignored, when the key's\n own ``reject_user_mismatch`` is false, or the deployment-wide setting is\n disabled and the key does not override it); it is never billed to that\n user.\n- Service key: a ``user`` field names one of the key owner's end users,\n created on first use on the budget ``Otari-End-User-Budget`` names (or\n the key's default), and is billed and rate limited as that end user.","operationId":"code-execution-execute_code","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodeExecuteRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodeExecuteResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Execute Code","tags":["code-execution"]}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.otari.ai/reference/api-reference/code-execution.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.