The HTTP Client-Server API

This page assumes you already know an API Root URL for a BigchainDB node or reverse proxy. It should be something like https://example.com:9984 or https://12.34.56.78:9984.

If you set up a BigchainDB node or reverse proxy yourself, and you’re not sure what the API Root URL is, then see the last section of this page for help.

BigchainDB Root URL

If you send an HTTP GET request to the BigchainDB Root URL e.g. http://localhost:9984 or https://example.com:9984 (with no /api/v1/ on the end), then you should get an HTTP response with something like the following in the body:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "api": {
    "v1": {
      "assets": "/api/v1/assets/",
      "docs": "https://docs.bigchaindb.com/projects/server/en/v1.0.0rc1/http-client-server-api.html",
      "outputs": "/api/v1/outputs/",
      "statuses": "/api/v1/statuses/",
      "streams": "ws://localhost:9985/api/v1/streams/valid_transactions",
      "transactions": "/api/v1/transactions/"
    }
  },
  "docs": "https://docs.bigchaindb.com/projects/server/en/v1.0.0rc1/",
  "keyring": [
    "6qHyZew94NMmUTYyHnkZsB8cxJYuRNEiEpXHe1ih9QX3",
    "AdDuyrTyjrDt935YnFu4VBCVDhHtY2Y6rcy7x2TFeiRi"
  ],
  "public_key": "NC8c8rYcAhyKVpx1PCV65CBmyq4YUbLysy3Rqrg8L8mz",
  "software": "BigchainDB",
  "version": "1.0.0rc1"
}

API Root Endpoint

If you send an HTTP GET request to the API Root Endpoint e.g. http://localhost:9984/api/v1/ or https://example.com:9984/api/v1/, then you should get an HTTP response that allows you to discover the BigchainDB API endpoints:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "assets": "/assets/",
  "docs": "https://docs.bigchaindb.com/projects/server/en/v1.0.0rc1/http-client-server-api.html",
  "outputs": "/outputs/",
  "statuses": "/statuses/",
  "streams": "ws://localhost:9985/api/v1/streams/valid_transactions",
  "transactions": "/transactions/"
}

Transactions

GET /api/v1/transactions/{transaction_id}

Get the transaction with the ID transaction_id.

This endpoint returns a transaction if it was included in a VALID block. All instances of a transaction in invalid/undecided blocks or the backlog are ignored and treated as if they don’t exist. If a request is made for a transaction and instances of that transaction are found only in invalid/undecided blocks or the backlog, then the response will be 404 Not Found.

Parameters:
  • transaction_id (hex string) – transaction ID

Example request:

GET /api/v1/transactions/a29b5efa7965b28dc739d899c8441feddf64704c9c9ef174e95bb2c3b60f7e8c HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "asset": {
    "data": {
      "msg": "Hello BigchainDB!"
    }
  },
  "id": "a29b5efa7965b28dc739d899c8441feddf64704c9c9ef174e95bb2c3b60f7e8c",
  "inputs": [
    {
      "fulfillment": "pGSAIDE5i63cn4X8T8N1sZ2mGkJD5lNRnBM4PZgI_zvzbr-cgUC2S7IX4uz1cNVWGF71BBfw_wfzXwgxWdQlQnq4OIl_m_fsBtXb0XJXpTYaNxCP3__1iCPHAVcq0XI5H1I5NG4M",
      "fulfills": null,
      "owners_before": [
        "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD"
      ]
    }
  ],
  "metadata": {
    "sequence": 0
  },
  "operation": "CREATE",
  "outputs": [
    {
      "amount": "1",
      "condition": {
        "details": {
          "public_key": "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD",
          "signature": null,
          "type": "ed25519-sha-256"
        },
        "uri": "ni:///sha-256;PNYwdxaRaNw60N6LDFzOWO97b8tJeragczakL8PrAPc?fpt=ed25519-sha-256&cost=131072"
      },
      "public_keys": [
        "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD"
      ]
    }
  ],
  "version": "1.0"
}
Response Headers:
 
