openapi: 3.0.0
info:
  version: 0.1.0
  title: E2B API

servers:
  - url: https://api.e2b.dev

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    AccessTokenAuth:
      type: http
      scheme: bearer
      bearerFormat: access_token

  parameters:
    templateID:
      name: templateID
      in: path
      required: true
      schema:
        type: string
    buildID:
      name: buildID
      in: path
      required: true
      schema:
        type: string
    sandboxID:
      name: sandboxID
      in: path
      required: true
      schema:
        type: string

  responses:
    400:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    401:
      description: Authentication error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    404:
      description: Not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

    500:
      description: Server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

  schemas:
    SandboxMetadata:
      additionalProperties:
        type: string
        description: Metadata of the sandbox

    SandboxLog:
      description: Log entry with timestamp and line
      required:
        - timestamp
        - line
      properties:
        timestamp:
          type: string
          format: date-time
          description: Timestamp of the log entry
        line:
          type: string
          description: Log line content

    SandboxLogs:
      required:
        - logs
      properties:
        logs:
          description: Logs of the sandbox
          type: array
          items:
            $ref: "#/components/schemas/SandboxLog"

    Sandbox:
      required:
        - templateID
        - sandboxID
        - clientID
      properties:
        templateID:
          type: string
          description: Identifier of the template from which is the sandbox created
        sandboxID:
          type: string
          description: Identifier of the sandbox
        alias:
          type: string
          description: Alias of the template
        clientID:
          type: string
          description: Identifier of the client

    RunningSandboxes:
      required:
        - templateID
        - sandboxID
        - clientID
        - startedAt
        - cpuCount
        - memoryMB
      properties:
        templateID:
          type: string
          description: Identifier of the template from which is the sandbox created
        alias:
          type: string
          description: Alias of the template
        sandboxID:
          type: string
          description: Identifier of the sandbox
        clientID:
          type: string
          description: Identifier of the client
        startedAt:
          type: string
          format: date-time
          description: Time when the sandbox was started
        cpuCount:
          type: integer
          description: CPU cores for the sandbox
        memoryMB:
          type: integer
          description: Memory limit for the sandbox in MB
        metadata:
          $ref: "#/components/schemas/SandboxMetadata"

    NewSandbox:
      required:
        - templateID
      properties:
        templateID:
          type: string
          description: Identifier of the required template
        metadata:
          $ref: "#/components/schemas/SandboxMetadata"

    Template:
      required:
        - templateID
        - buildID
        - cpuCount
        - memoryMB
        - storageGB
        - public
      properties:
        templateID:
          type: string
          description: Identifier of the template
        buildID:
          type: string
          description: Identifier of the last successful build for given template
        cpuCount:
          type: integer
          description: CPU cores for the sandbox
        memoryMB:
          type: integer
          description: Memory limit for the sandbox in MB
        public:
          type: boolean
          description: Whether the template is public or only accessible by the team
        aliases:
          type: array
          description: Aliases of the template
          items:
            type: string

    TemplateBuildRequest:
      required:
        - dockerfile
      properties:
        alias:
          description: Alias of the template
          type: string
        dockerfile:
          description: Dockerfile for the template
          type: string
        startCmd:
          description: Start command to execute in the template after the build
          type: string
        cpuCount:
          description: CPU cores for the template
          type: integer
          minimum: 1
        memoryMB:
          description: Memory limit for the template in MB
          type: integer
          minimum: 128

    TemplateBuild:
      required:
        - templateID
        - buildID
        - finished
        - logs
      properties:
        logs:
          default: []
          description: Build logs
          type: array
          items:
            type: string
        templateID:
          type: string
          description: Identifier of the template
        buildID:
          type: string
          description: Identifier of the build
        status:
          type: string
          description: Status of the template
          enum:
            - building
            - ready
            - error

    Error:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
          description: Error code
        message:
          type: string
          description: Error

tags:
  - name: templates
  - name: sandboxes

