openapi-v1.yaml

openapi: 3.0.0
info:
  title: Substrate API Sidecar
  description: Substrate API Sidecar is a REST service that makes it easy to
    interact with blockchain nodes built using Substrate's FRAME framework.
  contact:
    url: https://github.com/paritytech/substrate-api-sidecar
  license:
    name: GPL-3.0-or-later
    url: https://github.com/paritytech/substrate-api-sidecar/blob/master/LICENSE
  version: 12.2.0
tags:
- name: accounts
- name: blocks
- name: node
  description: node connected to sidecar
- name: pallets
  description: pallets employed in the runtime
- name: runtime
- name: transaction
- name: paras
- name: trace
paths:
  /accounts/{accountId}/asset-balances:
    get:
      tags:
      - accounts
      summary: Get an array of asset-balances for an account.
      description: Returns information about an account's asset-balances. This is
        specific to the assets pallet for parachains. If no `assets` query parameter
        is provided, all asset-balances for the given account will be returned.
      operationId: getAssetBalances
      parameters:
      - name: accountId
        in: path
        description: SS58 address of the account.
        required: true
        schema:
          type: string
          format: SS58
      - name: at
        in: query
        description: Block at which to query asset-balance info for the
          specified account.
        required: false
        schema:
          type: string
          description: Block height (as a positive integer) or hash
            (as a hex string).
          format: unsignedInteger or $hex
      - name: assets
        in: query
        description: An array of AssetId's to be queried. If not supplied, defaults to providing
          all asset balances associated with the `accountId` will be returned. The array query param
          format follows Express 4.x API. ex:`?assets[]=1&assets[]=2&assets[]=3`.
        required: false
        schema:
          type: array
          items:
            type: string
          description: An array of assetId numbers represented as strings
          format: Array of unsignedInteger's
      responses:
        "200":
          description: successfull operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountAssetsBalances'
        "400":
          description: Invalid Address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /accounts/{accountId}/asset-approvals:
    get:
      tags:
      - accounts
      summary: Get an asset approval for an account.
      description: Returns information about an account's asset approval transaction.
        It is required to pass in a delegate and an assetId as query parameters.
      operationId: getAssetApprovals
      parameters:
      - name: accountId
        in: path
        description: SS58 address of the account.
        required: true
        schema:
          type: string
          format: SS58
      - name: at
        in: query
        description: Block at which to query asset approval info for the
          specified account.
        required: false
        schema:
          type: string
          description: Block height (as a non-negative integer) or hash
            (as a hex string).
          format: unsignedInteger or $hex
      - name: assetId
        in: query
        description: The `assetId` associated with the asset-approval.
        required: true
        schema:
          type: string
          description: An assetId represented as an unsignedInteger.
          format: unsignedInteger
      - name: delegate
        in: query
        description: The delegate's `accountId` associated with an asset-approval.
        required: true
        schema:
          type: string
          format: SS58
      responses:
        "200":
          description: successfull operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountAssetsApproval'
        "400":
          description: Invalid Address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /accounts/{accountId}/balance-info:
    get:
      tags:
      - accounts
      summary: Get balance information for an account.
      description: Returns information about an account's balance.
        Replaces `/balance/{address}` from versions < v1.0.0.
      operationId: getAccountBalanceInfo
      parameters:
      - name: accountId
        in: path
        description: SS58 address of the account.
        required: true
        schema:
          type: string
          format: SS58
      - name: at
        in: query
        description: Block at which to query balance info for the
          specified account.
        required: false
        schema:
          type: string
          description: Block height (as a non-negative integer) or hash
            (as a hex string).
          format: unsignedInteger or $hex
      - name: token
        in: query
        description: 'Token to query the balance of. If not specified it will query
          the chains native token (e.g. DOT for Polkadot). Note: this is only relevant
          for chains that support multiple tokens through the ORML tokens pallet.'
        required: false
        schema:
          type: string
          description: Token symbol
      - name: denominated
        in: query
        description: When set to `true` it will denominate any balance's given atomic value
          using the chains given decimal value.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountBalanceInfo'
        "400":
          description: Invalid Address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "404":
          description: account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /accounts/{accountId}/staking-info:
    get:
      tags:
      - staking
      summary: Get staking information for a _Stash_ account.
      description: Returns information about a _Stash_ account's staking activity.
        Replaces `/staking/{address}` from versions < v1.0.0.
      operationId: getStakingSummaryByAccountId
      parameters:
      - name: accountId
        in: path
        description: SS58 address of the account. Must be a _Stash_ account.
        required: true
        schema:
          format: SS58
          type: string
      - name: at
        in: query
        description: Block at which to query the staking info for the
          specified account.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountStakingInfo'
        "400":
          description: invalid blockId supplied for at query param
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "404":
          description: account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /accounts/{accountId}/staking-payouts:
    get:
      tags:
      - staking
      summary: Get payout information for a _Stash_ account.
      description: Returns payout information for the last specified eras. If
        specifying both the depth and era query params, this endpoint will
        return information for (era - depth) through era. (i.e. if depth=5 and
        era=20 information will be returned for eras 16 through 20). N.B. You
        cannot query eras less then `current_era - HISTORY_DEPTH`. N.B. The
        `nominator*` fields correspond to the address being queried, even if it
        is a validator's _Stash_ address. This is because a validator is technically
        nominating itself.
      operationId: getStakingPayoutsByAccountId
      parameters:
      - name: accountId
        in: path
        description: SS58 address of the account. Must be a _Stash_ account.
        required: true
        schema:
          format: SS58
          type: string
      - name: depth
        in: query
        description: The number of eras to query for payouts of. Must be less
          than or equal to `HISTORY_DEPTH`. In cases where `era - (depth -1)` is
          less than 0, the first era queried will be 0.
        required: false
        schema:
          type: string
          format: unsignedInteger
          default: 1
      - name: era
        in: query
        description: The era to query at.
        required: false
        schema:
          type: string
          format: unsignedInteger
          default: '`active_era - 1`'
      - name: unclaimedOnly
        in: query
        description: Only return unclaimed rewards.
        required: false
        schema:
          type: string
          format: boolean
          default: true
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountStakingPayouts'
        "400":
          description: invalid blockId supplied for at query param
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "404":
          description: account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /accounts/{accountId}/vesting-info:
    get:
      tags:
      - accounts
      summary: Get vesting information for an account.
      description: Returns the vesting schedule for an account.
        Replaces `/vesting/{address}` from versions < v1.0.0.
      operationId: getVestingSummaryByAccountId
      parameters:
      - name: accountId
        in: path
        description: SS58 address of the account.
        required: true
        schema:
          format: SS58
          type: string
      - name: at
        in: query
        description: Block at which to query the vesting info for the
          specified account.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountVestingInfo'
        "400":
          description: Invalid Address
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "404":
          description: account not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /accounts/{address}/validate:
    get:
      tags:
      - accounts
      summary: Validate a given address.
      description: Returns whether the given address is valid ss58 format, the ss58 prefix if the address has one,
        the network address format, and what the account ID is for this address.
      operationId: getValidationByAccountId
      parameters:
      - name: address
        in: path
        description: SS58 or Hex address of the account.
        required: true
        schema:
          format: SS58 or Hex
          type: string
      responses:
        "200":
          description: successfully retrieved address info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AccountValidation'
  /blocks:
    get:
      tags:
      - blocks
      summary: Get a range of blocks by their height.
      description: Given a range query parameter return an array of all the blocks within that range.
      operationId: getBlock
      parameters:
      - name: range
        in: query
        description: A range of integers. There is a max limit of 500 blocks per request.
        required: true
        example: 0-499
        schema:
          type: string
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Blocks'
        "400":
          description: invalid Block identifier supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'      
  /blocks/{blockId}:
    get:
      tags:
      - blocks
      summary: Get a block by its height or hash.
      description: Returns a single block. BlockId can either be a block hash or a
        block height. Replaces `/block/{number}` from versions < v1.0.0.
      operationId: getBlockById
      parameters:
      - name: blockId
        in: path
        description: Block identifier, as the block height or block hash.
        required: true
        schema:
          pattern: 'a-km-zA-HJ-NP-Z1-9{8,64}'
          type: string
      - name: eventDocs
        in: query
        description: When set to `true`, every event will have an extra `docs`
          property with a string of the events documentation.
        required: false
        schema:
          type: boolean
          default: false
      - name: extrinsicDocs
        in: query
        description: When set to `true`, every extrinsic will have an extra `docs`
          property with a string of the extrinsics documentation.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Block'
        "400":
          description: invalid Block identifier supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /blocks/{blockId}/header:
    get:
      tags:
      - blocks
      summary: Get a block's header by its height or hash.
      description: Returns a single block's header. BlockId can either be a block hash or a
        block height.
      operationId: getBlockHeaderById
      parameters:
      - name: blockId
        in: path
        description: Block identifier, as the block height or block hash.
        required: true
        schema:
          pattern: 'a-km-zA-HJ-NP-Z1-9{8,64}'
          type: string
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockHeader'
        "400":
          description: invalid Block identifier supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /blocks/{blockId}/extrinsics/{extrinsicIndex}:
    get:
      tags:
      - blocks
      summary: Get an extrinsic by its extrinsicIndex and block height or hash.
        The pair blockId, extrinsicIndex is sometimes referred to as a Timepoint.
      description: Returns a single extrinsic.
      operationId: getExtrinsicByTimepoint
      parameters:
      - name: blockId
        in: path
        description: Block identifier, as the block height or block hash.
        required: true
        schema:
          pattern: a-km-zA-HJ-NP-Z1-9{8,64}
          type: string
      - name: extrinsicIndex
        in: path
        description: The extrinsic's index within the block's body.
        required: true
        schema:
          type: string
      - name: eventDocs
        in: query
        description: When set to `true`, every event will have an extra `docs`
          property with a string of the events documentation.
        required: false
        schema:
          type: boolean
          default: false
      - name: extrinsicDocs
        in: query
        description: When set to `true`, every extrinsic will have an extra `docs`
          property with a string of the extrinsics documentation.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ExtrinsicIndex'
        "400":
          description: Requested `extrinsicIndex` does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /blocks/head:
    get:
      tags:
      - blocks
      summary: Get the most recently finalized block.
      description: Returns the most recently finalized block. Replaces `/block`
        from versions < v1.0.0.
      operationId: getHeadBlock
      parameters:
      - name: finalized
        in: query
        description: Boolean representing whether or not to get the finalized head.
          If it is not set the value defaults to true. When set to false it will attempt
          to get the newest known block, which may not be finalized.
        required: false
        schema:
          type: boolean
          default: true
      - name: eventDocs
        in: query
        description: When set to `true`, every event will have an extra `docs`
          property with a string of the events documentation.
        required: false
        schema:
          type: boolean
          default: false
      - name: extrinsicDocs
        in: query
        description: When set to `true`, every extrinsic will have an extra `docs`
          property with a string of the extrinsics documentation.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Block'
  /blocks/head/header:
    get:
      tags:
      - blocks
      summary: Get information about the header of the most recent finalized block.
      description: Returns the most recently finalized block's header.
      operationId: getLatestBlockHeader
      parameters:
      - name: finalized
        in: query
        description: Boolean representing whether or not to get the finalized head.
          If it is not set the value defaults to true. When set to false it will attempt
          to get the newest known block, which may not be finalized.
        required: false
        schema:
          type: boolean
          default: true
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlockHeader'
        "400":
          description: invalid Block identifier supplied
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /node/network:
    get:
      tags:
      - node
      summary: Get information about the Substrate node's activity in the peer-to-peer network.
      description: Returns network related information of the node.
      operationId: getNodeNetworking
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodeNetwork'
  /node/transaction-pool:
    get:
      tags:
      - node
      summary: Get pending extrinsics from the Substrate node.
      description: Returns the extrinsics that the node knows of that have not
        been included in a block.
      operationId: getNodeTransactionPool
      parameters:
      - name: includeFee
        in: query
        description: Boolean representing whether or not to include tips, partialFee, and priority in each extrinsic.
        required: false
        schema:
          type: boolean
          default: false
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionPool'
  /node/version:
    get:
      tags:
      - node
      summary: Get information about the Substrates node's implementation and versioning.
      description: Returns versioning information of the node.
      operationId: getNodeVersion
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NodeVersion'
  /transaction:
    post:
      tags:
      - transaction
      summary: Submit a transaction to the node's transaction pool.
      description: Accepts a valid signed extrinsic. Replaces `/tx` from versions
        < v1.0.0.
      operationId: submitTransaction
      requestBody:
        $ref: '#/components/requestBodies/Transaction'
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionSuccess'
        "400":
            description: failed to parse or submit transaction
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/TransactionFailure'
  /transaction/dry-run:
    post:
      tags:
      - transaction
      summary: Dry run an extrinsic.
      description: Use the dryrun call to practice submission of a transaction.
      operationId: dryrunTransaction
      requestBody:
        $ref: '#/components/requestBodies/Transaction'
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionDryRun'
        "500":
          description: failed to dry-run transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionFailure'
  /transaction/fee-estimate:
    post:
      tags:
      - transaction
      summary: Receive a fee estimate for a transaction.
      description: >-
        Send a serialized transaction and receive back a naive fee estimate.
        Note: `partialFee` does not include any tips that you may add to increase
        a transaction's priority. See the reference on `compute_fee`.
        Replaces `/tx/fee-estimate` from versions < v1.0.0.
        Substrate Reference:
        - `RuntimeDispatchInfo`: https://crates.parity.io/pallet_transaction_payment_rpc_runtime_api/struct.RuntimeDispatchInfo.html
        - `query_info`: https://crates.parity.io/pallet_transaction_payment/struct.Module.html#method.query_info
        - `compute_fee`: https://crates.parity.io/pallet_transaction_payment/struct.Module.html#method.compute_fee
      operationId: feeEstimateTransaction
      requestBody:
        $ref: '#/components/requestBodies/Transaction'
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionFeeEstimate'
        "500":
          description: fee estimation failure
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionFeeEstimateFailure'
  /transaction/material:
    get:
      tags:
      - transaction
      summary: Get all the network information needed to construct a transaction offline.
      description: Returns the material that is universal to constructing any
        signed transaction offline. Replaces `/tx/artifacts` from versions < v1.0.0.
      operationId: getTransactionMaterial
      parameters:
      - name: at
        in: query
        description: Block at which to retrieve the transaction construction
          material.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      - name: noMeta
        in: query
        schema:
          type: boolean
          description: If true, does not return metadata hex. This is useful when
            metadata is not needed and response time is a concern. Defaults to false.
            This is due for deprecation in future releases. Please migrate to using the
            `metadata` query param.
          default: false
      - name: metadata
        in: query
        schema:
          type: string
          description: Specifies the format of the metadata to be returned. Accepted values are
            'json', and 'scale'. 'json' being the decoded metadata, and 'scale' being the SCALE encoded metadata.
            When inputted it will override the `noMeta` query parameter.
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionMaterial'
        "400":
          description: invalid blockId supplied for at query param
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /pallets/assets/{assetId}/asset-info:
    get:
      tags:
        - pallets
      summary: Get information and metadata associated with an asset.
      description: Returns information associated with an asset which includes
        the assets `AssetDetails` and `AssetMetadata`.
      operationId: getAssetById
      parameters:
      - name: assetId
        in: path
        description: The unsignedInteger Id of an asset.
        required: true
        schema:
          type: string
          format: unsignedInteger
      - name: at
        in: query
        description: Block at which to retrieve the assetInfo.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PalletsAssetsInfo'
  /pallets/staking/progress:
    get:
      tags:
      - staking
      - pallets
      summary: Get progress on the general Staking pallet system.
      description: Returns information on the progress of key components of the
        staking system and estimates of future points of interest. Replaces
        `/staking-info` from versions < v1.0.0.
      operationId: getStakingProgress
      parameters:
      - name: at
        in: query
        description: Block at which to retrieve a staking progress report.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StakingProgress'
        "400":
          description: invalid blockId supplied for at query param
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /runtime/metadata:
    get:
      tags:
      - runtime
      summary: Get the runtime metadata in decoded, JSON form.
      description: >-
       Returns the runtime metadata as a JSON object.
       Substrate Reference:
       - FRAME Support: https://crates.parity.io/frame_support/metadata/index.html
       - Knowledge Base: https://substrate.dev/docs/en/knowledgebase/runtime/metadata
      parameters:
      - name: at
        in: query
        description: Block at which to retrieve the metadata at.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                description: Response is dependent on the runtime metadata contents.
  /runtime/code:
    get:
      tags:
      - runtime
      summary: Get the runtime wasm blob.
      description: Returns the runtime Wasm blob in hex format.
      parameters:
      - name: at
        in: query
        description: Block at which to retrieve the runtime wasm blob at.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeCode'
  /runtime/spec:
    get:
      tags:
      - runtime
      summary: Get version information of the Substrate runtime.
      description: Returns version information related to the runtime.
      parameters:
      - name: at
        in: query
        description: Block at which to retrieve runtime version information at.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RuntimeSpec'
  /pallets/{palletId}/storage:
    get:
      tags:
      - pallets
      summary: Get a list of storage items for a pallet.
      description: Returns a list of storage item metadata for storage items of the
        specified palletId.
      parameters:
      - name: palletId
        in: path
        description: 'Name or index of the pallet to query the storage of. Note: the pallet name must match what is
          specified in the runtime metadata.'
        required: true
        schema:
          type: string
      - name: adjustMetadataV13
        in: query
        description: Instruct sidecar to return `StorageEntryType` in the V13 metadata
          format rather than V14. This is a **temporary** flag to allow existing systems to migrate.
          It will be deprecated and then removed in the future.
        required: false
        schema:
          type: boolean
      - name: onlyIds
        in: query
        description: Only return the names (IDs) of the storage items instead of all of each storage
          item's metadata.
        required: false
        schema:
          type: boolean
      - name: at
        in: query
        description: Block at which to retrieve a list of
          the pallet's storage items.
        required: false
        schema:
          type: string
          description: Block identifier, as the block height or block hash.
          format: unsignedInteger or $hex
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: array
                description: Pallet info and Array of storageItemIds.
                items:
                  $ref: '#/components/schemas/PalletStorage'
        "400":
          description: invalid blockId supplied for at query param
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        "404":
          description: could not find pallet with palletId
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /pallets/{palletId}/storage/{storageItemId}:
    get:
      tags:
      - pallets
      summary: Get the value of a storage item.
      description: Returns the value stored under the storageItemId. If it is a
        map, query param key1 is required. If the storage item is double map
        query params key1 and key2 are required.
      parameters:
      - name: palletId
        in: path
        description: 'Name or index of the pallet to query the storage of. Note: pallet name aligns with
          pallet name as specified in runtime metadata.'
        required: true
        schema:
          type: string
      - name: storageItemId
        in: path
        description: Id of the storage item to query for.
        required: true
        schema:
          type: string
      - name: adjustMetadataV13
        in: query
        description: Instruct sidecar to return `StorageEntryType` in the V13 metadata
          format rather than V14. This is a **temporary** flag to allow existing systems to migrate.
          It will be deprecated and then removed in the future.
        required: false
        schema:
          type: boolean
      - name: key1
        in: query
        description: Key for a map, or first key for a double map. Required for querying
          a map.
        required: false
        schema:
          type: string
      - name: key2
        in: query