Status Codes:
  • 200 OK – A transaction with that ID was found.
  • 404 Not Found – A transaction with that ID was not found.
GET /api/v1/transactions

The unfiltered /api/v1/transactions endpoint without any query parameters returns a status code 400. For valid filters, see the sections below.

There are however filtered requests that might come of use, given the endpoint is queried correctly. Some of them include retrieving a list of transactions that include:

In this section, we’ve listed those particular requests, as they will likely to be very handy when implementing your application on top of BigchainDB.

Note

Looking up transactions with a specific metadata field is currently not supported, however, providing a way to query based on metadata data is on our roadmap.

A generalization of those parameters follows:

Query Parameters:
 
  • asset_id (string) – The ID of the asset.
  • operation (string) – (Optional) One of the two supported operations of a transaction: CREATE, TRANSFER.
GET /api/v1/transactions?asset_id={asset_id}&operation={CREATE|TRANSFER}

Get a list of transactions that use an asset with the ID asset_id. Every TRANSFER transaction that originates from a CREATE transaction with asset_id will be included. This allows users to query the entire history or provenance of an asset.

This endpoint returns transactions only if they are decided VALID by the server.

Query Parameters:
 
  • operation (string) – (Optional) One of the two supported operations of a transaction: CREATE, TRANSFER.
  • asset_id (string) – asset ID.

Example request:

GET /api/v1/transactions?operation=TRANSFER&asset_id=a29b5efa7965b28dc739d899c8441feddf64704c9c9ef174e95bb2c3b60f7e8c HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[{
  "asset": {
    "id": "a29b5efa7965b28dc739d899c8441feddf64704c9c9ef174e95bb2c3b60f7e8c"
  },
  "id": "acbe54559e03714711816bff53a196756f21a857e357f1d5f150bd340d2cb811",
  "inputs": [
    {
      "fulfillment": "pGSAIDE5i63cn4X8T8N1sZ2mGkJD5lNRnBM4PZgI_zvzbr-cgUCsUFWezvnZSyDXW_CJ_v3_SKJRO-SiotHTeHrV3l0DvjPfyiKjoNYbyfaUANIRXmW1VO_0Vy5zLDvc2dM1X0EB",
      "fulfills": {
        "output": 0,
        "transaction_id": "a29b5efa7965b28dc739d899c8441feddf64704c9c9ef174e95bb2c3b60f7e8c"
      },
      "owners_before": [
        "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD"
      ]
    }
  ],
  "metadata": {
    "sequence": 1
  },
  "operation": "TRANSFER",
  "outputs": [
    {
      "amount": "1",
      "condition": {
        "details": {
          "public_key": "3yfQPHeWAa1MxTX9Zf9176QqcpcnWcanVZZbaHb8B3h9",
          "signature": null,
          "type": "ed25519-sha-256"
        },
        "uri": "ni:///sha-256;lu6ov4AKkee6KWGnyjOVLBeyuP0bz4-O6_dPi15eYUc?fpt=ed25519-sha-256&cost=131072"
      },
      "public_keys": [
        "3yfQPHeWAa1MxTX9Zf9176QqcpcnWcanVZZbaHb8B3h9"
      ]
    }
  ],
  "version": "1.0"
},
{
  "asset": {
    "id": "a29b5efa7965b28dc739d899c8441feddf64704c9c9ef174e95bb2c3b60f7e8c"
  },
  "id": "408d6515375ebdde8eb977147017603a98191407b73e5a5e58407fb90e81e8ad",
  "inputs": [
    {
      "fulfillment": "pGSAICw7Ul-c2lG6NFbHp3FbKRC7fivQcNGO7GS4wV3A-1QggUAIpJ3q_8Yn-hPm5xAEYA12epx4hbFfPGCZseJ4xKcFUzZlFvlyMVupib7frsdConp9baNV-0g3Rm6vHrBVRd8A",
      "fulfills": {
        "output": 0,
        "transaction_id": "acbe54559e03714711816bff53a196756f21a857e357f1d5f150bd340d2cb811"
      },
      "owners_before": [
        "3yfQPHeWAa1MxTX9Zf9176QqcpcnWcanVZZbaHb8B3h9"
      ]
    }
  ],
  "metadata": {
    "sequence": 2
  },
  "operation": "TRANSFER",
  "outputs": [
    {
      "amount": "1",
      "condition": {
        "details": {
          "public_key": "3Af3fhhjU6d9WecEM9Uw5hfom9kNEwE7YuDWdqAUssqm",
          "signature": null,
          "type": "ed25519-sha-256"
        },
        "uri": "ni:///sha-256;Ll1r0LzgHUvWB87yIrNFYo731MMUEypqvrbPATTbuD4?fpt=ed25519-sha-256&cost=131072"
      },
      "public_keys": [
        "3Af3fhhjU6d9WecEM9Uw5hfom9kNEwE7YuDWdqAUssqm"
      ]
    }
  ],
  "version": "1.0"
}]
Response Headers:
 
