RESTful API Reference#

The RESTful APIs are low level client implementations based on

Used to communicate with the Tangle network through the Node.

Node#

Endpoint Setting#

struct iota_client_conf_t#

Client endpoint configuration.

Public Members

char host[IOTA_ENDPOINT_MAX_LEN]#

domain name or IP as string

uint16_t port#

port to connect

bool use_tls#

Use TLS or not.

Error Response#

struct res_err_t#

Node API error response.

Public Members

char *code#

an error code from node response

char *msg#

a error message from node response

/health#

Returns the health of the node. A node considers itself healthy if its solid milestone is at most two delta away from the latest known milestone, has at least one ongoing gossip stream and the latest known milestone is newer than 5 minutes. This information might be useful for load-balancing or uptime monitoring.

int get_health(iota_client_conf_t const *conf, bool *health)#

Returns the health of the node.

A node considers itself healthy if its current confirmed milestone is at most two delta away from the latest known milestone, has at least one ongoing gossip stream and the latest known milestone is newer than 5 minutes.

Parameters

  • conf – [in] The endpoint configuration

  • health – [out] Is node health?

Returns

int 0 on success

/api/v2/info#

Returns general information about the node.

struct get_node_info_t#

The general information about the connected node.

struct res_node_info_t#

The response of get node info.

int get_node_info(iota_client_conf_t const *conf, res_node_info_t *res)#

Gets info API.

Parameters

  • conf – [in] The client endpoint configuration

  • res – [out] A response object of node info

Returns

int 0 on success

Tangle#

/api/v2/tips#

Returns tips that are ideal for attaching a block. The tips can be considered as non-lazy and are therefore ideal for attaching a block.

struct res_tips_t#

The response of get tips.

int get_tips(iota_client_conf_t const *conf, res_tips_t *res)#

Gets tips for attaching to a block.

Returns tips that are ideal for attaching to a block. The tips can be considered as non-lazy and are therefore ideal for attaching a block.

Parameters

  • conf – [in] The client endpoint configuration

  • res – [out] A response object of tips object

Returns

int 0 on success

Blocks#

/api/v2/blocks#

Submit a block. The node takes care of missing fields and tries to build the block. On success, the block will be stored in the Tangle. This endpoint will return the identifier of the built block. The node will try to auto-fill the following fields in case they are missing: protocolVersion, parents, nonce. If payload is missing, the block will be built without a payload.

struct res_send_block_t#

The response of send block.

int send_core_block(iota_client_conf_t const *const conf, core_block_t *blk, res_send_block_t *res)#

Send block thought core block object.

Parameters

  • conf – [in] The client endpoint configuration

  • blk – [in] A Block object

  • res – [out] An error or block ID

Returns

int 0 on success

/api/v2/blocks/{blockId}#

Find a block by its identifier.

struct res_block_t#

The response of get block.

int get_block_by_id(iota_client_conf_t const *conf, char const blk_id[], res_block_t *res)#

Get the block data from a given block ID.

Parameters

  • conf – [in] The client endpoint configuration

  • blk_id – [in] A block ID to query

  • res – [out] The block body of the given ID

Returns

int 0 on success

/api/v2/blocks/{blockId}/metadata#

Find the metadata of a given block ID.

struct block_meta_t#

Stores the block metadata object.

struct res_block_meta_t#

The response of get block metadata API call.

int get_block_metadata(iota_client_conf_t const *ctx, char const blk_id[], res_block_meta_t *res)#

Gets block metadata from a given block ID.

Parameters

  • ctx – [in] The client configuration

  • blk_id – [in] A block ID string for query

  • res – [out] A block metadata response

Returns

int 0 on success

UTXO#

/api/v2/outputs/{outputId}#

Find an output data by its identifier.

struct get_output_t#

An output response object.

struct res_output_t#

The response object of get_output.

int get_output(iota_client_conf_t const *conf, char const output_id[], res_output_t *res)#

Get an output from a given output ID.

Parameters

  • conf – [in] The client endpoint configuration

  • output_id – [in] A hex string of the output ID

  • res – [out] The response object from node

Returns

int 0 on success

/api/v2/transaction/{transactionId}/included-block#

Returns the included block of a transaction.

int get_transaction_included_block_by_id(iota_client_conf_t const *conf, char const tx_id[], res_block_t *res)#

