openapi: "3.0.0"

info:
  version: "1.0.0"
  title: vStash S3 Compatible API
  description: |
    A high-performance S3-compatible object storage API with management console.
    
    ## Features
    - Full S3 API compatibility for basic operations
    - Multipart upload support
    - Presigned URLs
    - Management console API
    - Enterprise storage backend
    
    ## Authentication
    Uses AWS Signature Version 4 for S3 API endpoints and API keys for management endpoints.
  contact:
    email: support@vultr.com
    name: 'vStash Support'
    url: https://www.vultr.com
  x-logo:
    url: 'https://www.vultr.com/dist/img/brand/vultr-logo-onwhite.svg'
    backgroundColor: '#fafafa'
    altText: 'vStash - S3 Compatible API and Management'

servers:
  - url: https://vstash.vultr.com
    description: Production server
  - url: https://vstash-staging.vultr.com  
    description: Staging server
  - url: http://localhost:8000
    description: Development server

tags:
  - name: S3 Buckets
    description: S3 bucket operations
  - name: S3 Objects
    description: S3 object operations
  - name: S3 Multipart
    description: S3 multipart upload operations
  - name: Management - Stats
    description: System statistics and monitoring
  - name: Management - Credentials
    description: Access key and credential management
  - name: Management - Buckets
    description: Bucket management via console
  - name: Management - Objects
    description: Object management via console
  - name: Management - Presigned URLs
    description: Presigned URL management

paths:
  $ref: './paths.yaml'

components:
  schemas:
    $ref: './schemas.yaml'
  parameters:
    $ref: './parameters.yaml'
  securitySchemes:
    $ref: './security.yaml'
  responses:
    '400':
      description: Bad Request
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/S3Error'
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    '401':
      description: Unauthorized
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/S3Error'
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    '403':
      description: Forbidden
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/S3Error'
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    '404':
      description: Not Found
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/S3Error'
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    '409':
      description: Conflict
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/S3Error'
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'
    '500':
      description: Internal Server Error
      content:
        application/xml:
          schema:
            $ref: '#/components/schemas/S3Error'
        application/json:
          schema:
            $ref: '#/components/schemas/ApiError'