Status Codes:
  • 200 OK – A list of transactions containing an asset with ID asset_id was found and returned.
  • 400 Bad Request – The request wasn’t understood by the server, e.g. the asset_id querystring was not included in the request.
POST /api/v1/transactions

Push a new transaction.

Note

The posted transaction should be structurally valid and not spending an already spent output. The steps to build a valid transaction are beyond the scope of this page. One would normally use a driver such as the BigchainDB Python Driver to build a valid transaction.

Example request:

POST /api/v1/transactions/ HTTP/1.1
Host: example.com
Content-Type: application/json

{
  "asset": {
    "data": {
      "msg": "Hello BigchainDB!"
    }
  },
  "id": "a29b5efa7965b28dc739d899c8441feddf64704c9c9ef174e95bb2c3b60f7e8c",
  "inputs": [
    {
      "fulfillment": "pGSAIDE5i63cn4X8T8N1sZ2mGkJD5lNRnBM4PZgI_zvzbr-cgUC2S7IX4uz1cNVWGF71BBfw_wfzXwgxWdQlQnq4OIl_m_fsBtXb0XJXpTYaNxCP3__1iCPHAVcq0XI5H1I5NG4M",
      "fulfills": null,
      "owners_before": [
        "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD"
      ]
    }
  ],
  "metadata": {
    "sequence": 0
  },
  "operation": "CREATE",
  "outputs": [
    {
      "amount": "1",
      "condition": {
        "details": {
          "public_key": "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD",
          "signature": null,
          "type": "ed25519-sha-256"
        },
        "uri": "ni:///sha-256;PNYwdxaRaNw60N6LDFzOWO97b8tJeragczakL8PrAPc?fpt=ed25519-sha-256&cost=131072"
      },
      "public_keys": [
        "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD"
      ]
    }
  ],
  "version": "1.0"
}

Example response:

HTTP/1.1 202 Accepted
Location: ../statuses?transaction_id=a29b5efa7965b28dc739d899c8441feddf64704c9c9ef174e95bb2c3b60f7e8c
Content-Type: application/json

