leasehold-http-api/schema/swagger.yml

HTTP API module for Leasehold sidechain

####################################################################################
# Copyright © 2019 Lisk Foundation
#
# See the LICENSE file at the top-level directory of this distribution
# for licensing information.
#
# Unless otherwise agreed in a custom licensing agreement with the Lisk Foundation,
# no part of this software, including this file, may be copied, modified,
# propagated, or distributed except according to the terms contained in the
# LICENSE file.
#
# Removal or modification of this copyright notice is prohibited.
####################################################################################
swagger: '2.0'

info:
  title: Lisk API Documentation
  description: |
    # Welcome!

    ## Access Restrictions
    The API endpoints are by default restricted to a whitelist of IPs that can be found in `config.json` in the section [`api.access.whitelist`](https://github.com/LiskHQ/lisk/blob/1.0.0/config.json#L35).
    If you want your API to be accessable by the public, you can do this by changing `api.access.public` to `true`.
    This will allow anyone to make requests to your Lisk Core node.
    However some endpoints stay private, that means only a list of whitelisted IPs can successfully make API calls to that particular endpoint;
    This includes all forging related API calls.
    By default, only the nodes' local IP is included in the whitelist, you can change the setting in `config.json` in the section [`forging.access.whitelist`](https://github.com/LiskHQ/lisk/blob/1.0.0/config.json#L114).
    For more details, see the descriptions at the respective endpoint.

    ## Requests
    Chained filter parameters are logically connected with `AND`.
    `HTTP` is the supported URL schema by default.
    To enable `HTTPS`, please adjust the the [`ssl`](https://github.com/LiskHQ/lisk/blob/1.0.0/config.json#L124) section in `config.json`.

    ## Responses
    The general response format is JSON (`application/json`).
    The responses for each API request have a common basic structure:
    ```javascript
    {
    	"data": {}, //Contains the requested data
    	"meta": {}, //Contains additional metadata, e.g. the values of `limit` and `offset`
    	"links": {} //Will contain links to connected API calls from here, e.g. pagination links
    }
    ```

    ## Date Formats
    Most of the timestamp parameters are in the Lisk Timestamp format, which is similar to the Unix Timestamp format.
    The **Lisk Timestamp** is the number of seconds that have elapsed since the Lisk epoch time (2016-05-24T17:00:00.000Z), not counting leap seconds.
    The **Lisk Epoch Time** is returned in the [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) format, combined date and time: `YYYY-MM-DDThh:mm:ssZ`.
    For details, see the descriptions and examples at the respective endpoint.

    ## Pagination
    One can paginate nicely through the results by providing `limit` and `offset` parameters to the requests.
    `limit` and `offset` can be found in the `meta`-object of the response of an API request.
    If no limit and offset are provided, they are set to 10 and 0 by default, what will display the first 10 results.

    ## List of Endpoints
    All possible API endpoints for Lisk Core are listed below.
    Click on an endpoint to show descriptions, details and examples.
  version: '1.0.32'
  contact:
    email: admin@lisk.io
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0

# All paths relative to specified basePath
basePath: /api

# Tags for organizing operations
tags:
  - name: Accounts
    description: Account related API calls
  - name: Blocks
    description: Block related API calls
  - name: Dapps
    description: Dapps related API calls
  - name: Delegates
    description: Delegates related API calls
  - name: Node
    description: Node related API calls
  - name: Peers
    description: Peers related API Calls
  - name: Signatures
    description: Signatures related API calls
  - name: Transactions
    description: Transactions related API calls
  - name: Voters
    description: Votes related API calls
  - name: Votes
    description: Votes related API calls

schemes:
  - http
  - https

paths:
  /accounts:
    x-swagger-router-controller: accounts
    get:
      tags:
        - Accounts
      summary: Requests account data
      operationId: getAccounts
      description: Search for matching accounts in the system.
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/address'
        - $ref: '#/parameters/publicKey'
        - $ref: '#/parameters/secondPublicKey'
        - $ref: '#/parameters/username'
        - $ref: '#/parameters/limit'
        - $ref: '#/parameters/offset'
        - name: sort
          in: query
          description: Fields to sort results by
          required: false
          type: string
          enum:
            - balance:asc
            - balance:desc
          default: balance:asc
      responses:
        200:
          description: List of accounts
          schema:
            $ref: '#/definitions/AccountsResponse'
        400:
          description: Malformed query or parameters
          schema:
            $ref: '#/definitions/ParamErrorResponse'
        429:
          description: Too many requests, exceeded rate limit
          schema:
            $ref: '#/definitions/RequestLimitError'
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/UnexpectedError'

  /accounts/{address}/multisignature_groups:
    x-swagger-router-controller: accounts
    get:
      tags:
        - Accounts
      summary: Requests multisignature groups data
      operationId: getMultisignatureGroups
      description: Searches for the specified account in the system and responds with a list of the multisignature groups that this account is member of.
      produces:
        - application/json
      parameters:
        - name: address
          in: path
          description: Lisk address of an account
          type: string
          format: address
          required: true
          minLength: 2
          maxLength: 22
      responses:
        200:
          description: List of multisignature accounts
          schema:
            $ref: '#/definitions/MultisignatureGroupsResponse'
        400:
          description: Malformed query or parameters
          schema:
            $ref: '#/definitions/ParamErrorResponse'
        404:
          description: Multisignature account not found
          schema:
            $ref: '#/definitions/NotFoundError'
        429:
          description: Too many requests, exceeded rate limit
          schema:
            $ref: '#/definitions/RequestLimitError'
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/UnexpectedError'

  /accounts/{address}/multisignature_memberships:
    x-swagger-router-controller: accounts
    get:
      tags:
        - Accounts
      summary: Requests multisignature membership data
      operationId: getMultisignatureMemberships
      description: Searches for the specified multisignature group and responds with a list of all members of this particular multisignature group.
      produces:
        - application/json
      parameters:
        - name: address
          in: path
          description: Lisk address of a multisignature account
          type: string
          format: address
          required: true
          minLength: 2
          maxLength: 22
      responses:
        200:
          description: List of multisignature accounts
          schema:
            $ref: '#/definitions/MultisignatureGroupsResponse'
        400:
          description: Malformed query or parameters
          schema:
            $ref: '#/definitions/ParamErrorResponse'
        429:
          description: Too many requests, exceeded rate limit
          schema:
            $ref: '#/definitions/RequestLimitError'
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/UnexpectedError'

  /dapps:
    x-swagger-router-controller: dapps
    get:
      tags:
        - Dapps
      summary: Requests dapps data
      operationId: getDapps
      description: Search for a specified dapp in the system.
      produces:
        - application/json
      parameters:
        - name: transactionId
          in: query
          description: Dapp registration transaction ID
          required: false
          type: string
          format: id
          minLength: 1
          maxLength: 20
        - name: name
          in: query
          description: Name to query - Fuzzy search
          type: string
          minLength: 1
          maxLength: 32
        - name: sort
          in: query
          description: Fields to sort results by
          required: false
          type: string
          enum:
            - name:asc
            - name:desc
          default: name:asc
        - $ref: '#/parameters/limit'
        - $ref: '#/parameters/offset'
      responses:
        200:
          description: Search results matching criteria
          schema:
            $ref: '#/definitions/DappsResponse'
        400:
          description: Malformed query or parameters
          schema:
            $ref: '#/definitions/ParamErrorResponse'
        429:
          description: Too many requests, exceeded rate limit
          schema:
            $ref: '#/definitions/RequestLimitError'
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/UnexpectedError'

  /peers:
    x-swagger-router-controller: peers
    get:
      tags:
        - Peers
      summary: Requests peers data
      operationId: getPeers
      description: Search for specified peers.
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/ip'
        - $ref: '#/parameters/httpPort'
        - $ref: '#/parameters/wsPort'
        - $ref: '#/parameters/os'
        - $ref: '#/parameters/version'
        - $ref: '#/parameters/protocolVersion'
        - $ref: '#/parameters/state'
        - $ref: '#/parameters/height'
        - $ref: '#/parameters/broadhash'
        - $ref: '#/parameters/limit'
        - $ref: '#/parameters/offset'
        - in: query
          name: sort
          description: Fields to sort results by
          required: false
          type: string
          enum:
            - height:asc
            - height:desc
            - version:asc
            - version:desc
          default: height:desc
      responses:
        200:
          description: List of peers
          schema:
            $ref: '#/definitions/PeersResponse'
        400:
          description: Malformed query or parameters
          schema:
            $ref: '#/definitions/ParamErrorResponse'
        429:
          description: Too many requests, exceeded rate limit
          schema:
            $ref: '#/definitions/RequestLimitError'
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/UnexpectedError'

  /node/constants:
    x-swagger-router-controller: node
    get:
      tags:
        - Node
      summary: Requests constants data
      operationId: getConstants
      description: Returns all current constants data on the system, e.g. Lisk epoch time and version.
      produces:
        - application/json
      responses:
        200:
          description: Node constants response
          schema:
            $ref: '#/definitions/NodeConstantsResponse'
        429:
          description: Too many requests, exceeded rate limit
          schema:
            $ref: '#/definitions/RequestLimitError'
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/UnexpectedError'

  /node/status:
    x-swagger-router-controller: node
    get:
      tags:
        - Node
      summary: Requests status data
      operationId: getStatus
      description: Returns all current status data of the node, e.g. height and broadhash.
      produces:
        - application/json
      responses:
        200:
          description: Node status response
          schema:
            $ref: '#/definitions/NodeStatusResponse'
        429:
          description: Too many requests, exceeded rate limit
          schema:
            $ref: '#/definitions/RequestLimitError'
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/UnexpectedError'

  /node/status/forging:
    x-swagger-router-controller: node
    get:
      tags:
        - Node
      summary: Requests forging status of a delegate
      operationId: getForgingStatus
      description: |
        *Attention! This is a **private endpoint only authorized to whitelisted IPs.**
        To edit the whitelist, please edit the `forging.access.whitelist` section in `config.json`*<br>
        Responds with the forging status of a delegate on a node.
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/publicKey'
      responses:
        200:
          description: Search results matching criteria
          schema:
            $ref: '#/definitions/ForgingStatusResponse'
        400:
          description: Malformed query or parameters
          schema:
            $ref: '#/definitions/ParamErrorResponse'
        403:
          description: Access denied
          schema:
            $ref: '#/definitions/AccessDeniedError'
        429:
          description: Too many requests, exceeded rate limit
          schema:
            $ref: '#/definitions/RequestLimitError'
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/UnexpectedError'
    put:
      tags:
        - Node
      summary: Toggles the forging status of a delegate
      operationId: updateForgingStatus
      description: |
        *Attention! This is a **private endpoint only authorized to whitelisted IPs.**
        To edit the whitelist, please edit the `forging.access.whitelist` section in `config.json`*<br>
        Upon passing the correct password and publicKey, forging will be enabled or disabled for the delegate of this particular node.
        The password can be generated locally by encrypting your passphrase, either by using Lisk Commander or with Lisk Elements.
      produces:
        - application/json
      consumes:
        - application/json
      parameters:
        - in: body
          name: data
          description: Password for decrypting passphrase of delegate with corresponding public key
          required: true
          schema:
            type: object
            required:
              - password
              - publicKey
              - forging
            properties:
              forging:
                type: boolean
                example: true
                description: Forging status of the delegate
              password:
                type: string
                example: 'happy tree friends'
                minLength: 5
                description: Password for decrypting passphrase of delegate.
              publicKey:
                type: string
                example: '968ba2fa993ea9dc27ed740da0daf49eddd740dbd7cb1cb4fc5db3a20baf341b'
                format: publicKey
                description: Public key of the delegate.
      responses:
        200:
          description: Delegate forging toggled on or off
          schema:
            $ref: '#/definitions/ForgingStatusResponse'
        400:
          description: Malformed query or parameters
          schema:
            $ref: '#/definitions/ParamErrorResponse'
        403:
          description: Access denied
          schema:
            $ref: '#/definitions/AccessDeniedError'
        404:
          description: Provided public key not found
          schema:
            $ref: '#/definitions/NotFoundError'
        429:
          description: Too many requests, exceeded rate limit
          schema:
            $ref: '#/definitions/RequestLimitError'
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/UnexpectedError'

  /node/transactions/{state}:
    x-swagger-router-controller: node
    get:
      tags:
        - Node
      summary: Requests unprocessed transactions data
      operationId: getPooledTransactions
      description: |
        By specifying the state of the transactions, you get a list of unprocessed transactions matching this state.
        Search for specific transactions by providing the appropriate parameters.
        If you post a batch of transactions, they will appear in the unprocessed list after a small delay, depending on server load.
      produces:
        - application/json
      parameters:
        - in: path
          name: state
          description: State of transactions to query
          required: true
          type: string
          enum:
            - pending
            - ready
            - received
            - validated
            - verified
          default: verified
        - $ref: '#/parameters/transactionId'
        - $ref: '#/parameters/recipientId'
        - $ref: '#/parameters/recipientPublicKey'
        - $ref: '#/parameters/senderId'
        - $ref: '#/parameters/senderPublicKey'
        - $ref: '#/parameters/transactionType'
        - $ref: '#/parameters/limit'
        - $ref: '#/parameters/offset'
        - in: query
          name: sort
          description: Fields to sort results by
          required: false
          type: string
          enum:
            - amount:asc
            - amount:desc
            - fee:asc
            - fee:desc
            - type:asc
            - type:desc
            - timestamp:asc
            - timestamp:desc
          default: amount:desc
      responses:
        200:
          description: Transactions list
          schema:
            $ref: '#/definitions/TransactionsResponse'
        400:
          description: Malformed query or parameters
          schema:
            $ref: '#/definitions/ParamErrorResponse'
        429:
          description: Too many requests, exceeded rate limit
          schema:
            $ref: '#/definitions/RequestLimitError'
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/UnexpectedError'

  /delegates:
    x-swagger-router-controller: delegates
    get:
      tags:
        - Delegates
      summary: Requests delegates data
      operationId: getDelegates
      x-lisk-cache-enabled: true
      description: Search for a specified delegate in the system.
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/address'
        - $ref: '#/parameters/publicKey'
        - $ref: '#/parameters/secondPublicKey'
        - $ref: '#/parameters/username'
        - $ref: '#/parameters/offset'
        - name: limit
          in: query
          description: Limit applied to results
          type: integer
          format: int32
          minimum: 1
          maximum: 101
          default: 10
        - name: search
          in: query
          description: Fuzzy delegate username to query
          type: string
          minLength: 1
          maxLength: 20
        - in: query
          name: sort
          description: Fields to sort results by
          required: false
          type: string
          enum:
            - username:asc
            - username:desc
            - rank:asc
            - rank:desc
            - productivity:asc
            - productivity:desc
            - missedBlocks:asc
            - missedBlocks:desc
            - producedBlocks:asc
            - producedBlocks:desc
          default: rank:asc
      responses:
        200:
          description: Search results matching criteria
          schema:
            $ref: '#/definitions/DelegatesResponse'
        400:
          description: Malformed query or parameters
          schema:
            $ref: '#/definitions/ParamErrorResponse'
        429:
          description: Too many requests, exceeded rate limit
          schema:
            $ref: '#/definitions/RequestLimitError'
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/UnexpectedError'

  /delegates/forgers:
    x-swagger-router-controller: delegates
    get:
      tags:
        - Delegates
      summary: Requests next forgers data
      operationId: getForgers
      description: |
        Returns a list of the next forgers in this delegate round.
      produces:
        - application/json
      parameters:
        - name: limit
          in: query
          description: Limit applied to results
          type: integer
          format: int32
          minimum: 1
          maximum: 101
          default: 10
        - name: offset
          in: query
          description: Offset value for results
          type: integer
          format: int32
          minimum: 0
          maximum: 100
          default: 0
      responses:
        200:
          description: Search results matching criteria
          schema:
            $ref: '#/definitions/ForgersResponse'
        400:
          description: Malformed query or parameters
          schema:
            $ref: '#/definitions/ParamErrorResponse'
        429:
          description: Too many requests, exceeded rate limit
          schema:
            $ref: '#/definitions/RequestLimitError'
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/UnexpectedError'

  /delegates/{address}/forging_statistics:
    x-swagger-router-controller: delegates
    get:
      tags:
        - Delegates
      summary: Requests forging stats by delegate
      operationId: getForgingStatistics
      x-lisk-cache-enabled: true
      description: |
        By passing an existing delegate address and the desired unix timestamps, you can get its forging statistics within the specified timespan.
        If no timestamps are provided, it will use the timestamps from Lisk epoch to current date.
      produces:
        - application/json
      parameters:
        - in: path
          name: address
          description: Lisk address of a delegate
          required: true
          type: string
          format: address
        - $ref: '#/parameters/fromTimestamp'
        - $ref: '#/parameters/toTimestamp'
      responses:
        200:
          description: Results matching specified delegate address
          schema:
            $ref: '#/definitions/ForgingStatsResponse'
        400:
          description: Malformed query or parameters
          schema:
            $ref: '#/definitions/ParamErrorResponse'
        429:
          description: Too many requests, exceeded rate limit
          schema:
            $ref: '#/definitions/RequestLimitError'
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/UnexpectedError'

  /blocks:
    x-swagger-router-controller: blocks
    get:
      tags:
        - Blocks
      summary: Requests blocks data
      operationId: getBlocks
      x-lisk-cache-enabled: true
      description: |
        Search for a specified block in the system.
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/blockId'
        - $ref: '#/parameters/height'
        - $ref: '#/parameters/fromTimestamp'
        - $ref: '#/parameters/toTimestamp'
        - $ref: '#/parameters/limit'
        - $ref: '#/parameters/offset'
        - in: query
          name: generatorPublicKey
          description: Public key of the forger of the block
          type: string
          format: publicKey
        - in: query
          name: sort
          description: Fields to sort results by
          required: false
          type: string
          enum:
            - height:asc
            - height:desc
            - totalAmount:asc
            - totalAmount:desc
            - totalFee:asc
            - totalFee:desc
            - timestamp:asc
            - timestamp:desc
          default: height:desc
      responses:
        200:
          description: Search results matching criteria
          schema:
            $ref: '#/definitions/BlocksResponse'
        400:
          description: Malformed query or parameters
          schema:
            $ref: '#/definitions/ParamErrorResponse'
        429:
          description: Too many requests, exceeded rate limit
          schema:
            $ref: '#/definitions/RequestLimitError'
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/UnexpectedError'

  /voters:
    x-swagger-router-controller: voters
    get:
      tags:
        - Voters
      summary: Requests voters data for a delegate
      operationId: getVoters
      description: |
        *Attention: At least **one of the filter parameters must be provided.***
        Returns all votes received by a delegate.
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/username'
        - $ref: '#/parameters/address'
        - $ref: '#/parameters/publicKey'
        - $ref: '#/parameters/secondPublicKey'
        - $ref: '#/parameters/offset'
        - $ref: '#/parameters/limit'
        - in: query
          name: sort
          description: Fields to sort results by
          required: false
          type: string
          enum:
            - publicKey:asc
            - publicKey:desc
            - balance:asc
            - balance:desc
            - username:asc
            - username:desc
          default: publicKey:asc
      responses:
        200:
          description: Voters list
          schema:
            $ref: '#/definitions/VotersResponse'
        400:
          description: Malformed query or parameters
          schema:
            $ref: '#/definitions/ParamErrorResponse'
        404:
          description: Requested resource not found based on provided filters
          schema:
            $ref: '#/definitions/NotFoundError'
        429:
          description: Too many requests, exceeded rate limit
          schema:
            $ref: '#/definitions/RequestLimitError'
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/UnexpectedError'

  /votes:
    x-swagger-router-controller: voters
    get:
      tags:
        - Votes
      summary: Requests votes data for an account
      operationId: getVotes
      description: |
        *Attention: At least **one of the filter parameters must be provided.***
        Returns all votes placed by an account.
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/username'
        - $ref: '#/parameters/address'
        - $ref: '#/parameters/publicKey'
        - $ref: '#/parameters/secondPublicKey'
        - $ref: '#/parameters/offset'
        - name: limit
          in: query
          description: Limit applied to results
          type: integer
          format: int32
          minimum: 1
          maximum: 101
          default: 10
        - in: query
          name: sort
          description: Fields to sort results by
          required: false
          type: string
          enum:
            - username:asc
            - username:desc
            - balance:asc
            - balance:desc
          default: username:asc
      responses:
        200:
          description: Votes list
          schema:
            $ref: '#/definitions/VotesResponse'
        400:
          description: Malformed query or parameters
          schema:
            $ref: '#/definitions/ParamErrorResponse'
        404:
          description: Requested resource not found based on provided filters
          schema:
            $ref: '#/definitions/NotFoundError'
        429:
          description: Too many requests, exceeded rate limit
          schema:
            $ref: '#/definitions/RequestLimitError'
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/UnexpectedError'

  /signatures:
    x-swagger-router-controller: signatures
    post:
      tags:
        - Signatures
      summary: Submits a signature object to sign multisignature transactions
      operationId: postSignature
      description: |
        Submits signature to sign a multisignature transaction.
        Signature objects can be generated locally either by using Lisk Commander or with Lisk Elements.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: signature
          description: Signature object to submit to the network
          required: true
          schema:
            $ref: '#/definitions/Signature'
      responses:
        200:
          description: Signature is accepted by the node for processing
          schema:
            $ref: '#/definitions/SignatureResponse'
        400:
          description: Malformed query or parameters
          schema:
            $ref: '#/definitions/ParamErrorResponse'
        409:
          description: Some error related to processing of request
          schema:
            $ref: '#/definitions/ProcessingError'
        429:
          description: Too many requests, exceeded rate limit
          schema:
            $ref: '#/definitions/RequestLimitError'
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/UnexpectedError'

  /transactions:
    x-swagger-router-controller: transactions
    get:
      tags:
        - Transactions
      summary: Requests transactions data
      operationId: getTransactions
      x-lisk-cache-enabled: true
      description: |
        Search for a specified transaction in the system.
      produces:
        - application/json
      parameters:
        - $ref: '#/parameters/transactionId'
        - $ref: '#/parameters/recipientId'
        - $ref: '#/parameters/recipientPublicKey'
        - $ref: '#/parameters/senderId'
        - $ref: '#/parameters/senderPublicKey'
        - $ref: '#/parameters/senderIdOrRecipientId'
        - $ref: '#/parameters/transactionType'
        - $ref: '#/parameters/height'
        - $ref: '#/parameters/minAmount'
        - $ref: '#/parameters/maxAmount'
        - $ref: '#/parameters/fromTimestamp'
        - $ref: '#/parameters/toTimestamp'
        - $ref: '#/parameters/blockId'
        - $ref: '#/parameters/limit'
        - $ref: '#/parameters/offset'
        - in: query
          name: sort
          description: Fields to sort results by
          required: false
          type: string
          enum:
            - amount:asc
            - amount:desc
            - fee:asc
            - fee:desc
            - type:asc
            - type:desc
            - timestamp:asc
            - timestamp:desc
          default: amount:asc
        - name: data
          in: query
          description: Fuzzy additional data field to query
          type: string
          format: additionalData
          minLength: 1
          maxLength: 64 # Its an additional check, actual check is 64 bytes
      responses:
        200:
          description: Transactions list
          schema:
            $ref: '#/definitions/TransactionsResponse'
        400:
          description: Malformed query or parameters
          schema:
            $ref: '#/definitions/ParamErrorResponse'
        429:
          description: Too many requests, exceeded rate limit
          schema:
            $ref: '#/definitions/RequestLimitError'
        500:
          description: Unexpected error
          schema:
            $ref: '#/definitions/UnexpectedError'
    post:
      tags:
        - Transactions
      summary: Submits signed transaction for processing
      operationId: postTransaction
      description: |
        Submits signed transaction object for processing by the transaction pool.
        Transaction objects can be generated locally either by using Lisk Commander or with Lisk Elements.
      consumes:
        - application/json
      produces:
        - application/json
      parameters:
        - in: body
          name: transaction
          description: Transaction object to submit to the network
          required: true
          schema:
            $ref: '#/definitions/TransactionRequest'
      responses:
        200:
          description: Transaction accepted by the node for processing
          schema:
            $ref: '#/definitions/GeneralStatusResponse'
        400:
          description: Malformed query or parameters
          schema:
            $ref: '#/definitions/ParamErrorResponse'
        409:
          description: Some error related to processing of request
          schema:
            $ref: '#/definitions/ProcessingError'
        429:
          description: Too many requests, exceeded rate limit
          schema:
            $ref: '#/definitions/RequestLimitError'

  /spec:
    x-swagger-pipe: swagger_raw_pipe

parameters:
  ip:
    name: ip
    in: query
    description: IP of the node or delegate
    type: string
    format: ip
  httpPort:
    name: httpPort
    in: query
    description: Http port of the node or delegate
    type: integer
    format: int32
    minimum: 1
    maximum: 65535
  wsPort:
    name: wsPort
    in: query
    description: Web socket port for the node or delegate
    type: integer
    format: int32
    minimum: 1
    maximum: 65535
  os:
    name: os
    in: query
    description: OS of the node
    type: string
  version:
    name: version
    in: query
    description: Lisk version of the node
    type: string
    format: version
  protocolVersion:
    name: protocolVersion
    in: query
    description: Protocol version of the node
    type: string
    format: protocolVersion
  state:
    name: state
    in: query
    description: Current state of the network
    type: integer
    format: int32
    minimum: 0
    maximum: 2
  height:
    name: height
    in: query
    description: Current height of the network
    type: integer
    format: int32
    minimum: 1
  broadhash:
    name: broadhash
    in: query
    description: Broadhash of the network
    type: string
    format: hex
  limit:
    in: query
    name: limit
    description: Limit applied to results
    type: integer
    format: int32
    minimum: 1
    maximum: 100
    default: 10
  offset:
    name: offset
    in: query
    description: Offset value for results
    type: integer
    format: int32
    minimum: 0
    default: 0
  address:
    name: address
    in: query
    description: Address of an account
    required: false
    type: string
    format: address
    minLength: 2
    maxLength: 22
  publicKey:
    name: publicKey
    in: query
    description: Public key to query
    type: string
    format: publicKey
  secondPublicKey:
    name: secondPublicKey
    in: query
    description: Second public key to query
    type: string
    format: publicKey
  username:
    name: username
    in: query
    description: Delegate username to query
    type: string
    format: username
    minLength: 1
    maxLength: 20
  blockId:
    name: blockId
    in: query
    description: Block id to query
    type: string
    format: id
    minLength: 1
    maxLength: 20
  transactionId:
    name: id
    in: query
    description: Transaction id to query
    type: string
    format: id
    minLength: 1
    maxLength: 20
  recipientId:
    name: recipientId
    in: query
    description: Recipient lisk address
    type: string
    format: address
    minLength: 1
    maxLength: 22
  recipientPublicKey:
    name: recipientPublicKey
    in: query
    description: Recipient public key
    type: string
    format: publicKey
    minLength: 1
  senderId:
    name: senderId
    in: query
    description: Sender lisk address
    type: string
    format: address
    minLength: 1
    maxLength: 22
  senderPublicKey:
    name: senderPublicKey
    in: query
    description: Sender public key
    type: string
    format: publicKey
    minLength: 1
  senderIdOrRecipientId:
    name: senderIdOrRecipientId
    in: query
    description: Lisk address
    type: string
    format: address
    minLength: 1
    maxLength: 22
  transactionType:
    name: type
    in: query
    description: Transaction type (0-*)
    type: integer
    minimum: 0
  minAmount:
    name: minAmount
    in: query
    description: Minimum transaction amount in Beddows
    type: integer
    minimum: 0
  maxAmount:
    name: maxAmount
    in: query
    description: Maximum transaction amount in Beddows
    type: integer
    minimum: 0
  fromTimestamp:
    name: fromTimestamp
    in: query
    description: Starting unix timestamp
    type: integer
    minimum: 0
  toTimestamp:
    name: toTimestamp
    in: query
    description: Ending unix timestamp
    type: integer
    minimum: 1

definitions:
  Meta:
    type: object
    required:
      - limit
      - offset
    properties:
      limit:
        $ref: '#/definitions/Limit'
      offset:
        $ref: '#/definitions/Offset'

  Limit:
    description: Limit applied to results
    type: integer
    format: int32
    minimum: 1
    maximum: 100
    default: 10

  Offset:
    description: Offset value for results
    type: integer
    format: int32
    minimum: 0
    default: 0

  TransactionRequest:
    type: object
    required:
      - id
      - type
      - amount
      - fee
      - senderPublicKey
      - recipientId
      - timestamp
      - asset
      - signature
    properties:
      id:
        type: string
        format: id
        example: '222675625422353767'
        minLength: 1
        maxLength: 20
        description: |
          Unique identifier of the transaction.
          Derived from the transaction signature.
      amount:
        type: string
        example: '150000000'
        description: |
          Amount of Lisk to be transferred in this transaction.
      fee:
        type: string
        example: '1000000'
        description: |
          Transaction fee associated with this transaction.
      type:
        type: integer
        minimum: 0
        description: |
          Describes the Transaction type.
      timestamp:
        type: integer
        example: 28227090
        description: |
          Time when the transaction was created.
          Unix Timestamp.
      senderId:
        type: string
        format: address
        example: 12668885769632475474L
        description: |
          Lisk Address of the Senders' account.
      senderPublicKey:
        type: string
        format: publicKey
        example: 2ca9a7143fc721fdc540fef893b27e8d648d2288efa61e56264edf01a2c23079
        description: |
          The public key of the Senders' account.
      senderSecondPublicKey:
        type: string
        format: publicKey
        example: 2ca9a7143fc721fdc540fef893b27e8d648d2288efa61e56264edf01a2c23079
        description: |
          The second public key of the Senders' account, if it exists.
      recipientId:
        type: string
        format: address
        example: 12668885769632475474L
        description: |
          Lisk Address of the Recipients' account.
      signature:
        type: string
        format: signature
        example: 2821d93a742c4edf5fd960efad41a4def7bf0fd0f7c09869aed524f6f52bf9c97a617095e2c712bd28b4279078a29509b339ac55187854006591aa759784c205
        description: |
          Derived from a SHA-256 hash of the transaction object,
          that is signed by the private key of the account who created the transaction.
      signSignature:
        type: string
        format: signature
        example: 2821d93a742c4edf5fd960efad41a4def7bf0fd0f7c09869aed524f6f52bf9c97a617095e2c712bd28b4279078a29509b339ac55187854006591aa759784c205
        description: Contains the second signature, if the transaction is sent from an account with second passphrase activated.
      signatures:
        type: array
        description: If the transaction is a multisignature transaction, all signatures of the members of the corresponding multisignature group will be listed here.
        items:
          type: string
          format: signature
          example: 72c9b2aa734ec1b97549718ddf0d4737fd38a7f0fd105ea28486f2d989e9b3e399238d81a93aa45c27309d91ce604a5db9d25c9c90a138821f2011bc6636c60a
      asset:
        type: object
        description: |
          Displays additional transaction data.
          Can include e.g. vote data or delegate username.
  NodeStatusResponse:
    type: object
    required:
      - data
      - links
      - meta
    properties:
      data:
        $ref: '#/definitions/NodeStatus'
      meta:
        type: object
      links:
        type: object

  NodeConstantsResponse:
    type: object
    required:
      - data
      - links
      - meta
    properties:
      data:
        $ref: '#/definitions/NodeConstants'
      meta:
        type: object
      links:
        type: object

  PeersResponse:
    description: Peers response
    type: object
    required:
      - data
      - meta
      - links
    properties:
      data:
        type: array
        items:
          $ref: '#/definitions/Peer'
      meta:
        type: object
        required:
          - offset
          - limit
          - count
        properties:
          offset:
            $ref: '#/definitions/Offset'
          limit:
            $ref: '#/definitions/Limit'
          count:
            description: Number of peers in the response
            type: integer
            example: 100
      links:
        type: object

  AccountsResponse:
    type: object
    required:
      - data
      - meta
      - links
    properties:
      data:
        description: List of accounts
        type: array
        items:
          $ref: '#/definitions/AccountExtended'
      meta:
        $ref: '#/definitions/Meta'
      links:
        type: object

  MultisignatureGroupsResponse:
    type: object
    required:
      - data
      - meta
      - links
    properties:
      data:
        description: List of multisignature groups
        type: array
        items:
          $ref: '#/definitions/MultisignatureGroup'
      meta:
        type: object
      links:
        type: object

  DappsResponse:
    description: Dapps endpoint response
    type: object
    required:
      - data
      - meta
      - links
    properties:
      data:
        type: array
        items:
          $ref: '#/definitions/Dapp'
      meta:
        $ref: '#/definitions/Meta'
      links:
        type: object

  DelegatesResponse:
    type: object
    required:
      - data
      - meta
      - links
    properties:
      data:
        description: List of delegates
        type: array
        items:
          $ref: '#/definitions/DelegateWithAccount'
      meta:
        type: object
        required:
          - limit
          - offset
        properties:
          offset:
            $ref: '#/definitions/Offset'
          limit:
            type: integer
            format: int32
            minimum: 1
            maximum: 101
            default: 10
      links:
        type: object

  ForgersResponse:
    type: object
    required:
      - data
      - meta
      - links
    properties:
      data:
        description: List of forgers
        type: array
        items:
          $ref: '#/definitions/Forger'
      meta:
        type: object
        required:
          - offset
          - limit
          - currentSlot
          - lastBlockSlot
          - lastBlock
        properties:
          offset:
            $ref: '#/definitions/Offset'
          limit:
            type: integer
            format: int32
            minimum: 1
            maximum: 101
            default: 10
          currentSlot:
            description: Currently active slot
            type: integer
            example: 10
          lastBlockSlot:
            description: Slot of the last processed block
            type: integer
            example: 10
          lastBlock:
            description: ID of the last processed block
            type: integer
            example: 10
      links:
        type: object

  ForgingStatusResponse:
    type: object
    required:
      - data
      - meta
      - links
    properties:
      data:
        type: array
        items:
          $ref: '#/definitions/ForgingStatus'
      meta:
        type: object
      links:
        type: object

  ForgingStatsResponse:
    type: object
    required:
      - data
      - meta
      - links
    properties:
      data:
        $ref: '#/definitions/ForgingStats'
      meta:
        type: object
        required:
          - fromTimestamp
          - toTimestamp
        properties:
          fromTimestamp:
            description: Starting unix timestamp
            type: integer
            example: 0
          toTimestamp:
            description: Ending unix timestamp
            type: integer
            example: 1525861914
      links:
        type: object

  BlocksResponse:
    description: Blocks response
    type: object
    required:
      - data
      - meta
      - links
    properties:
      data:
        type: array
        items:
          $ref: '#/definitions/Block'
      meta:
        $ref: '#/definitions/Meta'
      links:
        type: object

  SignatureResponse:
    description: Signature response
    type: object
    required:
      - data
      - meta
      - links
    properties:
      data:
        type: object
        required:
          - message
        properties:
          message:
            type: string
            minLength: 1
      meta:
        type: object
        required:
          - status
        properties:
          status:
            description: Acceptance status for the signature
            type: boolean
            example: true
      links:
        type: object

  TransactionsResponse:
    description: Transactions response
    type: object
    required:
      - data
      - meta
      - links
    properties:
      data:
        type: array
        items:
          $ref: '#/definitions/Transaction'
      meta:
        type: object
        required:
          - offset
          - limit
          - count
        properties:
          offset:
            $ref: '#/definitions/Offset'
          limit:
            $ref: '#/definitions/Limit'
          count:
            description: Number of transactions in the response
            type: integer
            example: 100
      links:
        type: object

  GeneralStatusResponse:
    type: object
    required:
      - data
      - links
      - meta
    properties:
      data:
        type: object
        required:
          - message
        properties:
          message:
            type: string
            minLength: 1
      meta:
        type: object
        required:
          - status
        properties:
          status:
            description: Acceptance status for transactions
            type: boolean
            example: true
      links:
        type: object

  Transaction:
    type: object
    required:
      - id
      - type
      - amount
      - fee
      - senderPublicKey
      - recipientId
      - timestamp
      - asset
      - signature
    properties:
      id:
        type: string
        format: id
        example: '222675625422353767'
        minLength: 1
        maxLength: 20
        description: |
          Unique identifier of the transaction.
          Derived from the transaction signature.
      amount:
        type: string
        example: '150000000'
        description: |
          Amount of Lisk to be transferred in this transaction.
      fee:
        type: string
        example: '1000000'
        description: |
          Transaction fee associated with this transaction.
      type:
        type: integer
        minimum: 0
        maximum: 7
        description: |
          Describes the Transaction type.
      height:
        type: integer
        minimum: 1
        description: |
          The height of the network, at the moment where this transaction was included in the blockchain.
      blockId:
        type: string
        format: id
        minLength: 1
        maxLength: 20
        example: '6258354802676165798'
        description: |
          The Id of the block, this transaction is included in.
      timestamp:
        type: integer
        example: 28227090
        description: |
          Time when the transaction was created.
          Unix Timestamp.
      senderId:
        type: string
        format: address
        example: 12668885769632475474L
        description: |
          Lisk Address of the Senders' account.
      senderPublicKey:
        type: string
        format: publicKey
        example: 2ca9a7143fc721fdc540fef893b27e8d648d2288efa61e56264edf01a2c23079
        description: |
          The public key of the Senders' account.
      senderSecondPublicKey:
        type: string
        format: publicKey
        example: 2ca9a7143fc721fdc540fef893b27e8d648d2288efa61e56264edf01a2c23079
        description: |
          The second public key of the Senders' account, if it exists.
      recipientId:
        type: string
        format: address
        example: 12668885769632475474L
        description: |
          Lisk Address of the Recipients' account.
      recipientPublicKey:
        type: string
        format: publicKey
        example: 2ca9a7143fc721fdc540fef893b27e8d648d2288efa61e56264edf01a2c23079
        description: |
          The public key of the Recipients' account.
      signature:
        type: string
        format: signature
        example: 2821d93a742c4edf5fd960efad41a4def7bf0fd0f7c09869aed524f6f52bf9c97a617095e2c712bd28b4279078a29509b339ac55187854006591aa759784c205
        description: |
          D