NAV Navbar
shell javascript
  • Introduction
  • Future Features
  • Authentication
  • Add Entry
  • Scalability and Reliability
  • Credits
  • Introduction

    Welcome to the Facto API! At the moment the API only allows you to add entries into Factom and provide you with a callback once the transaction has been confirmed in a directory block on Factom.

    Future Features

    At the moment we only have the capability to add entries.

    We plan to develop richer functionality, that will allow you to add chains and allow you to query and search the factom blockchain.

    Authentication

    To authorize, use this code:

    # With shell, you can just pass the correct header with each request
    curl "https://api.facto.cloud/v1/{request}"
      -H "Authorization: Apikey <developer api key>"
    

    Make sure to replace <developer api key> with your API key.

    Facto uses API keys to allow access to the API. You can register for an API key by messaging @schalk on discord.

    Facto expects for the API key to be included in all API requests to the server in a header that looks like the following:

    Authorization: Apikey <developer api key>

    Add Entry

    curl -X POST \
      https://api.facto.cloud/v1/chains/cc981114aafc7274473d59f844d7f86c20ee3b82e13f61575f923af3ddf10998/entries \
      -H 'Authorization: Apikey <developer api key>' \
      -d '{
        "chainId": "930bf02ebc8a92c3e4be0f5db7778b6dd9f379f3f976b15f0fc8089fecfb1dc5",
        "content": BASE64('content'),
        "externalIds": [BASE64('external id 1'), BASE64('external id 2')],
        "callbackUrl": "https://webhook.site/0a69fe86-7e36-445d-ba5f-9837f0efb92c"
    }'
    
    not yet done
    

    The above command returns JSON structured like this:

    {
        "entryHash": "d888e0d69d17d942416ddbcfb4dd119bfbc8164e53c150e608e6e85abe824a2f",
        "chainId": "930bf02ebc8a92c3e4be0f5db7778b6dd9f379f3f976b15f0fc8089fecfb1dc5",
        "externalIds": ["VGVzdA=="],
        "content": "RmFjdG8gQVBJ",
        "callbackUrl": "https://webhook.site/0a69fe86-7e36-445d-ba5f-9837f0efb92c",
        "timestamp": 1528251236497
    }
    

    This endpoint retrieves all kittens.

    HTTP Request

    POST https://api.facto.cloud/v1/chains/{chainId}/entries

    Query Parameters

    Parameter Required Description
    chainId yes The id of the chain to add the entry to.
    content yes Base64 encoding of the content.
    externalIds no Array of base64 encoded external ids
    callbackUrl no A callback url for a notification once the entry is confirmed in the Factom blockchain.

    Callback

    Once your entry is confirmed in a directory block in Factom we will trigger your callback URL.

    For example if your callback url is: https://example.com/callback

    We will send a GET request like https://example.com/callback/chainId=930bf02ebc8a92c3e4be0f5db7778b6dd9f379f3f976b15f0fc8089fecfb1dc5&entryHash=d888e0d69d17d942416ddbcfb4dd119bfbc8164e53c150e608e6e85abe824a2f

    If your callback responses with a 2xx status code. We will accept that as a successful callback. For any other response, we will consider that as a failure and will retry the callback every 30 minutes for up to a day.

    Scalability and Reliability

    We ensure that your entry gets into the Factom blockchain, even if the blockchain is stalled or down.

    To ensure scalability, requests that come in are load balanced across multiple Factom nodes in diffierent geographic locations.

    All requests that come in are stored in a database with automatic multi-region data replication, strong consistency guarantees and real transaction support.

    Credits

    Special thanks to Paul Bernier for his factomjs library. Used heavily in the implimentation of the Facto API.