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
    AdminTokenAuth:
      type: apiKey
      in: header
      name: X-Admin-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
    nodeID:
      name: nodeID
      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"
    "409":
      description: Conflict
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    "500":
      description: Server error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"

  schemas:
    Team:
      required:
        - teamID
        - name
        - apiKey
        - isDefault
      properties:
        teamID:
          type: string
          description: Identifier of the team
        name:
          type: string
          description: Name of the team
        apiKey:
          type: string
          description: API key for the team
        isDefault:
          type: boolean
          description: Whether the team is the default team

    TeamUser:
      required:
        - id
        - email
      properties:
        id:
          type: string
          format: uuid
          description: Identifier of the user
        email:
          type: string
          description: Email of the user

    TemplateUpdateRequest:
      properties:
        public:
          type: boolean
          description: Whether the template is public or only accessible by the team

    CPUCount:
      type: integer
      format: int32
      minimum: 1
      maximum: 8
      description: CPU cores for the sandbox

    MemoryMB:
      type: integer
      format: int32
      minimum: 128
      maximum: 8192
      description: Memory for the sandbox in MB

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

    EnvVars:
      additionalProperties:
        type: string
        description: Environment variables for 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
        - envdVersion
      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
        envdVersion:
          type: string
          description: Version of the envd running in the sandbox

    RunningSandbox:
      required:
        - templateID
        - sandboxID
        - clientID
        - startedAt
        - cpuCount
        - memoryMB
        - endAt
      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
        endAt:
          type: string
          format: date-time
          description: Time when the sandbox will expire
        cpuCount:
          $ref: "#/components/schemas/CPUCount"
        memoryMB:
          $ref: "#/components/schemas/MemoryMB"
        metadata:
          $ref: "#/components/schemas/SandboxMetadata"

    NewSandbox:
      required:
        - templateID
      properties:
        templateID:
          type: string
          description: Identifier of the required template
        timeout:
          type: integer
          format: int32
          minimum: 0
          default: 15
          description: Time to live for the sandbox in seconds.
        metadata:
          $ref: "#/components/schemas/SandboxMetadata"
        envVars:
          $ref: "#/components/schemas/EnvVars"

    ResumedSandbox:
      properties:
        timeout:
          type: integer
          format: int32
          minimum: 0
          default: 15
          description: Time to live for the sandbox in seconds.

    Template:
      required:
        - templateID
        - buildID
        - cpuCount
        - memoryMB
        - public
        - createdAt
        - updatedAt
        - createdBy
        - lastSpawnedAt
        - spawnCount
        - buildCount
      properties:
        templateID:
          type: string
          description: Identifier of the template
        buildID:
          type: string
          description: Identifier of the last successful build for given template
        cpuCount:
          $ref: "#/components/schemas/CPUCount"
        memoryMB:
          $ref: "#/components/schemas/MemoryMB"
        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
        createdAt:
          type: string
          format: date-time
          description: Time when the template was created
        updatedAt:
          type: string
          format: date-time
          description: Time when the template was last updated
        createdBy:
          allOf:
            - $ref: "#/components/schemas/TeamUser"
          nullable: true
        lastSpawnedAt:
          type: string
          format: date-time
          description: Time when the template was last used
        spawnCount:
          type: integer
          format: int64
          description: Number of times the template was used
        buildCount:
          type: integer
          format: int32
          description: Number of times the template was built

    TemplateBuildRequest:
      required:
        - dockerfile
      properties:
        alias:
          description: Alias of the template
          type: string
        dockerfile:
          description: Dockerfile for the template
          type: string
        teamID:
          type: string
          description: Identifier of the team
        startCmd:
          description: Start command to execute in the template after the build
          type: string
        cpuCount:
          $ref: "#/components/schemas/CPUCount"
        memoryMB:
          $ref: "#/components/schemas/MemoryMB"

    TemplateBuild:
      required:
        - templateID
        - buildID
        - status
        - 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

    NodeStatus:
      type: string
      description: Status of the node
      enum:
        - ready
        - draining

    NodeStatusChange:
      required:
        - status
      properties:
        status:
          $ref: "#/components/schemas/NodeStatus"

    Node:
      required:
        - nodeID
        - status
        - sandboxCount
        - allocatedCPU
        - allocatedMemoryMiB
      properties:
        nodeID:
          type: string
          description: Identifier of the node
        status:
          $ref: "#/components/schemas/NodeStatus"
        sandboxCount:
          type: integer
          format: int32
          description: Number of sandboxes running on the node
        allocatedCPU:
          type: integer
          format: int32
          description: Number of allocated CPU cores
        allocatedMemoryMiB:
          type: integer
          format: int32
          description: Amount of allocated memory in MiB

    NodeDetail:
      required:
        - nodeID
        - status
        - sandboxes
        - cachedBuilds
      properties:
        nodeID:
          type: string
          description: Identifier of the node
        status:
          $ref: "#/components/schemas/NodeStatus"
        sandboxes:
          type: array
          description: List of sandboxes running on the node
          items:
            $ref: "#/components/schemas/RunningSandbox"
        cachedBuilds:
          type: array
          description: List of cached builds id on the node
          items:
            type: string


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