Get included block data from a given transaction ID.

Parameters

  • conf – [in] The client endpoint configuration

  • tx_id – [in] A transaction ID to query

  • res – [out] The block body of the given ID

Returns

int 0 on success

UTXO Indexer#

query parameters#

enum outputs_query_params_e#

All Query Params Type.

Values:

enumerator QUERY_PARAM_ADDRESS#

The Bech32-encoded address that should be used to query outputs.

enumerator QUERY_PARAM_ALIAS_ADDRESS#

The alias address that should be used to query some outputs.

enumerator QUERY_PARAM_HAS_NATIVE_TOKENS#

To filter outputs based on the presence of native tokens.

enumerator QUERY_PARAM_MIN_NATIVE_TOKENS#

To filter outputs that have at least a certain number of distinct native tokens.

enumerator QUERY_PARAM_MAX_NATIVE_TOKENS#

To filter outputs that have at most a certain number of distinct native tokens.

enumerator QUERY_PARAM_HAS_STORAGE_RET#

The presence of storage return unlock condition.

enumerator QUERY_PARAM_STORAGE_RET_ADDR#

The specific return address in the storage deposit return unlock condition.

enumerator QUERY_PARAM_HAS_TIMELOCK#

To filter outputs based on the presence of timelock unlock condition.

enumerator QUERY_PARAM_TIMELOCKED_BEFORE#

To return outputs that are timelocked before a certain Unix timestamp.

enumerator QUERY_PARAM_TIMELOCKED_AFTER#

To return outputs that are timelocked after a certain Unix timestamp.

enumerator QUERY_PARAM_TIMELOCKED_BEFORE_MS#

To return outputs that are timelocked before a certain milestone index.

enumerator QUERY_PARAM_TIMELOCKED_AFTER_MS#

To return outputs that are timelocked after a certain milestone index.

enumerator QUERY_PARAM_HAS_EXP_COND#

To filters outputs based on the presence of expiration unlock condition.

enumerator QUERY_PARAM_EXPIRES_BEFORE#

To return outputs that expire before a certain Unix timestamp.

enumerator QUERY_PARAM_EXPIRES_AFTER#

To return outputs that expire after a certain Unix timestamp.

enumerator QUERY_PARAM_EXPIRES_BEFORE_MS#

To return outputs that expire before a certain milestone index.

enumerator QUERY_PARAM_EXPIRES_AFTER_MS#

To return outputs that expire after a certain milestone index.

enumerator QUERY_PARAM_EXP_RETURN_ADDR#

To filter outputs based on the presence of a specific return address in the expiration unlock condition.

enumerator QUERY_PARAM_SENDER#

To query outputs based on bech32-encoded sender address.

enumerator QUERY_PARAM_TAG#

A tag block to search for outputs matching it.

enumerator QUERY_PARAM_CREATED_BEFORE#

To return outputs that were created before a certain Unix timestamp.

enumerator QUERY_PARAM_CREATED_AFTER#

To return outputs that were created after a certain Unix timestamp.

enumerator QUERY_PARAM_PAGE_SIZE#

The maximum amount of items returned in one api call.

enumerator QUERY_PARAM_CURSOR#

A cursor to start the query (confirmationMS+outputId.pageSize)

enumerator QUERY_PARAM_STATE_CTRL#

To query outputs based on bech32-encoded state controller address.

enumerator QUERY_PARAM_GOV#

To query outputs based on bech32-encoded governor (governance controller) address.

enumerator QUERY_PARAM_ISSUER#

To query outputs based on bech32-encoded issuer address.

struct outputs_query_params_t#

A Query Param Object.

struct outputs_query_list#

A list of outputs query parameters.

outputs_query_list_t *outputs_query_list_new()#

New a query parameter list.

The filter for output IDs

Returns

NULL

int outputs_query_list_add(outputs_query_list_t **list, outputs_query_params_e type, char const *const param)#

Add a query parameter to the list.

Parameters

  • list – [in] A query item list

  • type – [in] A query parameter type

  • param – [in] A query parameter

Returns

int 0 on success

size_t get_outputs_query_str_len(outputs_query_list_t *list)#

Get the length of query string present in list.

Parameters

  • list – [in] A query item list