paths:
  /health:
    get:
      description: Health check
      responses:
        200:
          description: Request was successful
        401:
          $ref: "#/components/responses/401"

  /sandboxes:
    get:
      description: List all running sandboxes
      tags: [sandboxes]
      security:
        - ApiKeyAuth: []
      responses:
        200:
          description: Successfully returned all running sandboxes
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                    - $ref: "#/components/schemas/RunningSandboxes"
        401:
          $ref: "#/components/responses/401"
        400:
          $ref: "#/components/responses/400"
        500:
          $ref: "#/components/responses/500"
    post:
      description: Create a sandbox from the template
      tags: [sandboxes]
      security:
        - ApiKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NewSandbox"
      responses:
        201:
          description: The sandbox was created successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Sandbox"
        401:
          $ref: "#/components/responses/401"
        400:
          $ref: "#/components/responses/400"
        500:
          $ref: "#/components/responses/500"

  /sandboxes/{sandboxID}/logs:
    get:
      description: Get sandbox logs
      tags: [sandboxes]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: "#/components/parameters/sandboxID"
        - in: query
          name: start
          schema:
            type: integer
          description: Starting timestamp of the logs that should be returned in milliseconds
        - in: query
          name: limit
          schema:
            default: 1000
            type: integer
          description: Maximum number of logs that should be returned
      responses:
        200:
          description: Successfully returned the sandbox logs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SandboxLogs"
        404:
          $ref: "#/components/responses/404"
        401:
          $ref: "#/components/responses/401"
        500:
          $ref: "#/components/responses/500"

  /sandboxes/{sandboxID}:
    delete:
      description: Kill a sandbox
      tags: [sandboxes]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: "#/components/parameters/sandboxID"
      responses:
        204:
          description: The sandbox was killed successfully
        404:
          $ref: "#/components/responses/404"
        401:
          $ref: "#/components/responses/401"
        500:
          $ref: "#/components/responses/500"

  /sandboxes/{sandboxID}/refreshes:
    post:
      description: Refresh the sandbox extending its time to live
      security:
        - ApiKeyAuth: []
      tags: [sandboxes]
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                duration:
                  description: Duration for which the sandbox should be kept alive in seconds
                  type: integer
                  maximum: 3600 # 1 hour
                  minimum: 0
      parameters:
        - $ref: "#/components/parameters/sandboxID"
      responses:
        204:
          description: Successfully refreshed the sandbox
        401:
          $ref: "#/components/responses/401"
        404:
          $ref: "#/components/responses/404"

  /templates:
    get:
      description: List all templates
      tags: [templates]
      security:
        - AccessTokenAuth: []
      responses:
        200:
          description: Successfully returned all templates
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                    - $ref: "#/components/schemas/Template"
        401:
          $ref: "#/components/responses/401"
        500:
          $ref: "#/components/responses/500"
    post:
      description: Create a new template
      tags: [templates]
      security:
        - AccessTokenAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TemplateBuildRequest"

      responses:
        202:
          description: The build was accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Template"
        401:
          $ref: "#/components/responses/401"
        500:
          $ref: "#/components/responses/500"

  /templates/{templateID}:
    post:
      description: Rebuild an template
      tags: [templates]
      security:
        - AccessTokenAuth: []
      parameters:
        - $ref: "#/components/parameters/templateID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TemplateBuildRequest"

      responses:
        202:
          description: The build was accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Template"
        401:
          $ref: "#/components/responses/401"
        500:
          $ref: "#/components/responses/500"
    delete:
      description: Delete a template
      tags: [templates]
      security:
        - AccessTokenAuth: []
      parameters:
        - $ref: "#/components/parameters/templateID"
      responses:
        204:
          description: The template was deleted successfully
        401:
          $ref: "#/components/responses/401"
        500:
          $ref: "#/components/responses/500"

  /templates/{templateID}/builds/{buildID}:
    post:
      description: Start the build
      tags: [templates]
      security:
        - AccessTokenAuth: []
      parameters:
        - $ref: "#/components/parameters/templateID"
        - $ref: "#/components/parameters/buildID"
      responses:
        202:
          description: The build has started
        401:
          $ref: "#/components/responses/401"
        500:
          $ref: "#/components/responses/500"

  /templates/{templateID}/builds/{buildID}/logs:
    post:
      description: Add a build log
      tags: [templates]
      parameters:
        - $ref: "#/components/parameters/templateID"
        - $ref: "#/components/parameters/buildID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - apiSecret
                - logs
              properties:
                apiSecret:
                  description: API secret
                  type: string
                logs:
                  type: array
                  items:
                    type: string
      responses:
        201:
          description: Successfully added log
        401:
          $ref: "#/components/responses/401"
        404:
          $ref: "#/components/responses/404"

  /templates/{templateID}/builds/{buildID}/status:
    get:
      description: Get template build info
      tags: [templates]
      security:
        - AccessTokenAuth: []
      parameters:
        - $ref: "#/components/parameters/templateID"
        - $ref: "#/components/parameters/buildID"
        - in: query
          name: logsOffset
          schema:
            default: 0
            type: integer
          description: Index of the starting build log that should be returned with the template
      responses:
        200:
          description: Successfully returned the template
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TemplateBuild"
        401:
          $ref: "#/components/responses/401"
        404:
          $ref: "#/components/responses/404"
        500:
          $ref: "#/components/responses/500"