swagger.yaml

basePath: /api/v1
definitions:
  handlers.ConcurrencyStatus:
    properties:
      available_slots:
        type: integer
      slots_acquired_total:
        type: integer
      slots_released_total:
        type: integer
      total_active_slots:
        type: integer
    type: object
  handlers.HealthResponse:
    properties:
      service:
        type: string
      status:
        type: string
      timestamp:
        type: string
      uptime:
        type: string
      version:
        type: string
    type: object
  handlers.ReadinessResponse:
    properties:
      checks:
        additionalProperties:
          type: string
        type: object
      status:
        type: string
      timestamp:
        type: string
    type: object
  handlers.WorkerManagerStatus:
    properties:
      is_healthy:
        type: boolean
      is_running:
        type: boolean
    type: object
  handlers.WorkerPoolStatus:
    properties:
      active_workers:
        type: integer
      average_task_time:
        example: 1m30s
        type: string
      idle_workers:
        type: integer
      pool_size:
        type: integer
      total_tasks_failed:
        type: integer
      total_tasks_processed:
        type: integer
      total_tasks_successful:
        type: integer
      unhealthy_workers:
        type: integer
    type: object
  handlers.WorkerStatusResponse:
    properties:
      concurrency:
        $ref: '#/definitions/handlers.ConcurrencyStatus'
      status:
        type: string
      timestamp:
        type: string
      worker_manager:
        $ref: '#/definitions/handlers.WorkerManagerStatus'
      worker_pool:
        $ref: '#/definitions/handlers.WorkerPoolStatus'
    type: object
  models.AuthResponse:
    properties:
      access_token:
        type: string
      expires_in:
        type: integer
      refresh_token:
        type: string
      token_type:
        type: string
      user:
        $ref: '#/definitions/models.UserResponse'
    type: object
  models.CreateTaskRequest:
    properties:
      description:
        maxLength: 1000
        type: string
      metadata:
        $ref: '#/definitions/models.JSONB'
      name:
        maxLength: 255
        minLength: 1
        type: string
      priority:
        maximum: 10
        minimum: 0
        type: integer
      script_content:
        maxLength: 65535
        minLength: 1
        type: string
      script_type:
        $ref: '#/definitions/models.ScriptType'
      timeout_seconds:
        maximum: 3600
        minimum: 1
        type: integer
    required:
    - name
    - script_content
    - script_type
    type: object
  models.ErrorResponse:
    properties:
      details:
        type: string
      error:
        type: string
      validation_errors:
        items:
          $ref: '#/definitions/models.ValidationError'
        type: array
    type: object
  models.ExecutionStatus:
    enum:
    - pending
    - running
    - completed
    - failed
    - timeout
    - cancelled
    type: string
    x-enum-varnames:
    - ExecutionStatusPending
    - ExecutionStatusRunning
    - ExecutionStatusCompleted
    - ExecutionStatusFailed
    - ExecutionStatusTimeout
    - ExecutionStatusCancelled
  models.JSONB:
    additionalProperties: true
    type: object
  models.LoginRequest:
    properties:
      email:
        type: string
      password:
        type: string
    required:
    - email
    - password
    type: object
  models.RefreshTokenRequest:
    properties:
      refresh_token:
        type: string
    required:
    - refresh_token
    type: object
  models.RegisterRequest:
    properties:
      email:
        type: string
      name:
        maxLength: 255
        minLength: 1
        type: string
      password:
        minLength: 8
        type: string
    required:
    - email
    - name
    - password
    type: object
  models.ScriptType:
    enum:
    - python
    - javascript
    - bash
    - go
    type: string
    x-enum-varnames:
    - ScriptTypePython
    - ScriptTypeJavaScript
    - ScriptTypeBash
    - ScriptTypeGo
  models.TaskExecutionResponse:
    properties:
      completed_at:
        type: string
      created_at:
        type: string
      execution_time_ms:
        type: integer
      id:
        type: string
      memory_usage_bytes:
        type: integer
      return_code:
        type: integer
      started_at:
        type: string
      status:
        $ref: '#/definitions/models.ExecutionStatus'
      stderr:
        type: string
      stdout:
        type: string
      task_id:
        type: string
    type: object
  models.TaskListResponse:
    properties:
      limit:
        type: integer
      offset:
        type: integer
      tasks:
        items:
          $ref: '#/definitions/models.TaskResponse'
        type: array
      total:
        type: integer
    type: object
  models.TaskResponse:
    properties:
      created_at:
        type: string
      description:
        type: string
      id:
        type: string
      metadata:
        $ref: '#/definitions/models.JSONB'
      name:
        type: string
      priority:
        type: integer
      script_content:
        type: string
      script_type:
        $ref: '#/definitions/models.ScriptType'
      status:
        $ref: '#/definitions/models.TaskStatus'
      timeout_seconds:
        type: integer
      updated_at:
        type: string
      user_id:
        type: string
    type: object
  models.TaskStatus:
    enum:
    - pending
    - running
    - completed
    - failed
    - timeout
    - cancelled
    type: string
    x-enum-varnames:
    - TaskStatusPending
    - TaskStatusRunning
    - TaskStatusCompleted
    - TaskStatusFailed
    - TaskStatusTimeout
    - TaskStatusCancelled
  models.UserResponse:
    properties:
      created_at:
        type: string
      email:
        type: string
      id:
        type: string
      name:
        type: string
      updated_at:
        type: string
    type: object
  models.ValidationError:
    properties:
      field:
        type: string
      message:
        type: string
      tag:
        type: string
      value:
        type: string
    type: object