{
  "asset": {
    "data": {
      "msg": "Hello BigchainDB!"
    }
  },
  "id": "a29b5efa7965b28dc739d899c8441feddf64704c9c9ef174e95bb2c3b60f7e8c",
  "inputs": [
    {
      "fulfillment": "pGSAIDE5i63cn4X8T8N1sZ2mGkJD5lNRnBM4PZgI_zvzbr-cgUC2S7IX4uz1cNVWGF71BBfw_wfzXwgxWdQlQnq4OIl_m_fsBtXb0XJXpTYaNxCP3__1iCPHAVcq0XI5H1I5NG4M",
      "fulfills": null,
      "owners_before": [
        "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD"
      ]
    }
  ],
  "metadata": {
    "sequence": 0
  },
  "operation": "CREATE",
  "outputs": [
    {
      "amount": "1",
      "condition": {
        "details": {
          "public_key": "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD",
          "signature": null,
          "type": "ed25519-sha-256"
        },
        "uri": "ni:///sha-256;PNYwdxaRaNw60N6LDFzOWO97b8tJeragczakL8PrAPc?fpt=ed25519-sha-256&cost=131072"
      },
      "public_keys": [
        "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD"
      ]
    }
  ],
  "version": "1.0"
}

Note

If the server is returning a 202 HTTP status code, then the transaction has been accepted for processing. To check the status of the transaction, poll the link to the status monitor provided in the Location header or listen to server’s WebSocket Event Stream API.

Response Headers:
 
  • Content-Typeapplication/json
  • Location – Relative link to a status monitor for the submitted transaction.
Status Codes:
  • 202 Accepted – The pushed transaction was accepted in the BACKLOG, but the processing has not been completed.
  • 400 Bad Request – The transaction was malformed and not accepted in the BACKLOG.

Transaction Outputs

The /api/v1/outputs endpoint returns transactions outputs filtered by a given public key, and optionally filtered to only include either spent or unspent outputs.

GET /api/v1/outputs

Get transaction outputs by public key. The public_key parameter must be a base58 encoded ed25519 public key associated with transaction output ownership.

Returns a list of transaction outputs.

Parameters:
  • public_key – Base58 encoded public key associated with output ownership. This parameter is mandatory and without it the endpoint will return a 400 response code.
  • spent – Boolean value (“true” or “false”) indicating if the result set should include only spent or only unspent outputs. If not specified the result includes all the outputs (both spent and unspent) associated with the public_key.
GET /api/v1/outputs?public_key={public_key}
Return all outputs, both spent and unspent, for the public_key.

Example request:

GET /api/v1/outputs?public_key=1AAAbbb...ccc HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "output": 0,
    "transaction_id": "2d431073e1477f3073a4693ac7ff9be5634751de1b8abaa1f4e19548ef0b4b0e"
  },
  {
    "output": 1,
    "transaction_id": "2d431073e1477f3073a4693ac7ff9be5634751de1b8abaa1f4e19548ef0b4b0e"
  }
]
Status Codes:
  • 200 OK – A list of outputs were found and returned in the body of the response.
  • 400 Bad Request – The request wasn’t understood by the server, e.g. the public_key querystring was not included in the request.
GET /api/v1/outputs?public_key={public_key}&spent=true
Return all spent outputs for public_key.

Example request:

GET /api/v1/outputs?public_key=1AAAbbb...ccc&spent=true HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "output": 0,
    "transaction_id": "2d431073e1477f3073a4693ac7ff9be5634751de1b8abaa1f4e19548ef0b4b0e"
  }
]
Status Codes:
  • 200 OK – A list of outputs were found and returned in the body of the response.
  • 400 Bad Request – The request wasn’t understood by the server, e.g. the public_key querystring was not included in the request.
GET /api/v1/outputs?public_key={public_key}&spent=false
Return all unspent outputs for public_key.

Example request:

GET /api/v1/outputs?public_key=1AAAbbb...ccc&spent=false HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "output": 1,
    "transaction_id": "2d431073e1477f3073a4693ac7ff9be5634751de1b8abaa1f4e19548ef0b4b0e"
  }
]
Status Codes:
  • 200 OK – A list of outputs were found and returned in the body of the response.
  • 400 Bad Request – The request wasn’t understood by the server, e.g. the public_key querystring was not included in the request.

Statuses

GET /api/v1/statuses

Get the status of an asynchronously written transaction or block by their id.