Returns

size_t The length of the query string

size_t get_outputs_query_str(outputs_query_list_t *list, char *buf, size_t buf_len)#

Get the query string present in list.

Parameters

  • list – [in] A query item list

  • buf – [in] A buffer to hold query string

  • buf_len – [in] The length of the buffer

Returns

size_t the length in bytes that written to the buffer

void outputs_query_list_free(outputs_query_list_t *list)#

Free query list.

Indexer Response#

struct get_outputs_id_t#

An output object.

struct res_outputs_id_t#

The response of get outputs from address.

/api/plugins/indexer/v1/outputs/basic#

Returns Basic outputs filtered based on parameters.

int get_basic_outputs(iota_client_conf_t const *conf, char const *const indexer_path, outputs_query_list_t *list, res_outputs_id_t *res)#

Gets output IDs from a given address.

Parameters

  • conf – [in] The client endpoint configuration

  • indexer_path – [in] The api end-point indexer path

  • list – [in] A list of optional query parameters

  • res – [out] A response object

Returns

int 0 on successful

/api/plugins/indexer/v1/outputs/alias#

Returns Alias outputs filtered based on parameters.

int get_alias_outputs(iota_client_conf_t const *conf, char const *const indexer_path, outputs_query_list_t *list, res_outputs_id_t *res)#

Gets output IDs from a given Alias address.

Parameters

  • conf – [in] The client endpoint configuration

  • indexer_path – [in] The api end-point indexer path

  • list – [in] A list of optional query parameters

  • res – [out] A response object

Returns

int 0 on successful

/api/plugins/indexer/v1/outputs/alias/{aliasId}#

Returns the output ID of the current unspent Alias output for Alias ID.

int get_outputs_from_alias_id(iota_client_conf_t const *conf, char const *const indexer_path, char const alias_id[], res_outputs_id_t *res)#

Gets output IDs from a given Alias ID.

Parameters

  • conf – [in] The client endpoint configuration

  • indexer_path – [in] The api end-point indexer path

  • alias_id – [in] An Alias ID in hex string format

  • res – [out] A response object

Returns

int 0 on successful

/api/plugins/indexer/v1/outputs/foundry#

Returns Foundry outputs filtered based on parameters.

int get_foundry_outputs(iota_client_conf_t const *conf, char const *const indexer_path, outputs_query_list_t *list, res_outputs_id_t *res)#

Gets output IDs from a given Foundry address.

Parameters

  • conf – [in] The client endpoint configuration

  • indexer_path – [in] The api end-point indexer path

  • list – [in] A list of optional query parameters

  • res – [out] A response object

Returns

int 0 on successful

/api/plugins/indexer/v1/outputs/foundry/{foundryId}#

Returns the output ID of the current unspent foundry output for Foundry Id

int get_outputs_from_foundry_id(iota_client_conf_t const *conf, char const *const indexer_path, char const foundry_id[], res_outputs_id_t *res)#

Gets output IDs from a given Foundry ID.

Parameters

  • conf – [in] The client endpoint configuration

  • indexer_path – [in] The api end-point indexer path

  • foundry_id – [in] A Foundry ID in hex string format

  • res – [out] A response object

Returns

int 0 on successful

/api/plugins/indexer/v1/outputs/nft#

Returns NFT outputs filtered based on parameters

int get_nft_outputs(iota_client_conf_t const *conf, char const *const indexer_path, outputs_query_list_t *list, res_outputs_id_t *res)#

Gets output IDs from a given NFT address.

Parameters

  • conf – [in] The client endpoint configuration

  • indexer_path – [in] The api end-point indexer path

  • addr – [in] An NFT address in hex string format

  • res – [out] A response object

Returns

int 0 on successful

/api/plugins/indexer/v1/outputs/nft/{nftId}#

Returns the output ID of the current unspent NFT output for NFT ID.

int get_outputs_from_nft_id(iota_client_conf_t const *conf, char const *const indexer_path, char const nft_id[], res_outputs_id_t *res)#

Gets output IDs from a given NFT ID.

Parameters

  • conf – [in] The client endpoint configuration

  • indexer_path – [in] The api end-point indexer path

  • nft_id – [in] An NFT ID in hex string format

  • res – [out] A response object

Returns

int 0 on successful