tags:
  - name: templates
  - name: sandboxes
  - name: auth

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

  /teams:
    get:
      description: List all teams
      tags: [auth]
      security:
        - AccessTokenAuth: []
      responses:
        "200":
          description: Successfully returned all teams
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                    - $ref: "#/components/schemas/Team"
        "401":
          $ref: "#/components/responses/401"
        "500":
          $ref: "#/components/responses/500"

  /sandboxes:
    get:
      description: List all running sandboxes
      tags: [sandboxes]
      security:
        - ApiKeyAuth: []
      parameters:
        - name: filter
          in: query
          description: A list of filters with key-value pairs (e.g. user:abc, app:prod).
          required: false
          schema:
            type: array
            items:
              type: string
      responses:
        "200":
          description: Successfully returned all running sandboxes
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                    - $ref: "#/components/schemas/RunningSandbox"
        "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
            format: int64
            minimum: 0
          description: Starting timestamp of the logs that should be returned in milliseconds
        - in: query
          name: limit
          schema:
            default: 1000
            format: int32
            minimum: 0
            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}:
    get:
      description: Get a sandbox by id
      tags: [sandboxes]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: "#/components/parameters/sandboxID"
      responses:
        "200":
          description: Successfully returned the sandbox
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunningSandbox"
        "404":
          $ref: "#/components/responses/404"
        "401":
          $ref: "#/components/responses/401"
        "500":
          $ref: "#/components/responses/500"

    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"

  # TODO: Pause and resume might be exposed as POST /sandboxes/{sandboxID}/snapshot and then POST /sandboxes with specified snapshotting setup
  /sandboxes/{sandboxID}/pause:
    post:
      description: Pause the sandbox
      tags: [sandboxes]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: "#/components/parameters/sandboxID"
      responses:
        "204":
          description: The sandbox was paused successfully and can be resumed
        "409":
          $ref: "#/components/responses/409"
        "404":
          $ref: "#/components/responses/404"
        "401":
          $ref: "#/components/responses/401"
        "500":
          $ref: "#/components/responses/500"

  /sandboxes/{sandboxID}/resume:
    post:
      description: Resume the sandbox
      tags: [sandboxes]
      security:
        - ApiKeyAuth: []
      parameters:
        - $ref: "#/components/parameters/sandboxID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ResumedSandbox"
      responses:
        "201":
          description: The sandbox was resumed successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Sandbox"
        "409":
          $ref: "#/components/responses/409"
        "404":
          $ref: "#/components/responses/404"
        "401":
          $ref: "#/components/responses/401"
        "500":
          $ref: "#/components/responses/500"

  /sandboxes/{sandboxID}/timeout:
    post:
      description: Set the timeout for the sandbox. The sandbox will expire x seconds from the time of the request. Calling this method multiple times overwrites the TTL, each time using the current timestamp as the starting point to measure the timeout duration.
      security:
        - ApiKeyAuth: []
      tags: [sandboxes]
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - timeout
              properties:
                timeout:
                  description: Timeout in seconds from the current time after which the sandbox should expire
                  type: integer
                  format: int32
                  minimum: 0
      parameters:
        - $ref: "#/components/parameters/sandboxID"
      responses:
        "204":
          description: Successfully set the sandbox timeout
        "401":
          $ref: "#/components/responses/401"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"

  /sandboxes/{sandboxID}/refreshes:
    post:
      description: Refresh the sandbox extending its time to live
      security:
        - ApiKeyAuth: []
      tags: [sandboxes]
      requestBody:
        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: []
      parameters:
        - in: query
          required: false
          name: teamID
          schema:
            type: string
            description: Identifier of the team
      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"
    patch:
      description: Update template
      tags: [templates]
      security:
        - AccessTokenAuth: []
      parameters:
        - $ref: "#/components/parameters/templateID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/TemplateUpdateRequest"
      responses:
        "200":
          description: The template was updated successfully
        "400":
          $ref: "#/components/responses/400"
        "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}/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
            format: int32
            minimum: 0
          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"

  /nodes:
    get:
      description: List all nodes
      tags: [admin]
      security:
        - AdminTokenAuth: []
      responses:
        "200":
          description: Successfully returned all nodes
          content:
            application/json:
              schema:
                type: array
                items:
                  allOf:
                    - $ref: "#/components/schemas/Node"
        "401":
          $ref: "#/components/responses/401"
        "500":
          $ref: "#/components/responses/500"

  /nodes/{nodeID}:
    get:
      description: Get node info
      tags: [admin]
      security:
        - AdminTokenAuth: []
      parameters:
        - $ref: "#/components/parameters/nodeID"
      responses:
        "200":
          description: Successfully returned the node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/NodeDetail"
        "401":
          $ref: "#/components/responses/401"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"
    post:
      description: Change status of a node
      tags: [admin]
      security:
        - AdminTokenAuth: []
      parameters:
        - $ref: "#/components/parameters/nodeID"
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/NodeStatusChange"
      responses:
        "204":
          description: The node status was changed successfully
        "401":
          $ref: "#/components/responses/401"
        "404":
          $ref: "#/components/responses/404"
        "500":
          $ref: "#/components/responses/500"