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:
    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

    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"

    Template:
      required:
        - templateID
        - buildID
        - cpuCount
        - memoryMB
        - public
      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

    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

    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: []
      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}:
    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}/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"

  /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"