openapi: "3.0.0"
info:
  title: Autopilot API
  version: 2.0.0
  description: API for managing Autopilot configuration and related operations.

paths:
  #############################
  #
  # Autopilot routes
  #
  #############################
  /autopilot/config/evaluate:
    post:
      summary: Evaluate autopilot configuration
      description: Evaluates the provided autopilot configuration and returns some information about the hosts that would be considered usable using that configuration. If possible, it also returns a recommendation for a better configuration that would allow for forming contracts with more hosts.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                autopilotConfig:
                  $ref: "#/components/schemas/AutopilotConfig"
                gougingSettings:
                  $ref: "#/components/schemas/GougingSettings"
                redundancySettings:
                  $ref: "#/components/schemas/RedundancySettings"
      responses:
        "400":
          description: Malformed request
          content:
            text/plain:
              schema:
                type: string
        "500":
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
        "200":
          description: The evaluated autopilot configuration
          content:
            application/json:
              schema:
                type: object
                properties:
                  hosts:
                    type: integer
                    format: uin64
                    description: Number of hosts available
                  usable:
                    type: integer
                    format: uint64
                    description: Number of hosts that the autopilot could form contracts with using the provided config
                  unusable:
                    type: object
                    properties:
                      blocked:
                        type: integer
                        format: uint64
                        description: Number of hosts unavailable due to being blocklisted
                      gouging:
                        type: object
                        properties:
                          contract:
                            type: integer
                            format: uint64
                            description: Number of hosts that fail the contract gouging checks
                          download:
                            type: integer
                            format: uint64
                            description: Number of hosts that fail the download gouging checks
                          gouging:
                            type: integer
                            format: uint64
                            description: Number of hosts that fail the general gouging checks
                          pruning:
                            type: integer
                            format: uint64
                            description: Number of hosts that fail the pruning gouging checks
                          upload:
                            type: integer
                            format: uint64
                            description: Number of hosts that fail the upload gouging checks
                      lowMaxDuration:
                        type: integer
                        format: uint64
                        description: Number of hosts that have a max contract duration that is too low
                      notAcceptingContracts:
                        type: integer
                        format: uint64
                        description: Number of hosts that are not accepting contracts
                      notScanned:
                        type: integer
                        format: uint64
                        description: Number of hosts that haven't been successfully scanned yet
                  recommendation:
                    $ref: "#/components/schemas/ConfigRecommendation"

  /autopilot/state:
    get:
      summary: Get the autopilot state
      description: Returns the current state of the autopilot, including migration, pruning, and scanning status.
      responses:
        "200":
          description: The current state of the autopilot
          content:
            application/json:
              schema:
                type: object
                allOf:
                  - $ref: "#/components/schemas/BuildState"
                properties:
                  enabled:
                    type: boolean
                    description: Whether the autopilot is enabled
                  migrating:
                    type: boolean
                    description: Indicates if the autopilot is currently migrating
                  migratingLastStart:
                    type: string
                    format: date-time
                    description: When migration last started
                  pruning:
                    type: boolean
                    description: Indicates if the autopilot is currently pruning
                  pruningLastStart:
                    type: string
                    format: date-time
                    description: When pruning last started
                  scanning:
                    type: boolean
                    description: Indicates if the autopilot is currently scanning
                  scanningLastStart:
                    type: string
                    format: date-time
                    description: When scanning last started
                  uptimeMs:
                    type: integer
                    format: int64
                    description: The autopilot uptime in milliseconds
                  startTime:
                    type: string
                    format: date-time
                    description: When the autopilot was started

  /autopilot/trigger:
    post:
      summary: Wake up autopilot
      description: Triggers the autopilot to start an iteration of contract maintenance and host scanning.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                forceScan:
                  type: boolean
                  description: If true, the autopilot force a new batch of host scans even if it recently scanned the hosts.
                  default: false
      responses:
        "400":
          description: Malformed request
          content:
            text/plain:
              schema:
                type: string
        "200":
          description: Successfully attempted to trigger the autopilot
          content:
            application/json:
              schema:
                type: object
                properties:
                  triggered:
                    type: boolean
                    description: Indicates whether the request triggered a new iteration of the maintenance loop. If maintenance was already ongoing, this will be false.

  #############################
  #
  # Autopilot routes
  #
  #############################
  /worker/account/{hostkey}:
    get:
      summary: Get a worker account
      description: Returns the account the worker maintains with the specified host for payment.
      parameters:
        - name: hostkey
          in: path
          required: true
          schema:
            $ref: "#/components/schemas/PublicKey"
          description: The host's public key
      responses:
        "200":
          description: Successfully retrieved worker account
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Account"

  /worker/accounts:
    get:
      summary: Get all worker accounts
      description: Returns all accounts the worker maintains with hosts for payment.
      responses:
        "200":
          description: Successfully retrieved worker accounts
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Account"

  /worker/{id}/resetdrift:
    post:
      summary: Reset drift for a worker's account
      description: Resets the drift for the specified account to 0.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            allOf:
              - $ref: "#/components/schemas/PublicKey"
              - description: The account's ID
      responses:
        "200":
          description: Successfully reset drift for worker account
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Account"

  /worker/memory:
    get:
      summary: Get overview of worker's memory usage.
      description: Returns the memory usage of the worker for both uploads and downloads.
      responses:
        "200":
          description: Successfully retrieved memory usage
          content:
            application/json:
              schema:
                type: object
                properties:
                  download:
                    allOf:
                      - $ref: "#/components/schemas/MemoryStatus"
                      - description: The memory status for for downloads
                  upload:
                    allOf:
                      - $ref: "#/components/schemas/MemoryStatus"
                      - description: The memory status for for uploads

  /worker/multipart/{key}:
    put:
      summary: Upload a part of an ongoing multipart upload
      description: Upload a single part of an ongoing multipart upload. Parts can be uploaded in parallel and then combined afterwards.
      parameters:
        - name: key
          description: The key of the file to upload
          in: path
          required: true
          schema:
            type: string
            example: "myDir/myFile"
            minLength: 1
        - name: bucket
          description: The bucket the multipart upload belongs to
          example: "myBucket"
          in: query
          required: true
          schema:
            $ref: "#/components/schemas/Bucket"
        - name: uploadid
          description: The ID of the ongoing multipart upload
          in: query
          required: true
          schema:
            allOf:
              - $ref: "#/components/schemas/MultipartUploadID"
              - example: 7aaac83c6d553865755286c326e852a68300bebf7feea1b435d61bd3610bf82b
        - name: partnumber
          description: The part number of the part being uploaded
          example: 0
          in: query
          required: true
          schema:
            type: integer
            format: uint32
        - name: minshards
          description: Used to override the minimum number of shards the part should be split into.
          example: 10
          in: query
          required: false
          schema:
            type: integer
            format: uint32
        - name: totalshards
          description: Used to override the total number of shards the part should be split into.
          example: 30
          in: query
          required: false
          schema:
            type: integer
            format: uint32
        - name: encryptionoffset
          description: The offset of the part within the final object. This is required unless the upload was explicitly created to not be encrypted before erasure coding.
          example: 0
          in: query
          required: false
          schema:
            type: integer
            format: uint64
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        "200":
          description: Successfully uploaded part
          headers:
            ETag:
              description: The ETag of the uploaded part
              schema:
                $ref: "#/components/schemas/ETag"
        "400":
          description: Invalid combination of request parameters
          content:
            text/plain:
              schema:
                type: string
        "404":
          description: Bucket or upload weren't found
          content:
            text/plain:
              schema:
                type: string
        "503":
          description: Consensus isn't synced
          content:
            text/plain:
              schema:
                type: string
  /worker/object/{key}:
    get:
      summary: Download an object
      description: Downloads an object from the Sia network.
      parameters:
        - name: key
          description: The key of the file to download
          in: path
          required: true
          schema:
            type: string
            example: "myDir/myFile"
            minLength: 1
        - name: bucket
          description: The bucket the object belongs to
          example: "myBucket"
          in: query
          required: true
          schema:
            $ref: "#/components/schemas/Bucket"
        - name: Range
          in: header
          description: The range of bytes to download. If not provided, the entire object will be downloaded.
          schema:
            type: string
            example: "bytes=0-100"
      responses:
        "200":
          description: Successfully downloaded object
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
          headers:
            "Accept-Ranges":
              description: The range units the server supports
              schema:
                type: string
            "Content-Range":
              description: The range of bytes that were downloaded
              schema:
                type: string
            "Content-Type":
              description: The content type of the object
              schema:
                type: string
            "ETag":
              description: The ETag of the downloaded object
              schema:
                $ref: "#/components/schemas/ETag"
        "400":
          description: Invalid range or missing parameters
          content:
            text/plain:
              schema:
                type: string
                example: invalid range
        "404":
          description: Object not found
          content:
            text/plain:
              schema:
                type: string
                example: object not found
        "416":
          description: No overlap between 'Range' and object's content
          content:
            text/plain:
              schema:
                type: string
                example: "invalid range: failed to overlap"
        "500":
          description: Internal server error
          content:
            text/plain:
              schema:
                type: string
                example: "failed to fetch object metadata"