Query Parameters:
 
  • transaction_id (string) – transaction ID
  • block_id (string) – block ID

Note

Exactly one of the transaction_id or block_id query parameters must be used together with this endpoint (see below for getting transaction statuses and block statuses).

GET /api/v1/statuses?transaction_id={transaction_id}

Get the status of a transaction.

The possible status values are undecided, valid or backlog. If a transaction in neither of those states is found, a 404 Not Found HTTP status code is returned. We’re currently looking into ways to unambigously let the user know about a transaction’s status that was included in an invalid block.

Example request:

GET /statuses?transaction_id=a29b5efa7965b28dc739d899c8441feddf64704c9c9ef174e95bb2c3b60f7e8c HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "valid"
}
Response Headers:
 
Status Codes:
  • 200 OK – A transaction with that ID was found.
  • 404 Not Found – A transaction with that ID was not found.
GET /api/v1/statuses?block_id={block_id}

Get the status of a block.

The possible status values are undecided, valid or invalid.

Example request:

GET /api/v1/statuses?block_id=d9b76d309f223b24790bbe92c66a1a22e1d5118694c0d396454ddbf26350051c HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "valid"
}
Response Headers:
 
Status Codes:
  • 200 OK – A block with that ID was found.
  • 404 Not Found – A block with that ID was not found.

Assets

GET /api/v1/assets

Return all the assets that match a given text search.

Query Parameters:
 
  • text search (string) – Text search string to query.
  • limit (int) – (Optional) Limit the number of returned assets. Defaults to 0 meaning return all matching assets.

Note

Currently this enpoint is only supported if the server is running MongoDB as the backend.

Return all assets that match a given text search. The id of the asset is the same id of the transaction that created the asset.

If no assets match the text search it returns an empty list.

If the text string is empty or the server does not support text search, a 400 is returned.

The results are sorted by text score. For more information about the behavior of text search see MongoDB text search behavior

Example request:

GET /api/v1/assets/?search=bigchaindb HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-type: application/json

[
    {
        "data": {"msg": "Hello BigchainDB 1!"},
        "id": "51ce82a14ca274d43e4992bbce41f6fdeb755f846e48e710a3bbb3b0cf8e4204"
    },
    {
        "data": {"msg": "Hello BigchainDB 2!"},
        "id": "b4e9005fa494d20e503d916fa87b74fe61c079afccd6e084260674159795ee31"
    },
    {
        "data": {"msg": "Hello BigchainDB 3!"},
        "id": "fa6bcb6a8fdea3dc2a860fcdc0e0c63c9cf5b25da8b02a4db4fb6a2d36d27791"
    }
]
Response Headers:
 
Status Codes:
  • 200 OK – The query was executed successfully.
  • 400 Bad Request – The query was not executed successfully. Returned if the text string is empty or the server does not support text search.
GET /api/v1/assets?search={text_search}&limit={n_documents}

Return at most n assets that match a given text search.

If no assets match the text search it returns an empty list.

If the text string is empty or the server does not support text search, a 400 is returned.

The results are sorted by text score. For more information about the behavior of text search see MongoDB text search behavior

Example request:

GET /api/v1/assets/?search=bigchaindb&limit=2 HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-type: application/json

[
    {
        "data": {"msg": "Hello BigchainDB 1!"},
        "id": "51ce82a14ca274d43e4992bbce41f6fdeb755f846e48e710a3bbb3b0cf8e4204"
    },
    {
        "data": {"msg": "Hello BigchainDB 2!"},
        "id": "b4e9005fa494d20e503d916fa87b74fe61c079afccd6e084260674159795ee31"
    },
]
Response Headers:
 
Status Codes:
  • 200 OK – The query was executed successfully.
  • 400 Bad Request – The query was not executed successfully. Returned if the text string is empty or the server does not support text search.

Advanced Usage

The following endpoints are more advanced and meant for debugging and transparency purposes.

