openapi.argus.yaml

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

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

components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
    AccessTokenAuth:
      type: http
      scheme: bearer
      bearerFormat: access_token
    # Generated code uses security schemas in the alphabetical order.
    # In order to check first the token, and then the team (so we can already use the user),
    # there is a 1 and 2 present in the names of the security schemas.
    Supabase1TokenAuth:
      type: apiKey
      in: header
      name: X-Supabase-Token
    Supabase2TeamAuth:
      type: apiKey
      in: header
      name: X-Supabase-Team
    AdminTokenAuth:
      type: apiKey
      in: header
      name: X-Admin-Token

  parameters:
    sandboxID:
      name: sandboxID
      in: path
      required: true
      schema:
        type: string
    webhookID:
      name: webhookID
      in: path
      required: true
      schema:
        type: string
        format: uuid

  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:
    Error:
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
          description: Error code
        message:
          type: string
          description: Error

    SandboxEvent:
      description: Sandbox event
      required:
        - id
        - version
        - type
        - timestamp
        - sandboxId
        - sandboxExecutionId
        - sandboxTemplateId
        - sandboxBuildId
        - sandboxTeamId
      properties:
        id:
          type: string
          format: uuid
          description: Event unique identifier
        version:
          type: string
          description: Event structure version
        type:
          type: string
          description: Event name
        eventCategory:
          type: string
          deprecated: true
          description: Category of the event (e.g., 'lifecycle', 'process', etc.)
        eventLabel:
          type: string
          deprecated: true
          description: Label for the specific event type (e.g., 'sandbox_started', 'process_oom', etc.)
        eventData:
          type: object
          nullable: true
          description: Optional JSON data associated with the event

        timestamp:
          type: string
          format: date-time
          description: Timestamp of the event
        sandboxId:
          type: string
          format: string
          description: Unique identifier for the sandbox
        sandboxExecutionId:
          type: string
          format: string
          description: Unique identifier for the sandbox execution
        sandboxTemplateId:
          type: string
          format: string
          description: Unique identifier for the sandbox template
        sandboxBuildId:
          type: string
          format: string
          description: Unique identifier for the sandbox build
        sandboxTeamId:
          type: string
          format: uuid
          description: Team identifier associated with the sandbox

    WebhookCreate:
      description: Configuration for registering new webhooks
      required:
        - name
        - url
        - events
        - signatureSecret
      properties:
        name:
          type: string
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
        enabled:
          type: boolean
          default: true
        signatureSecret:
          type: string
          description: Secret used to sign the webhook payloads

    WebhookCreation:
      description: Webhook creation response
      required:
        - id
        - name
        - createdAt
        - teamId
        - url
        - enabled
        - events
      properties:
        id:
          type: string
          description: Webhook unique identifier
        name:
          type: string
          description: Webhook user friendly name
        createdAt:
          type: string
          format: date-time
          description: Time when the template was created
        teamId:
          type: string
          description: Unique identifier for the team
        url:
          type: string
          format: uri
        enabled:
          type: boolean
        events:
          type: array
          items:
            type: string

    WebhookDetail:
      description: Webhook detail response
      required:
        - id
        - teamId
        - name
        - createdAt
        - url
        - enabled
        - events
      properties:
        id:
          type: string
          description: Webhook unique identifier
        teamId:
          type: string
          description: Unique identifier for the team
        name:
          type: string
          description: Webhook user friendly name
        createdAt:
          type: string
          format: date-time
          description: Time when the template was created
        url:
          type: string
          format: uri
        enabled:
          type: boolean
        events:
          type: array
          items:
            type: string

    WebhookConfiguration:
      description: Configuration for updating existing webhooks
      properties:
        enabled:
          type: boolean
        name:
          type: string
          description: Webhook user friendly name
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
        signatureSecret:
          type: string
          description: Secret used to sign the webhook payloads

    WebhookDelivery:
      description: Webhook delivery attempt
      required:
        - id
        - teamId
        - webhookId
        - eventId
        - sandboxId
        - eventType
        - status
        - durationMs
        - requestBody
        - requestHeaders
        - requestUrl
        - errorClass
        - timestamp
      properties:
        id:
          type: string
          format: uuid
          description: Delivery attempt identifier
        teamId:
          type: string
          format: uuid
          description: Team identifier
        webhookId:
          type: string
          format: uuid
          description: Webhook configuration identifier
        eventId:
          type: string
          format: uuid
          description: Sandbox event identifier
        sandboxId:
          type: string
          description: Sandbox identifier
        eventType:
          type: string
          description: Sandbox event type
        status:
          type: string
          enum: [success, failed]
          description: Delivery attempt status
        durationMs:
          type: integer
          format: int32
          description: Delivery request duration in milliseconds
        requestBody:
          type: string
          description: Serialized webhook request body
        requestHeaders:
          type: string
          description: JSON-encoded request headers with sensitive values redacted
        requestUrl:
          type: string
          format: uri
          description: URL attempted for this delivery
        responseBody:
          type: string
          nullable: true
          description: Truncated response body, if a response was received
        responseHeaders:
          type: string
          nullable: true
          description: JSON-encoded response headers, if a response was received
        responseHttpStatusCode:
          type: integer
          format: int32
          nullable: true
          description: HTTP response status code, if a response was received
        errorClass:
          type: string
          nullable: true
          enum:
            - http_error
            - dns_error
            - timeout
            - transport_error
            - request_error
            - signature_error
            - canceled
          description: Machine-readable non-HTTP or HTTP failure class
        errorMessage:
          type: string
          nullable: true
          description: Error message for failures without a useful response body
        timestamp:
          type: string
          format: date-time
          description: Time when the delivery attempt started

    WebhookDeliveryStats:
      description: Webhook delivery aggregate stats
      required:
        - buckets
        - total
        - failed
        - durationMs
      properties:
        buckets:
          type: array
          items:
            $ref: "#/components/schemas/WebhookDeliveryStatsBucket"
        total:
          type: integer
          format: int64
        failed:
          type: integer
          format: int64
        durationMs:
          $ref: "#/components/schemas/WebhookDeliveryDurationStats"

    WebhookDeliveryDurationStats:
      description: Webhook delivery duration statistics in milliseconds
      required:
        - minimum
        - average
        - maximum
      properties:
        minimum:
          type: number
          format: double
        average:
          type: number
          format: double
        maximum:
          type: number
          format: double

    WebhookDeliveryStatsBucket:
      description: Webhook delivery stats for a time bucket
      required:
        - timestamp
        - total
        - failed
        - durationMs
      properties:
        timestamp:
          type: string
          format: date-time
        total:
          type: integer
          format: int64
        failed:
          type: integer
          format: int64
        durationMs:
          $ref: "#/components/schemas/WebhookDeliveryDurationStats"

    WebhookDeliveryGroup:
      description: Webhook delivery attempts grouped by sandbox event
      required:
        - eventId
        - eventType
        - sandboxId
        - attempts
      properties:
        eventId:
          type: string
          format: uuid
        eventType:
          type: string
        sandboxId:
          type: string
        attempts:
          type: array
          items:
            $ref: "#/components/schemas/WebhookDelivery"

    WebhookDeliveriesListPayload:
      description: Paginated webhook delivery attempts grouped by event
      required:
        - data
        - nextCursor
      properties:
        data:
          type: array
          items:
            $ref: "#/components/schemas/WebhookDeliveryGroup"
        nextCursor:
          type: string
          nullable: true
          description: Cursor to pass to the next list request, or null when there is no next page.

