openapi.yaml

openapi: 3.0.3

info:
  version: 0.0.1
  title: Archivist API
  description: "List of endpoints and interfaces available to Archivist API users"

security:
  - {}

components:
  schemas:
    MultiAddress:
      type: string
      description: Address of node as specified by the multi-address specification https://multiformats.io/multiaddr/
      example: /ip4/127.0.0.1/tcp/8080

    PeerId:
      type: string
      description: Peer Identity reference as specified at https://docs.libp2p.io/concepts/fundamentals/peers/
      example: QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N

    Id:
      type: string
      description: 32bits identifier encoded in hex-decimal string.
      minLength: 66
      maxLength: 66
      example: 0x...

    Cid:
      type: string
      description: Content Identifier as specified at https://github.com/multiformats/cid
      example: QmYyQSo1c1Ym7orWxLYvCrM2EmxFTANf8wXmmE7DWjhx5N

    SlotId:
      type: string
      description: Keccak hash of the abi encoded tuple (RequestId, slot index)
      example: 268a781e0db3f7cf36b18e5f4fdb7f586ec9edd08e5500b17c0e518a769f114a

    LogLevel:
      type: string
      description: "One of the log levels: TRACE, DEBUG, INFO, NOTICE, WARN, ERROR or FATAL"
      example: DEBUG

    EthereumAddress:
      type: string
      description: Address of Ethereum address

    PricePerBytePerSecond:
      type: string
      description: The amount of tokens paid per byte per second per slot to hosts the client is willing to pay

    CollateralPerByte:
      type: string
      description: Number as decimal string that represents how much collateral per byte is asked from hosts that wants to fill a slots

    Duration:
      type: integer
      format: int64
      description: The duration of the request in seconds

    ProofProbability:
      type: string
      description: How often storage proofs are required as decimal string

    Expiry:
      type: integer
      format: int64
      description: A timestamp as seconds since unix epoch at which this request expires if the Request does not find requested amount of nodes to host the data.

    SPR:
      type: string
      description: Signed Peer Record (libp2p)

    SPRRead:
      type: object
      required:
        - spr
      properties:
        spr:
          $ref: "#/components/schemas/SPR"

    PeerIdRead:
      type: object
      properties:
        id:
          $ref: "#/components/schemas/PeerId"

    Content:
      type: object
      required:
       - cid
      description: Parameters specifying the content
      properties:
        cid:
          $ref: "#/components/schemas/Cid"

    Node:
      type: object
      required:
       - nodeId
       - peerId
       - record
       - address
       - seen
      properties:
        nodeId:
          type: string
        peerId:
          type: string
        record:
          type: string
        address:
          type: string
        seen:
          type: boolean

    ArchivistVersion:
      type: object
      properties:
        version:
          type: string
          example: v0.1.7
        revision:
          type: string
          example: 0c647d8
        contracts:
          type: string
          example: 0b537c7

    PeersTable:
      type: object
      required:
       - localNode
       - nodes
      properties:
        localNode:
          $ref: "#/components/schemas/Node"
        nodes:
          type: array
          items:
            $ref: "#/components/schemas/Node"

    DebugInfo:
      type: object
      required:
        - id
        - addrs
        - repo
        - spr
        - announceAddresses
        - ethAddress
        - table
        - archivist
      properties:
        id:
          $ref: "#/components/schemas/PeerId"
        addrs:
          type: array
          items:
            $ref: "#/components/schemas/MultiAddress"
        repo:
          type: string
          description: Path of the data repository where all nodes data are stored
        spr:
          $ref: "#/components/schemas/SPR"
        announceAddresses:
          type: array
          items:
            $ref: "#/components/schemas/MultiAddress"
        ethAddress:
            $ref: "#/components/schemas/EthereumAddress"
            nullable: true
        table:
          $ref: "#/components/schemas/PeersTable"
        archivist:
          $ref: "#/components/schemas/ArchivistVersion"

    DebugPeerRecord:
      type: object
      required:
        - peerId
        - seqNo
        - addresses
      properties:
        peerId:
          type: string
        seqNo:
          type: integer
        addresses:
          type: array
          items:
            type: string

    SalesAvailability:
      type: object
      required:
        - minimumPricePerBytePerSecond
        - maximumCollateralPerByte
        - maximumDuration
      properties:
        maximumDuration:
          $ref: "#/components/schemas/Duration"
        minimumPricePerBytePerSecond:
          type: string
          description: Minimal price per byte per second paid (in amount of tokens) for the hosted request's slot for the request's duration as decimal string
        maximumCollateralPerByte:
          type: string
          description: Maximum collateral per byte that can be used for matching requests
        availableUntil:
          type: integer
          description: Specifies the latest timestamp, after which the availability will no longer host any slots. If set to 0, there will be no restrictions.
          default: 0

    Slot:
      type: object
      required:
        - id
        - request
        - slotIndex
      properties:
        id:
          $ref: "#/components/schemas/SlotId"
        request:
          $ref: "#/components/schemas/StorageRequest"
        slotIndex:
          type: integer
          format: int64
          description: Slot Index number

    SalesSlot:
      type: object
      required:
        - state
        - requestId
        - slotIndex
      properties:
        slotIndex:
          type: integer
          format: int64
          description: Slot Index number
        requestId:
          $ref: "#/components/schemas/Id"
        request:
          $ref: "#/components/schemas/StorageRequest"
        state:
          type: string
          enum:
            - SaleCancelled
            - SaleDownloading
            - SaleErrored
            - SaleFailed
            - SaleFilled
            - SaleFilling
            - SaleFinished
            - SaleIgnored
            - SaleInitialProving
            - SalePayout
            - SalePreparing
            - SaleProving
            - SaleUnknown

    StorageRequestCreation:
      type: object
      required:
        - pricePerBytePerSecond
        - duration
        - proofProbability
        - collateralPerByte
        - expiry
      properties:
        duration:
          $ref: "#/components/schemas/Duration"
        pricePerBytePerSecond:
          $ref: "#/components/schemas/PricePerBytePerSecond"
        proofProbability:
          $ref: "#/components/schemas/ProofProbability"
        nodes:
          description: Minimal number of nodes the content should be stored on
          type: integer
          default: 3
          minimum: 3
        tolerance:
          description: Additional number of nodes on top of the `nodes` property that can be lost before pronouncing the content lost
          type: integer
          default: 1
          minimum: 1
        collateralPerByte:
          $ref: "#/components/schemas/CollateralPerByte"
        expiry:
          type: integer
          format: int64
          description: Number that represents expiry threshold in seconds from when the Request is submitted. When the threshold is reached and the Request does not find requested amount of nodes to host the data, the Request is voided. The number of seconds can not be higher then the Request's duration itself.
    StorageAsk:
      type: object
      required:
        - slots
        - slotSize
        - duration
        - proofProbability
        - pricePerBytePerSecond
        - collateralPerByte
        - maxSlotLoss
      properties:
        slots:
          description: Number of slots (eq. hosts) that the Request want to have the content spread over
          type: integer
          format: int64
        slotSize:
          type: integer
          format: int64
          description: Amount of storage per slot in bytes
        duration:
          $ref: "#/components/schemas/Duration"
        proofProbability:
          $ref: "#/components/schemas/ProofProbability"
        pricePerBytePerSecond:
          $ref: "#/components/schemas/PricePerBytePerSecond"
        collateralPerByte:
          $ref: "#/components/schemas/CollateralPerByte"
        maxSlotLoss:
          type: integer
          format: int64
          description: Max slots that can be lost without data considered to be lost

    StorageRequest:
      type: object
      required:
       - id
       - client
       - ask
       - content
       - expiry
       - nonce
      properties:
        id:
          type: string
          description: Request ID
        client:
          $ref: "#/components/schemas/EthereumAddress"
        ask:
          $ref: "#/components/schemas/StorageAsk"
        content:
          $ref: "#/components/schemas/Content"
        expiry:
          $ref: "#/components/schemas/Expiry"
        nonce:
          type: string
          description: Random data

    Purchase:
      type: object
      required:
        - state
        - requestId
      properties:
        state:
          type: string
          description: Description of the Request's state
          enum:
            - cancelled
            - errored
            - failed
            - finished
            - pending
            - started
            - submitted
            - unknown
        error:
          type: string
          nullable: true
          description: If Request failed, then here is presented the error message
        request:
          $ref: "#/components/schemas/StorageRequest"
        requestId:
          $ref: "#/components/schemas/Id"

    DataList:
      type: object
      required:
        - content
      properties:
        content:
          type: array
          items:
            $ref: "#/components/schemas/DataItem"

    DataItem:
      type: object
      required:
        - cid
        - manifest
      properties:
        cid:
          $ref: "#/components/schemas/Cid"
        manifest:
          $ref: "#/components/schemas/ManifestItem"

    ManifestItem:
      type: object
      required:
        - treeCid
        - datasetSize
        - blockSize
        - protected
      properties:
        treeCid:
          $ref: "#/components/schemas/Cid"
          description: "Unique data identifier"
        datasetSize:
          type: integer
          format: int64
          description: "Length of original content in bytes"
        blockSize:
          type: integer
          description: "Size of blocks"
        protected:
          type: boolean
          description: "Indicates if content is protected by erasure-coding"
        filename:
          type: string
          nullable: true
          description: "The original name of the uploaded content (optional)"
          example: example.png
        mimetype:
          type: string
          nullable: true
          description: "The original mimetype of the uploaded content (optional)"
          example: image/png

    Space:
      type: object
      required:
        - totalBlocks
        - quotaMaxBytes
        - quotaUsedBytes
        - quotaReservedBytes
      properties:
        totalBlocks:
          description: "Number of blocks stored by the node"
          type: integer
          format: int64
        quotaMaxBytes:
          type: integer
          format: int64
          description: "Maximum storage space (in bytes) available for the node in its local repository."
        quotaUsedBytes:
          type: integer
          format: int64
          description: "Amount of storage space (in bytes) currently used for storing files in its local repository."
        quotaReservedBytes:
          type: integer
          format: int64
          description: "Amount of storage reserved (in bytes) in the node's local repository for future use when storage requests will be picked up and hosted by the node using node's availability. This does not include the storage currently in use."