More precisely, the blocks endpoint allows you to retrieve a block by block_id as well the list of blocks that a certain transaction with transaction_id occured in (a transaction can occur in multiple invalid blocks until it either gets rejected or validated by the system). This endpoint gives the ability to drill down on the lifecycle of a transaction

The votes endpoint contains all the voting information for a specific block. So after retrieving the block_id for a given transaction_id, one can now simply inspect the votes that happened at a specific time on that block.

Blocks

GET /api/v1/blocks/{block_id}

Get the block with the ID block_id. Any blocks, be they VALID, UNDECIDED or INVALID will be returned. To check a block’s status independently, use the Statuses endpoint. To check the votes on a block, have a look at the votes endpoint.

Parameters:
  • block_id (hex string) – block ID

Example request:

GET /api/v1/blocks/d9b76d309f223b24790bbe92c66a1a22e1d5118694c0d396454ddbf26350051c HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "block": {
    "node_pubkey": "DngBurxfeNVKZWCEcDnLj1eMPAS7focUZTE5FndFGuHT",
    "timestamp": "1498208256",
    "transactions": [
      {
        "asset": {
          "data": {
            "msg": "Hello BigchainDB!"
          }
        },
        "id": "a29b5efa7965b28dc739d899c8441feddf64704c9c9ef174e95bb2c3b60f7e8c",
        "inputs": [
          {
            "fulfillment": "pGSAIDE5i63cn4X8T8N1sZ2mGkJD5lNRnBM4PZgI_zvzbr-cgUC2S7IX4uz1cNVWGF71BBfw_wfzXwgxWdQlQnq4OIl_m_fsBtXb0XJXpTYaNxCP3__1iCPHAVcq0XI5H1I5NG4M",
            "fulfills": null,
            "owners_before": [
              "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD"
            ]
          }
        ],
        "metadata": {
          "sequence": 0
        },
        "operation": "CREATE",
        "outputs": [
          {
            "amount": "1",
            "condition": {
              "details": {
                "public_key": "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD",
                "signature": null,
                "type": "ed25519-sha-256"
              },
              "uri": "ni:///sha-256;PNYwdxaRaNw60N6LDFzOWO97b8tJeragczakL8PrAPc?fpt=ed25519-sha-256&cost=131072"
            },
            "public_keys": [
              "4K9sWUMFwTgaDGPfdynrbxWqWS6sWmKbZoTjxLtVUibD"
            ]
          }
        ],
        "version": "1.0"
      }
    ],
    "voters": [
      "DngBurxfeNVKZWCEcDnLj1eMPAS7focUZTE5FndFGuHT"
    ]
  },
  "id": "d9b76d309f223b24790bbe92c66a1a22e1d5118694c0d396454ddbf26350051c",
  "signature": "53wxrEQDYk1dXzmvNSytbCfmNVnPqPkDQaTnAe8Jf43s6ssejPxezkCvUnGTnduNUmaLjhaan1iRLi3peu6s5DzA"
}
Response Headers:
 
Status Codes:
  • 200 OK – A block with that ID was found.
  • 400 Bad Request – The request wasn’t understood by the server, e.g. just requesting /blocks without the block_id.
  • 404 Not Found – A block with that ID was not found.
GET /api/v1/blocks

The unfiltered /blocks endpoint without any query parameters returns a 400 status code. The list endpoint should be filtered with a transaction_id query parameter, see the /blocks?transaction_id={transaction_id}&status={UNDECIDED|VALID|INVALID} endpoint.

Example request:

GET /api/v1/blocks HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 400 Bad Request
Status Codes:
  • 400 Bad Request – The request wasn’t understood by the server, e.g. just requesting /blocks without the block_id.
GET /api/v1/blocks?transaction_id={transaction_id}&status={UNDECIDED|VALID|INVALID}

Retrieve a list of block_id with their corresponding status that contain a transaction with the ID transaction_id.

