openapi: 3.0.3
info:
  title: BigchainDB HTTP Assets Transactions API
  version: v1
  description: The BigchainDB HTTP Client-Server API. BigchainDB is an open-source blockchain database that combines high throughput, low latency, immutable data storage and built-in asset support with decentralized control. This document is a faithful transcription of the operations, parameters and status codes published in the official BigchainDB Server HTTP API reference; BigchainDB does not publish its own machine-readable OpenAPI, so this spec was generated by the API Evangelist enrichment pipeline from the documented endpoint reference.
  x-apievangelist-generated: true
  x-source: https://docs.bigchaindb.com/projects/server/en/latest/http-client-server-api.html
  license:
    name: Apache-2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  contact:
    name: BigchainDB GmbH
    url: https://www.bigchaindb.com/
servers:
- url: https://{host}:9984
  description: A BigchainDB node (self-hosted or hosted network). Default node port is 9984.
  variables:
    host:
      default: test.ipdb.io
      description: Hostname of a BigchainDB node (the IPDB test network historically ran at test.ipdb.io).
tags:
- name: Transactions
  description: Create and read transactions (CREATE and TRANSFER operations).
paths:
  /api/v1/transactions/{transaction_id}:
    get:
      tags:
      - Transactions
      operationId: getTransaction
      summary: Get a transaction by ID
      description: Retrieve a single committed transaction by its transaction id.
      parameters:
      - name: transaction_id
        in: path
        required: true
        description: The id of the transaction to retrieve.
        schema:
          type: string
      responses:
        '200':
          description: The requested transaction.
        '404':
          description: A transaction with that id was not found (or is not yet committed).
  /api/v1/transactions:
    get:
      tags:
      - Transactions
      operationId: listTransactions
      summary: List transactions for an asset
      description: Get a list of transactions that use an asset with the given asset_id. The operation type (CREATE or TRANSFER) may be filtered, and last_tx returns only the latest transaction.
      parameters:
      - name: asset_id
        in: query
        required: true
        description: The asset id to filter transactions by.
        schema:
          type: string
      - name: operation
        in: query
        required: false
        description: Filter by transaction operation.
        schema:
          type: string
          enum:
          - CREATE
          - TRANSFER
      - name: last_tx
        in: query
        required: false
        description: When true, return only the last transaction.
        schema:
          type: boolean
      responses:
        '200':
          description: A list of matching transactions.
        '400':
          description: The request was malformed or a required parameter was missing.
    post:
      tags:
      - Transactions
      operationId: createTransaction
      summary: Submit a transaction
      description: Push a new transaction to the node. The signed transaction is validated and, depending on mode, returned when accepted (async), when validated (sync), or when committed to a block (commit).
      parameters:
      - name: mode
        in: query
        required: false
        description: Persistence/acknowledgement mode for the submitted transaction.
        schema:
          type: string
          enum:
          - async
          - sync
          - commit
          default: async
      requestBody:
        required: true
        description: A signed BigchainDB transaction (CREATE or TRANSFER).
        content:
          application/json:
            schema:
              type: object
      responses:
        '202':
          description: The transaction was accepted for processing.
        '400':
          description: The transaction was invalid (bad signature, schema, or amount).
externalDocs:
  description: BigchainDB Server HTTP Client-Server API
  url: https://docs.bigchaindb.com/projects/server/en/latest/http-client-server-api.html