servers:
  - url: "http://localhost:8080/api/archivist/v1"

tags:
  - name: Marketplace
    description: Marketplace information and operations
  - name: Data
    description: Data operations
  - name: Node
    description: Node management
  - name: Debug
    description: Debugging configuration

paths:
  "/connect/{peerId}":
    get:
      summary: "Connect to a peer"
      description: |
        If `addrs` param is supplied, it will be used to dial the peer, otherwise the `peerId` is used
        to invoke peer discovery, if it succeeds the returned addresses will be used to dial.
      tags: [Node]
      operationId: connectPeer
      parameters:
        - in: path
          name: peerId
          required: true
          schema:
            $ref: "#/components/schemas/PeerId"
          description: Peer that should be dialed.
        - in: query
          name: addrs
          schema:
            type: array
            nullable: true
            items:
              $ref: "#/components/schemas/MultiAddress"
          description: |
            If supplied, it will be used to dial the peer.
            The address has to target the listening address of the peer,
            which is specified with the `--listen-addrs` CLI flag.

      responses:
        "200":
          description: Successfully connected to peer
        "400":
          description: Peer either not found or was not possible to dial

  "/data":
    get:
      summary: "Lists manifest CIDs stored locally in node."
      tags: [Data]
      operationId: listData
      responses:
        "200":
          description: Retrieved list of content CIDs
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DataList"

        "400":
          description: Invalid CID is specified
        "404":
          description: Content specified by the CID is not found
        "422":
          description: The content type is not a valid content type or the filename is not valid
        "500":
          description: Well it was bad-bad
    post:
      summary: "Upload a file in a streaming manner. Once finished, the file is stored in the node and can be retrieved by any node in the network using the returned CID."
      tags: [Data]
      operationId: upload
      parameters:
        - name: content-type
          in: header
          required: false
          description: The content type of the file. Must be valid.
          schema:
            type: string
            example: "image/png"
        - name: content-disposition
          in: header
          required: false
          description: The content disposition used to send the filename.
          schema:
            type: string
            example: 'attachment; filename="example.png"'
      requestBody:
        content:
          application/octet-stream:
            schema:
              type: string
              format: binary
      responses:
        "200":
          description: CID of uploaded file
          content:
            text/plain:
              schema:
                type: string
        "422":
          description: The mimetype of the filename is invalid
        "500":
          description: Well it was bad-bad and the upload did not work out

  "/data/{cid}":
    get:
      summary: "Download a file from the local node in a streaming manner. If the file is not available locally, a 404 is returned."
      tags: [Data]
      operationId: downloadLocal
      parameters:
        - in: path
          name: cid
          required: true
          schema:
            $ref: "#/components/schemas/Cid"
          description: File to be downloaded.

      responses:
        "200":
          description: Retrieved content specified by CID
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "400":
          description: Invalid CID is specified
        "404":
          description: Content specified by the CID is unavailable locally
        "500":
          description: Well it was bad-bad

    delete:
      summary: "Deletes either a single block or an entire dataset from the local node."
      tags: [Data]
      operationId: deleteLocal
      parameters:
        - in: path
          name: cid
          required: true
          schema:
            $ref: "#/components/schemas/Cid"
          description: Block or dataset to be deleted.

      responses:
        "204":
          description: Data was successfully deleted.
        "400":
          description: Invalid CID is specified
        "500":
          description: There was an error during deletion

  "/data/{cid}/network":
    post:
      summary: "Download a file from the network to the local node if it's not available locally. Note: Download is performed async. Call can return before download is completed."
      tags: [Data]
      operationId: downloadNetwork
      parameters:
        - in: path
          name: cid
          required: true
          schema:
            $ref: "#/components/schemas/Cid"
          description: "File to be downloaded."
      responses:
        "200":
          description: Manifest information for download that has been started.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DataItem"
        "400":
          description: Invalid CID is specified
        "404":
          description: Failed to download dataset manifest
        "500":
          description: Well it was bad-bad

  "/data/{cid}/network/stream":
    get:
      summary: "Download a file from the network in a streaming manner. If the file is not available locally, it will be retrieved from other nodes in the network if able."
      tags: [Data]
      operationId: downloadNetworkStream
      parameters:
        - in: path
          name: cid
          required: true
          schema:
            $ref: "#/components/schemas/Cid"
          description: "File to be downloaded."
      responses:
        "200":
          description: Retrieved content specified by CID
          content:
            application/octet-stream:
              schema:
                type: string
                format: binary
        "400":
          description: Invalid CID is specified
        "404":
          description: Content specified by the CID is not found
        "500":
          description: Well it was bad-bad

  "/data/{cid}/network/manifest":
    get:
      summary: "Download only the dataset manifest from the network to the local node if it's not available locally."
      tags: [Data]
      operationId: downloadNetworkManifest
      parameters:
        - in: path
          name: cid
          required: true
          schema:
            $ref: "#/components/schemas/Cid"
          description: "File for which the manifest is to be downloaded."
      responses:
        "200":
          description: Manifest information.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DataItem"
        "400":
          description: Invalid CID is specified
        "404":
          description: Failed to download dataset manifest
        "500":
          description: Well it was bad-bad

  "/space":
    get:
      summary: "Gets a summary of the storage space allocation of the node."
      tags: [Data]
      operationId: space
      responses:
        "200":
          description: "Summary of storage allocation"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Space"

        "500":
          description: "It's not working as planned"

  "/sales/slots":
    get:
      summary: "Returns active slots"
      tags: [Marketplace]
      operationId: getActiveSlots
      responses:
        "200":
          description: Retrieved active slots
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/Slot"

        "503":
          description: Persistence is not enabled

  "/sales/slots/{slotId}":
    get:
      summary: "Returns active slot with id {slotId} for the host"
      tags: [Marketplace]
      operationId: getActiveSlotById
      parameters:
        - in: path
          name: slotId
          required: true
          schema:
            $ref: "#/components/schemas/Cid"
          description: File to be downloaded.
      responses:
        "200":
          description: Retrieved active slot
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SalesSlot"

        "400":
          description: Invalid or missing SlotId

        "404":
          description: Host is not in an active sale for the slot

        "503":
          description: Persistence is not enabled

  "/sales/availability":
    get:
      summary: "Returns storage that is for sale"
      tags: [Marketplace]
      operationId: getAvailability
      responses:
        "200":
          description: Retrieved storage availability of the node
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SalesAvailability"
        "500":
          description: Error getting unused availability
        "503":
          description: Persistence is not enabled

    post:
      summary: "Offers storage for sale"
      operationId: offerStorage
      tags: [Marketplace]
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/SalesAvailability"
      responses:
        "201":
          description: Created storage availability
        "400":
          description: Invalid data input
        "422":
          description: Not enough node's storage quota available or the provided parameters did not pass validation
        "500":
          description: Error reserving availability
        "503":
          description: Persistence is not enabled

  "/storage/request/{cid}":
    post:
      summary: "Creates a new Request for storage"
      tags: [Marketplace]
      operationId: createStorageRequest
      parameters:
        - in: path
          name: cid
          required: true
          schema:
            $ref: "#/components/schemas/Cid"
          description: CID of the uploaded data that should be stored
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/StorageRequestCreation"
      responses:
        "200":
          description: Returns the Request ID as decimal string
          content:
            text/plain:
              schema:
                type: string
        "400":
          description: Invalid or missing Request ID
        "422":
          description: The storage request parameters are not valid
        "404":
          description: Request ID not found
        "503":
          description: Persistence is not enabled

  "/storage/purchases":
    get:
      summary: "Returns list of purchase IDs"
      tags: [Marketplace]
      operationId: getPurchases
      responses:
        "200":
          description: Gets all purchase IDs stored in node
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        "503":
          description: Persistence is not enabled

  "/storage/purchases/{id}":
    get:
      summary: "Returns purchase details"
      tags: [Marketplace]
      operationId: getPurchase
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
          description: Hexadecimal ID of a Purchase
      responses:
        "200":
          description: Purchase details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Purchase"
        "400":
          description: Invalid or missing Purchase ID
        "404":
          description: Purchase not found
        "503":
          description: Persistence is not enabled

  "/spr":
    get:
      summary: "Get Node's SPR"
      operationId: getSPR
      tags: [Node]
      responses:
        "200":
          description: Node's SPR
          content:
            text/plain:
              schema:
                $ref: "#/components/schemas/SPR"
            application/json:
              schema:
                $ref: "#/components/schemas/SPRRead"
        "503":
          description: Node SPR not ready, try again later

  "/peerid":
    get:
      summary: "Get Node's PeerID"
      operationId: getPeerId
      tags: [Node]
      responses:
        "200":
          description: Node's Peer ID
          content:
            text/plain:
              schema:
                $ref: "#/components/schemas/PeerId"
            application/json:
              schema:
                $ref: "#/components/schemas/PeerIdRead"

  "/debug/chronicles/loglevel":
    post:
      summary: "Set log level at run time"
      tags: [Debug]
      operationId: setDebugLogLevel

      parameters:
        - in: query
          name: level
          required: true
          schema:
            $ref: "#/components/schemas/LogLevel"

      responses:
        "200":
          description: Successfully log level set
        "400":
          description: Invalid or missing log level
        "500":
          description: Well it was bad-bad

  "/debug/info":
    get:
      summary: "Gets node information"
      operationId: getDebugInfo
      tags: [Debug]
      responses:
        "200":
          description: Node's information
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DebugInfo"

  "/debug/peer/{peerId}":
    get:
      summary: "Only available when built with 'system testing' compile flag. Performs DHT lookup for peerId."
      tags: [Debug]
      operationId: getDebugPeer

      parameters:
        - in: path
          name: peerId
          required: true
          schema:
            type: string

      responses:
        "200":
          description: Successfully looked up peer
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/DebugPeerRecord"
        "500":
          description: Well it was bad-bad

  "/debug/testing/option/{key}/{value}":
    post:
      summary: "Only available when built with 'system testing' compile flag. Sets a system testing option."
      tags: [Debug]
      operationId: setSTO

      parameters:
        - in: path
          name: key
          required: true
          schema:
            type: string
        - in: path
          name: value
          required: true
          schema:
            type: string

      responses:
        "200":
          description: Successfully set system testing option value