host: localhost:8080
info:
  contact:
    email: support@voidrunner.com
    name: VoidRunner Support
    url: https://github.com/voidrunnerhq/voidrunner
  description: VoidRunner is a distributed task execution platform that allows users
    to create, manage, and execute code tasks securely in isolated containers.
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  termsOfService: https://voidrunner.com/terms
  title: VoidRunner API
  version: 1.0.0
paths:
  /api:
    get:
      description: Returns an HTML page with links to various API documentation formats
      produces:
      - text/html
      responses:
        "200":
          description: HTML documentation index
          schema:
            type: string
      summary: API Documentation Index
      tags:
      - Documentation
  /auth/login:
    post:
      consumes:
      - application/json
      description: Authenticates a user with email and password, returns access and
        refresh tokens
      parameters:
      - description: User login credentials
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/models.LoginRequest'
      produces:
      - application/json
      responses:
        "200":
          description: Login successful
          schema:
            $ref: '#/definitions/models.AuthResponse'
        "400":
          description: Invalid request format or validation error
          schema:
            $ref: '#/definitions/models.ErrorResponse'
        "401":
          description: Invalid credentials
          schema:
            $ref: '#/definitions/models.ErrorResponse'
        "429":
          description: Rate limit exceeded
          schema:
            $ref: '#/definitions/models.ErrorResponse'
      summary: Authenticate user
      tags:
      - Authentication
  /auth/logout:
    post:
      consumes:
      - application/json
      description: Logs out the current user (client-side token removal)
      produces:
      - application/json
      responses:
        "200":
          description: Logout successful
          schema:
            additionalProperties:
              type: string
            type: object
      summary: Logout user
      tags:
      - Authentication
  /auth/me:
    get:
      consumes:
      - application/json
      description: Returns information about the currently authenticated user
      produces:
      - application/json
      responses:
        "200":
          description: User information retrieved successfully
          schema:
            additionalProperties:
              $ref: '#/definitions/models.UserResponse'
            type: object
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/models.ErrorResponse'
      security:
      - BearerAuth: []
      summary: Get current user
      tags:
      - Authentication
  /auth/refresh:
    post:
      consumes:
      - application/json
      description: Generates a new access token using a valid refresh token
      parameters:
      - description: Refresh token request
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/models.RefreshTokenRequest'
      produces:
      - application/json
      responses:
        "200":
          description: Token refreshed successfully
          schema:
            $ref: '#/definitions/models.AuthResponse'
        "400":
          description: Invalid request format
          schema:
            $ref: '#/definitions/models.ErrorResponse'
        "401":
          description: Invalid refresh token
          schema:
            $ref: '#/definitions/models.ErrorResponse'
        "429":
          description: Rate limit exceeded
          schema:
            $ref: '#/definitions/models.ErrorResponse'
      summary: Refresh access token
      tags:
      - Authentication
  /auth/register:
    post:
      consumes:
      - application/json
      description: Creates a new user account with email and password
      parameters:
      - description: User registration details
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/models.RegisterRequest'
      produces:
      - application/json
      responses:
        "201":
          description: User registered successfully
          schema:
            $ref: '#/definitions/models.AuthResponse'
        "400":
          description: Invalid request format or validation error
          schema:
            $ref: '#/definitions/models.ErrorResponse'
        "409":
          description: User already exists
          schema:
            $ref: '#/definitions/models.ErrorResponse'
        "429":
          description: Rate limit exceeded
          schema:
            $ref: '#/definitions/models.ErrorResponse'
      summary: Register a new user
      tags:
      - Authentication
  /docs:
    get:
      description: Redirects to the Swagger UI interface
      responses:
        "302":
          description: Redirect to Swagger UI
          schema:
            type: string
      summary: Redirect to Swagger UI
      tags:
      - Documentation
  /docs/swagger.json:
    get:
      description: Returns the OpenAPI specification in JSON format
      produces:
      - application/json
      responses:
        "200":
          description: OpenAPI specification
          schema:
            additionalProperties: true
            type: object
      summary: Get OpenAPI JSON specification
      tags:
      - Documentation
  /docs/swagger.yaml:
    get:
      description: Returns the OpenAPI specification in YAML format
      produces:
      - text/yaml
      responses:
        "200":
          description: OpenAPI specification in YAML
          schema:
            type: string
      summary: Get OpenAPI YAML specification
      tags:
      - Documentation
  /health:
    get:
      consumes:
      - application/json
      description: Returns the health status of the API service
      produces:
      - application/json
      responses:
        "200":
          description: Service is healthy
          schema:
            $ref: '#/definitions/handlers.HealthResponse'
      summary: Health check
      tags:
      - Health
  /health/workers:
    get:
      description: Returns detailed status information about the embedded worker system
      produces:
      - application/json
      responses:
        "200":
          description: OK
          schema:
            $ref: '#/definitions/handlers.WorkerStatusResponse'
        "503":
          description: Service Unavailable
          schema:
            additionalProperties:
              type: string
            type: object
      summary: Worker status
      tags:
      - Health
  /ready:
    get:
      consumes:
      - application/json
      description: Returns the readiness status of the API service and its dependencies
      produces:
      - application/json
      responses:
        "200":
          description: Service is ready
          schema:
            $ref: '#/definitions/handlers.ReadinessResponse'
        "503":
          description: Service is not ready
          schema:
            $ref: '#/definitions/handlers.ReadinessResponse'
      summary: Readiness check
      tags:
      - Health
  /tasks:
    get:
      consumes:
      - application/json
      description: Retrieves a paginated list of tasks owned by the authenticated
        user
      parameters:
      - default: 20
        description: Maximum number of tasks to return
        in: query
        name: limit
        type: integer
      - default: 0
        description: Number of tasks to skip
        in: query
        name: offset
        type: integer
      produces:
      - application/json
      responses:
        "200":
          description: Tasks retrieved successfully
          schema:
            $ref: '#/definitions/models.TaskListResponse'
        "400":
          description: Invalid query parameters
          schema:
            $ref: '#/definitions/models.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/models.ErrorResponse'
        "429":
          description: Rate limit exceeded
          schema:
            $ref: '#/definitions/models.ErrorResponse'
      security:
      - BearerAuth: []
      summary: List user's tasks
      tags:
      - Tasks
    post:
      consumes:
      - application/json
      description: Creates a new task with the specified script content and configuration
      parameters:
      - description: Task creation details
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/models.CreateTaskRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Task created successfully
          schema:
            $ref: '#/definitions/models.TaskResponse'
        "400":
          description: Invalid request format or validation error
          schema:
            $ref: '#/definitions/models.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/models.ErrorResponse'
        "429":
          description: Rate limit exceeded
          schema:
            $ref: '#/definitions/models.ErrorResponse'
      security:
      - BearerAuth: []
      summary: Create a new task
      tags:
      - Tasks
  /tasks/{id}:
    get:
      consumes:
      - application/json
      description: Retrieves detailed information about a specific task
      parameters:
      - description: Task ID
        in: path
        name: id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Task retrieved successfully
          schema:
            $ref: '#/definitions/models.TaskResponse'
        "400":
          description: Invalid task ID
          schema:
            $ref: '#/definitions/models.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/models.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/models.ErrorResponse'
        "404":
          description: Task not found
          schema:
            $ref: '#/definitions/models.ErrorResponse'
        "429":
          description: Rate limit exceeded
          schema:
            $ref: '#/definitions/models.ErrorResponse'
      security:
      - BearerAuth: []
      summary: Get task details
      tags:
      - Tasks
  /tasks/{task_id}/executions:
    post:
      consumes:
      - application/json
      description: Starts execution of the specified task
      parameters:
      - description: Task ID
        in: path
        name: task_id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "201":
          description: Execution started successfully
          schema:
            $ref: '#/definitions/models.TaskExecutionResponse'
        "400":
          description: Invalid task ID
          schema:
            $ref: '#/definitions/models.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/models.ErrorResponse'
        "403":
          description: Forbidden
          schema:
            $ref: '#/definitions/models.ErrorResponse'
        "404":
          description: Task not found
          schema:
            $ref: '#/definitions/models.ErrorResponse'
        "409":
          description: Task is already running
          schema:
            $ref: '#/definitions/models.ErrorResponse'
        "429":
          description: Rate limit exceeded
          schema:
            $ref: '#/definitions/models.ErrorResponse'
      security:
      - BearerAuth: []
      summary: Start task execution
      tags:
      - Executions
securityDefinitions:
  BearerAuth:
    description: Type "Bearer" followed by a space and JWT token.
    in: header
    name: Authorization
    type: apiKey
swagger: "2.0"