paths:
  /health:
    get:
      description: Health check
      responses:
        200:
          description: Request was successful
        401:
          $ref: "#/components/responses/401"
  
  /events/sandboxes/{sandboxID}:
    get:
      description: Get sandbox events
      tags: [events]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: "#/components/parameters/sandboxID"
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 0
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 10
        - name: orderAsc
          in: query
          required: false
          schema:
            type: boolean
            default: false
        - name: types
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
          description: Filter events to the provided event types
      responses:
        "200":
          description: Successfully returned the sandbox events
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SandboxEvent"
        "400":
          $ref: "#/components/responses/400"
        "404":
          $ref: "#/components/responses/404"
        "401":
          $ref: "#/components/responses/401"
        "500":
          $ref: "#/components/responses/500"

  /events/sandboxes:
    get:
      description: Get all sandbox events for the team associated with the API key
      tags: [events]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 0
            default: 0
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 10
        - name: orderAsc
          in: query
          required: false
          schema:
            type: boolean
            default: false
        - name: types
          in: query
          required: false
          style: form
          explode: true
          schema:
            type: array
            items:
              type: string
          description: Filter events to the provided event types
      responses:
        "200":
          description: Successfully returned the sandbox events
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/SandboxEvent"
        "400":
          $ref: "#/components/responses/400"
        "404":
          $ref: "#/components/responses/404"
        "401":
          $ref: "#/components/responses/401"
        "500":
          $ref: "#/components/responses/500"

  /events/webhooks:
    post:
      operationId: webhookCreate
      description: Register events webhook.
      tags: [webhooks]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WebhookCreate"
      responses:
        "201":
          description: Successfully created webhook.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookCreation"
        "400":
          $ref: "#/components/responses/400"
        "404":
          $ref: "#/components/responses/404"
        "401":
          $ref: "#/components/responses/401"
        "500":
          $ref: "#/components/responses/500"
    get:
        operationId: webhooksList
        description: List registered webhooks.
        tags: [webhooks]
        security:
          - ApiKeyAuth: []
          - Supabase1TokenAuth: []
            Supabase2TeamAuth: []
        responses:
          "200":
            description: List of registered webhooks.
            content:
              application/json:
                schema:
                  type: array
                  items:
                    $ref: "#/components/schemas/WebhookDetail"
          "404":
            $ref: "#/components/responses/404"
          "401":
            $ref: "#/components/responses/401"
          "500":
            $ref: "#/components/responses/500"

  /events/webhooks/{webhookID}:
    get:
      operationId: webhookGet
      description: Get a registered webhook.
      tags: [webhooks]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: "#/components/parameters/webhookID"
      responses:
        "200":
          description: Successfully returned the webhook configuration.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookDetail"
        "404":
          $ref: "#/components/responses/404"
        "401":
          $ref: "#/components/responses/401"
        "500":
          $ref: "#/components/responses/500"

    patch:
      operationId: webhookUpdate
      description: Update a registered webhook configuration.
      tags: [webhooks]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: "#/components/parameters/webhookID"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/WebhookConfiguration"
      responses:
        "200":
          description: Successfully updated webhook.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookDetail"
        "400":
          $ref: "#/components/responses/400"
        "404":
          $ref: "#/components/responses/404"
        "401":
          $ref: "#/components/responses/401"
        "500":
          $ref: "#/components/responses/500"

    delete:
      operationId: webhookDelete
      description: Delete a registered webhook.
      tags: [webhooks]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: "#/components/parameters/webhookID"
      responses:
        "200":
          description: Successfully deleted webhook.
        "404":
          $ref: "#/components/responses/404"
        "401":
          $ref: "#/components/responses/401"
        "500":
          $ref: "#/components/responses/500"

  /events/webhooks/{webhookID}/deliveries:
    get:
      operationId: webhookDeliveriesList
      description: List webhook delivery attempts.
      tags: [webhooks]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: "#/components/parameters/webhookID"
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: Opaque cursor from the previous response's nextCursor field.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            format: int32
            minimum: 1
            maximum: 100
            default: 25
        - name: orderAsc
          in: query
          required: false
          schema:
            type: boolean
            default: false
        - name: start
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Include deliveries at or after this timestamp.
        - name: end
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Include deliveries before this timestamp.
        - name: deliveryStatus
          in: query
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
              enum: [success, failed]
          description: Filter deliveries by delivery status
        - name: eventType
          in: query
          required: false
          style: form
          explode: false
          schema:
            type: array
            items:
              type: string
          description: Filter deliveries by event type
      responses:
        "200":
          description: List of webhook delivery attempts grouped by event.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookDeliveriesListPayload"
        "400":
          $ref: "#/components/responses/400"
        "404":
          $ref: "#/components/responses/404"
        "401":
          $ref: "#/components/responses/401"
        "500":
          $ref: "#/components/responses/500"

  /events/webhooks/{webhookID}/stats:
    get:
      operationId: webhookDeliveryStats
      description: Get webhook delivery aggregate stats.
      tags: [webhooks]
      security:
        - ApiKeyAuth: []
        - Supabase1TokenAuth: []
          Supabase2TeamAuth: []
      parameters:
        - $ref: "#/components/parameters/webhookID"
        - name: start
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Inclusive stats range start. Defaults to 24 hours ago.
        - name: end
          in: query
          required: false
          schema:
            type: string
            format: date-time
          description: Exclusive stats range end. Defaults to now.
      responses:
        "200":
          description: Webhook delivery stats.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookDeliveryStats"
        "404":
          $ref: "#/components/responses/404"
        "401":
          $ref: "#/components/responses/401"
        "500":
          $ref: "#/components/responses/500"