Any blocks, be they UNDECIDED, VALID or INVALID will be returned if no status filter is provided.

Note

In case no block was found, an empty list and an HTTP status code 200 OK is returned, as the request was still successful.

Query Parameters:
 
  • transaction_id (string) – transaction ID (required)
  • status (string) – Filter blocks by their status. One of VALID, UNDECIDED or INVALID.

Example request:

GET /api/v1/blocks?transaction_id=a29b5efa7965b28dc739d899c8441feddf64704c9c9ef174e95bb2c3b60f7e8c HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[
  "b54a97521c97bbff28ff13a4a5d35be977add76e0bb276901afea6539b26bc1c",
  "d9b76d309f223b24790bbe92c66a1a22e1d5118694c0d396454ddbf26350051c"
]
Response Headers:
 
Status Codes:
  • 200 OK – A list of blocks containing a transaction with ID transaction_id was found and returned.
  • 400 Bad Request – The request wasn’t understood by the server, e.g. just requesting /blocks, without defining transaction_id.

Votes

GET /api/v1/votes?block_id={block_id}

Retrieve a list of votes for a certain block with ID block_id. To check for the validity of a vote, a user of this endpoint needs to perform the following steps:

  1. Check if the vote’s node_pubkey is allowed to vote.
  2. Verify the vote’s signature against the vote’s body (vote.vote) and node_pubkey.
Query Parameters:
 
  • block_id (string) – The block ID to filter the votes.

Example request:

GET /api/v1/votes?block_id=d9b76d309f223b24790bbe92c66a1a22e1d5118694c0d396454ddbf26350051c HTTP/1.1
Host: example.com

Example response:

HTTP/1.1 200 OK
Content-Type: application/json

[{
  "node_pubkey": "DngBurxfeNVKZWCEcDnLj1eMPAS7focUZTE5FndFGuHT",
  "signature": "4sZDzr6yY9PA3ao5qrysgXDfFdXvr5tS79RoAwFVpm7qcMd6r6qZQA18Hh3B2Xn4irzfqZ9Q4vpsqyJphygE7YoS",
  "vote": {
    "invalid_reason": null,
    "is_block_valid": true,
    "previous_block": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "timestamp": "1498208256",
    "voting_for_block": "d9b76d309f223b24790bbe92c66a1a22e1d5118694c0d396454ddbf26350051c"
  }
}]
Response Headers:
 
Status Codes:
  • 200 OK – A list of votes voting for a block with ID block_id was found and returned.
  • 400 Bad Request – The request wasn’t understood by the server, e.g. just requesting /votes, without defining block_id.

Determining the API Root URL

When you start BigchainDB Server using bigchaindb start, an HTTP API is exposed at some address. The default is:

http://localhost:9984/api/v1/

It’s bound to localhost, so you can access it from the same machine, but it won’t be directly accessible from the outside world. (The outside world could connect via a SOCKS proxy or whatnot.)

The documentation about BigchainDB Server Configuration Settings has a section about how to set server.bind so as to make the HTTP API publicly accessible.

If the API endpoint is publicly accessible, then the public API Root URL is determined as follows:

  • The public IP address (like 12.34.56.78) is the public IP address of the machine exposing the HTTP API to the public internet (e.g. either the machine hosting Gunicorn or the machine running the reverse proxy such as Nginx). It’s determined by AWS, Azure, Rackspace, or whoever is hosting the machine.
  • The DNS hostname (like example.com) is determined by DNS records, such as an “A Record” associating example.com with 12.34.56.78
  • The port (like 9984) is determined by the server.bind setting if Gunicorn is exposed directly to the public Internet. If a reverse proxy (like Nginx) is exposed directly to the public Internet instead, then it could expose the HTTP API on whatever port it wants to. (It should expose the HTTP API on port 9984, but it’s not bound to do that by anything other than convention.)