dxs
/
onionr
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity
onionr/docs/http-api.md

3.8 KiB
Executable File
Raw Blame History

Onionr HTTP API

All HTTP interfaces in the Onionr reference client use the Flask web framework with the gevent WSGI server.

Client & Public difference

The client API server is a locked down interface intended for authenticated local communication.

The public API server is available only remotely from Tor & I2P. It is the interface in which peers use to communicate with one another.

Client API

Please note: endpoints that simply provide static web app files are not documented here.

  • /serviceactive/pubkey
    • Methods: GET
    • Returns true or false based on if a given public key has an active direct connection service.
  • /queueResponseAdd/key (DEPRECATED)
    • Methods: POST
    • Accepts form key 'data' to set queue response information from a plugin
    • Returns success if no error occurs
  • /queueResponse/key (DEPRECATED)
    • Methods: GET
    • Returns the queue response for a key. Returns failure with a 404 code if a code is not set.
  • /ping
    • Methods: GET
    • Returns "pong!"
  • /getblocksbytype/type
    • Methods: GET
    • Returns a list of stored blocks by a given type
  • /getblockbody/hash
    • Methods: GET
    • Returns the main data section of a block
  • /getblockdata/hash
    • Methods: GET
    • Returns the entire data contents of a block, including metadata.
  • /getblockheader/hash
    • Methods: GET
    • Returns the header (metadata section) of a block.
  • /lastconnect
    • Methods: GET
    • Returns the epoch timestamp of when the last incoming connection to the public API server was logged
  • /site/hash
    • Methods: GET
    • Returns HTML content out of a block
  • /waitforshare/hash
    • Methods: POST
    • Prevents the public API server from listing or sharing a block until it has been uploaded to at least 1 peer.
  • /shutdown
    • Methods: GET
    • Shutdown Onionr. You should probably use /shutdownclean instead.
  • /shutdownclean
    • Methods: GET
    • Tells the communicator daemon to shutdown Onionr. Slower but cleaner.
  • /getstats
    • Methods: GET
    • Returns some JSON serialized statistics
  • /getuptime
    • Methods: GET
    • Returns uptime in seconds
  • /getActivePubkey
    • Methods: GET
    • Returns the current active public key in base32 format
  • /getHumanReadable/pubkey
    • Methods: GET
    • Echos the specified public key in mnemonic format
  • /insertblock
    • Methods: POST
    • Accepts JSON data for creating a new block. 'message' contains the block data, 'to' specifies the peer's public key to encrypt the data to, 'sign' is a boolean for signing the message.

Public API

v0

  • /
    • Methods: GET
    • Returns a basic HTML informational banner describing Onionr.
  • /getblocklist
    • Methods: GET
    • URI Parameters:
      • date: unix epoch timestamp for offset
    • Returns a list of block hashes stored on the node since an offset (all blocks if no timestamp is specified)
  • /getdata/block-hash
    • Methods: GET
    • Returns data for a block based on a provided hash
  • /www/file-path
    • Methods: GET
    • Returns file data. Intended for manually sharing file data directly from an Onionr node.
  • /ping
    • Methods: GET
    • Returns 'pong!'
  • /pex
    • Methods: GET
    • Returns a list of peer addresses reached within recent time
  • /announce
    • Methods: POST
    • Accepts form data for 'node' (valid node address) and 'random' which is a nonce when hashed (blake2b_256) in the format hash(peerAddress+serverAddress+nonce), begins with at least 5 zeros.
    • Returns 200 with 'Success' if no error occurs. If the post is invalid, 'failure' with code 406 is returned.
  • /upload
    • Methods: POST
    • Accepts form data for 'block' as a 'file' upload.
    • Returns 200 with 'success' if no error occurs. If the block cannot be accepted, 'failure' with 400 is returned.

Direct Connection API