Celesto AI celesto API

openapi: 3.1.0
info:
  title: Celesto AI celesto API
  version: '2026-11-04'
  description: 'GENERATED FROM DOCUMENTATION by API Evangelist on 2026-11-04: 7 operation(s) read from 1 public documentation page(s) (each operation
    names its page in x-source). This is not the provider''s published contract; Celesto AI has published no machine-readable contract that the
    pipeline could find. Engine: local.'
  x-evidence-tiers:
    code-example: 10
    documentation: 6
    pages-with-code: 12
    pages-read: 15
  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://celesto.ai/docs/celesto/guides/http-api-typescript-sdk
  x-docs-section: celesto
paths:
  /:
    get:
      operationId: get
      tags:
      - Api
      summary: GET /
      x-source: https://celesto.ai/docs/celesto/guides/http-api-typescript-sdk
      responses:
        '200':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: curl Run a command Use the TypeScript client Get sandbox desktop connection details Generate clients from OpenAPI Troubleshooting
          Related Guides Use the Celesto HTTP API and TypeScript SDK Copy page Copy page Run the local Celesto HTTP server to create sandboxes
          and run commands over REST, then control those sandboxes from TypeScript with the generated client. Copy page Copy page Celesto can
          run a
  /sandboxes:
    get:
      operationId: get_sandboxes
      tags:
      - Sandboxes
      summary: List sandboxes on the host
      x-source: https://celesto.ai/docs/celesto/guides/http-api-typescript-sdk
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    post:
      operationId: post_sandboxes
      tags:
      - Sandboxes
      summary: POST /sandboxes
      x-source: https://celesto.ai/docs/celesto/guides/http-api-typescript-sdk
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostSandboxesRequest'
      responses:
        '201':
          description: Success (shape read from the example response on the page)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostSandboxesResponse'
      x-evidence:
        kind: code-example
        language: curl
        snippet: "curl -s -X POST http://127.0.0.1:8000/sandboxes  -H \"Content-Type: application/json\"  -d '{\"os\":\"ubuntu\",\"memory\":512,\"\
          disk_size\":1024}' \n Example response: \n { \n \"id\" : \"vm-a1b2c3d4\" , \n \"status\" : \"running\" \n } \n The request body mirrors\
          \ the auto-config options of the Python Celesto(...) constructor. \n ​ os \"alpine\" | \"ubuntu\" | \"windows\" Guest operating system.\
          \ Omit it for the default Linux san"
  /sandboxes/{id}:
    delete:
      operationId: delete_sandboxes_id
      tags:
      - Sandboxes
      summary: Stop and delete a sandbox
      x-source: https://celesto.ai/docs/celesto/guides/http-api-typescript-sdk
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
    get:
      operationId: get_sandboxes_id
      tags:
      - Sandboxes
      summary: Get one sandbox’s state
      x-source: https://celesto.ai/docs/celesto/guides/http-api-typescript-sdk
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
      x-evidence:
        kind: documentation
  /sandboxes/{id}/desktop:
    get:
      operationId: get_sandboxes_id_desktop
      tags:
      - Sandboxes
      summary: Get the sandbox’s desktop connection details
      x-source: https://celesto.ai/docs/celesto/guides/http-api-typescript-sdk
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetSandboxesIdDesktopResponse'
      x-evidence:
        kind: documentation
  /sandboxes/{id}/exec:
    post:
      operationId: post_sandboxes_id_exec
      tags:
      - Sandboxes
      summary: Run a command inside a sandbox
      x-source: https://celesto.ai/docs/celesto/guides/http-api-typescript-sdk
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PostSandboxesIdExecRequest'
      responses:
        '201':
          description: Success (status as documented)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PostSandboxesIdExecResponse'
      x-evidence:
        kind: documentation
components:
  schemas:
    GetResponse:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
    PostSandboxesRequest:
      type: object
      properties:
        os:
          type: string
        memory:
          type: integer
        disk_size:
          type: integer
    PostSandboxesResponse:
      type: object
      properties:
        id:
          type: string
        status:
          type: string
    GetSandboxesIdDesktopResponse:
      type: object
      properties:
        protocol:
          type: string
          description: The desktop protocol, currently "vnc".
        host:
          type: string
          description: The loopback host the desktop is bound to.
        port:
          type: integer
          description: The port the desktop is listening on.
        viewer_url:
          type: string
          description: A URL you can hand to a desktop viewer to open the session.
    PostSandboxesIdExecRequest:
      type: object
      properties:
        command:
          type: string
          description: Command to run inside the sandbox.
        timeout:
          type: integer
          description: Maximum seconds to wait for the command.
        shell:
          type: string
          description: '"login" | "raw" default: "login" Use login for the guest login shell, or raw to run the command without shell wrapping.'
      required:
      - command
    PostSandboxesIdExecResponse:
      type: object
      properties:
        exit_code:
          type: integer
          description: Process exit code.
        stdout:
          type: string
          description: Standard output.
        stderr:
          type: string
          description: Standard error.
  securitySchemes:
    CELESTO_API_KEY:
      type: apiKey
      in: header
      name: Authorization
      x-source: https://celesto.ai/docs/cloud/authentication
tags:
- name: Api
- name: Sandboxes
security:
- CELESTO_API_KEY: []