components:
  schemas:
    #############################
    #
    # Core types
    #
    #############################
    Account:
      type: object
      properties:
        id:
          allOf:
            - $ref: "#/components/schemas/PublicKey"
            - description: The account's ID
        cleanShutdown:
          type: boolean
          description: Whether the account has been cleanly shutdown. If not, the account will require a sync with the host.
        hostKey:
          allOf:
            - $ref: "#/components/schemas/PublicKey"
            - description: The host's public key
        balance:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: The account's balance as expected by the worker
        drift:
          allOf:
            - $ref: "#/components/schemas/SignedCurrency"
            - description: The accumulated drift between the worker's expected balance and the host's actual balance. Used to track if a host is trying to cheat the renter over time.
        owner:
          type: string
          description: The owner of the account that manages it. This is the id of the worker that maintains the account.
          minLength: 1
        requiresSync:
          type: boolean
          description: Whether the account requires a sync with the host. This is usually the case when the host reports insufficient balance for an account that the worker still believes to be funded.

    Currency:
      type: string
      pattern: "^\\d+$"
      maxLength: 39 # fits 2^128 - 1
      description: An unsigned amount of Hastings, the smallest unit of currency in Sia. 1 Siacoin (SC) equals 10^24 Hastings (H).

    PublicKey:
      type: string
      pattern: "^ed25519:[0-9a-fA-F]{64}$"
      description: A ed25519 public key

    SignedCurrency:
      type: string
      pattern: "^-?\\d+$"
      maxLength: 39 # fits 2^128 - 1
      description: A signed amount of Hastings, the smallest unit of currency in Sia. 1 Siacoin (SC) equals 10^24 Hastings (H).

    #############################
    #
    # Helper types
    #
    #############################
    AutopilotConfig:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether the autopilot is enabled
        contracts:
          $ref: "#/components/schemas/ContractsConfig"
        hosts:
          $ref: "#/components/schemas/HostsConfig"

    Bucket:
      type: string
      pattern: (?!(^xn--|.+-s3alias$))^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$
      description: A bucket logically groups together objects.

    BuildState:
      type: object
      properties:
        buildTime:
          type: string
          format: date-time
          description: The build time of the build
        commit:
          type: string
          description: The commit hash of the build
        version:
          type: string
          description: The version of the build
        os:
          type: string
          description: The operating system of the build

    ConfigRecommendation:
      type: object
      properties:
        gougingSettings:
          $ref: "#/components/schemas/GougingSettings"

    ContractsConfig:
      type: object
      properties:
        amount:
          type: integer
          format: uint64
          description: The minimum number of contracts to form
          default: 0
        period:
          type: integer
          format: uint64
          description: The length of a contract's period in blocks (1 block being 10 minutes on average)
          default: 0
        renewWindow:
          type: integer
          format: uint64
          description: The number of blocks before the end of a contract that a contract should be renewed
          default: 0
        download:
          type: integer
          format: uint64
          description: Expected download bandwidth used per period in bytes
          default: 0
        upload:
          type: integer
          format: uint64
          description: Expected upload bandwidth used per period in bytes
          default: 0
        storage:
          type: integer
          format: uint64
          description: Expected amount of data stored in bytes
          default: 0
        prune:
          type: boolean
          description: Whether to automatically prune deleted data from contracts
          default: false

    ETag:
      type: string
      pattern: '^(W/)?".*?"$'
      description: An ETag representing a resource

    GougingSettings:
      type: object
      properties:
        maxRPCPrice:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: The maximum base price a host can charge per RPC
        maxContractPrice:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: The maximum price a host can charge for a contract formation
        maxDownloadPrice:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: The maximum price a host can charge for downloading in hastings / byte
        maxUploadPrice:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: The maximum price a host can charge for uploading in hastings / byte
        maxStoragePrice:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: The maximum price a host can charge for storage in hastings / byte / block
        hostBlockHeightLeeway:
          type: integer
          format: uint32
          description: The number of blocks a host's chain's height can diverge from our own before we stop using it
        minPriceTableValidity:
          type: integer
          format: uint64
          description: The time a host's price table should be valid after acquiring it in milliseconds
        minAccountExpiry:
          type: integer
          format: uint64
          description: The minimum amount of time an account on a host can be idle for before expiring
        minMaxEphemeralAccountBalance:
          allOf:
            - $ref: "#/components/schemas/Currency"
            - description: The minimum max balance a host should allow us to fund an account with

    HostsConfig:
      type: object
      properties:
        maxConsecutiveScanFailures:
          type: integer
          format: uint64
          description: The maximum number of consecutive scan failures before a host is removed from the database
          default: 0
        maxDowntimeHours:
          type: integer
          format: uint64
          description: The maximum number of hours a host can be offline before it is removed from the database
          default: 0
        minProtocolVersion:
          type: string
          description: The minimum supported protocol version of a host to be considered good

    MemoryStatus:
      type: object
      properties:
        available:
          type: integer
          format: uint64
          description: The amount of remaining memory currently available in bytes
        total:
          type: integer
          format: uint64
          description: The total amount of memory available in bytes
          minimum: 1

    RedundancySettings:
      type: object
      properties:
        minShards:
          type: integer
          minimum: 1
          format: int32
          description: The number of data shards a piece of an object gets erasure-coded into
        totalShards:
          type: integer
          minimum: 2
          format: int32
          description: The number of total data shards a piece of an object gets erasure-coded into

    MultipartUploadID:
      type: string
      pattern: ^[0-9a-fA-F]{64}$
      description: A unique identifier for a multipart upload