block.html

---
title: Block
layout: default
---
<section>
  <a name="block-object" id="block-object"></a>
  <h1>Block</h1>
  <h3>Quick Access Via Virtual Block Token</h3>
  <p>To get you up and running quickly, we provide a virtual block token, which you can enable (and revoke), in the <a href="https://a.ninja.is/hacking">account settings page</a>. This block token will allow you to create arbitrary devices under your account without activating or claiming.</p>
  <p>Use your virtual block token exactly as you would a standard block token, i.e. pass it as an http header named X-Ninja-Token.</p>

  {% include block_activation.html %}

  <p><strong>cURL tip:</strong> JSON responses on the command line can be very hard to read. The simplest way is to get <a href="https://github.com/trentm/json">this excellent json script</a> and then add pipe to json <code>| json</code> at the end of your curl commands. Slightly more work to install but well worth the effort if you regularly work with restful APIs is the python utility <a href="https://github.com/jkbr/httpie">HTTPie</a>.</p>

  <table>
    <tbody>
      <tr>
        <th width='35%'>Resource</th>
        <th>Description</th>
      </tr>
      <tr>
        <td><a href="#block-get">GET block</a></td>
        <td>Fetch all claimed blocks.</td>
      </tr>
      <tr>
        <td><a href="#block-post">POST block</a></td>
        <td>Attempt to claim an unclaimed block.</td>
      </tr>
      <tr>
        <td><a href="#block-activate">GET block/:nodeId/activate</a></td>
        <td>Activate a block and return its token. This token should be used with all subsequent requests. Your nodeId should be a 12+ alphanumeric character identifier (no underscores), ideally a unique serial number.</td>
      </tr>

      <tr>
        <td><a href="#block-get-one">GET block/:nodeId</a></td>
        <td>Fetch a specific block's details.</td>
      </tr>
      <tr>
        <td><a href="#block-unpair">DELETE block/:nodeId</a></td>
        <td>Unpair a block.</td>
      </tr>

      <tr>
        <td><a href="#block-heartbeat">POST block/:nodeId/heartbeat</a></td>
        <td>[DEPRECATED] Send a heartbeat from this block.</td>
      </tr>
      <tr>
        <td><a href="#block-data">POST block/:nodeId/data</a></td>
        <td>Send a 'data' event from this block. Typically 'data' events will be instantly actioned, as opposed to heartbeats which may be queued.</td>
      </tr>
      <tr>
        <td><a href="#block-config">POST block/:nodeId/config</a></td>
        <td>Config events are intended to be meta information about a device, for example its IP address if it were an IP camera.</td>
      </tr>
      <tr>
        <td><a href="#block-commands">GET block/:nodeId/commands</a></td>
        <td>A block will receive commands from this endpoint.</td>
      </tr>
      <tr>
        <td><a href="#device-send-image">POST camera/:guid/snapshot</a></td>
        <td>Send an image that has been requested via a 'snapshot' command.</td>
      </tr>
    </tbody>
  </table>


  <p>&nbsp;</p>
  <a name="block-get" id="block-get"></a>
  <h2>GET block</h2>
  <p>Returns all the blocks paired to an account.</p>
  <table>
    <tbody>
      <tr>
        <th colspan="2">Parameters</th>
      </tr>
      <tr>
        <td colspan="2"><em>none</em</td>
      </tr>
    </tbody>
  </table>
  <h4>Resource URL</h4>
<pre><code>https://api.ninja.is/rest/v0/block</code></pre>

  <h4>cURL Example</h4>
  <p>Fetch all of a user's blocks:</p>
<pre><code>curl -i https://api.ninja.is/rest/v0/block?user_access_token=YOUR_ACCESS_TOKEN</code></pre>

  <h4>Sample JSON response</h4>
<pre><code>{
    "result": 1,
    "error": null,
    "id": 0,
    "data": {
        "STEALTHYNODE01": {
            "date_created": 1354675751000,
            "last_active": 1354765031967,
            "short_name": "Ninja Block"
        },
        "STEALTHYNODE02": {
            "date_created": 1354672575000,
            "last_active": 1354741967799,
            "short_name": "Ninja Block"
        }
    }
}</code></pre>



  <p>&nbsp;</p>
  <a name="block-post" id="block-post"></a>
  <h2>POST block</h2>
  <p>Attempt to claim an unclaimed block.</p>
  <table>
    <tbody>
      <tr>
        <th colspan="2">Parameters</th>
      </tr>
      <tr>
        <td><strong>nodeid</strong><br /><em>string</em><br /><small>Required</small></td>
        <td>
          The ID of the block you are attempting to claim. This block must be currently awaiting activation. ID's have a minimum length of 12 characters and only include letters and numbers (no underscores).
          <br />
          <small>Example: "ASTEALTHYNODE01"</small>
        </td>
      </tr>
    </tbody>
  </table>
  <h4>Notes</h4>
  <ul>
    <li>Note that a result of 1 indicates the claim attempt was received successfully NOT that the claim was successful (this will change in v1 of the API). The first block requesting activation with a matching nodeid within 30 seconds will be given a token linking it to the user making this request. </li>
  </ul>
  <h4>Resource URL</h4>
<pre><code>https://api.ninja.is/rest/v0/block</code></pre>
  <h4>cURL Example</h4>
  <p>Attempt to claim block 123456789ABC on behalf of the user identified by their <a href="authentication.html">user access token</a></p>
<pre><code>curl -X 'POST' \
     -H 'Content-Type: application/json' \
     -d '{"nodeid":"123456789ABC"}' \
     -i https://api.ninja.is/rest/v0/block?user_access_token=YOUR_API_TOKEN </code></pre>

  <h4>Sample JSON response</h4>
<pre><code>{
  "result": 1,
  "error": null,
  "id": 0
}</code></pre>

  <p>&nbsp;</p>
  <a name="block-activate" id="block-activate"></a>
  <h2>GET block/:nodeId/activate</h2>
  <p>Activate a block and return its token. This token should be used with all subsequent requests. Your nodeId should be a 12+ alphanumeric character identifier (no underscores), ideally a unique serial number.</p>
  <table>
    <tbody>
      <tr>
        <th colspan="2">Parameters</th>
      </tr>
      <tr>
        <td colspan="2"><em>none</em</td>
      </tr>
    </tbody>
  </table>
  <h4>Notes</h4>
  <ul>
    <li><strong>nodeId</strong> should be a unique string at least 12 alphanumeric characters (no underscores) in length, ideally a hardware serial number accessible by the user.</li>
    <li>If authentication credentials are provided with the request, ie via an <code>access_token</code> or <code>user_access_token</code>, an activated block token will immediately be returned.</li>
    <li>If no authentication credentials are provided, a response will only be returned only after a user has successfully executed the <a href="#block-post">POST to claim a block</a>. In this case the request is a 'long GET', and thus if the response ends without a body, the request should be reinitialized.</li>
  </ul>
  <h4>Resource URL</h4>
<pre><code>https://api.ninja.is/rest/v0/block/:nodeId/activate</code></pre>
  <h4>cURL Example</h4>
  <p>Listen for activation from a the block with nodeId 123456789ABC:</p>
<pre><code>curl -i https://api.ninja.is/rest/v0/block/123456789ABC/activate</code></pre>
  <h4>Sample JSON response</h4>
<pre><code>{
  "token": "1c0c8929-3318-411d-96e0-36fb7872ea5c"
}</code></pre>

  <p>&nbsp;</p>
  <a name="block-get-one" id="block-get-one"></a>
  <h2>GET block/:nodeId</h2>
  <p>Returns data about the specified block.</p>
  <table>
    <tbody>
      <tr>
        <th colspan="2">Parameters</th>
      </tr>
      <tr>
        <td colspan="2"><em>none</em</td>
      </tr>
    </tbody>
  </table>
  <h4>Resource URL</h4>
<pre><code>https://api.ninja.is/rest/v0/block/:nodeId</code></pre>

  <h4>cURL Example</h4>
  <p>Fetch one block's details:</p>
<pre><code>curl -i https://api.ninja.is/rest/v0/block/STEALTHYNODE02?user_access_token=YOUR_ACCESS_TOKEN</code></pre>

  <h4>Sample JSON response</h4>
<pre><code>{
    "result": 1,
    "error": null,
    "id": 0,
    "data": {
        "date_created": 1354672575000,
        "last_active": 1354741967799,
        "short_name": "Ninja Block"
    }
}</code></pre>


  <p>&nbsp;</p>
  <a name="block-unpair" id="block-unpair"></a>
  <h2>DELETE block/:nodeId</h2>
  <p>Unpair a block.</p>
  <table>
    <tbody>
      <tr>
        <th colspan="2">Parameters</th>
      </tr>
      <tr>
        <td colspan="2"><em>none</em</td>
      </tr>
    </tbody>
  </table>
  <h4>Notes</h4>
  <ul>
    <li>At the time of writing the block must be restarted to complete the unpairing process. In future this will not be necessary.</li>
  </ul>
  <h4>Resource URL</h4>
<pre><code>https://api.ninja.is/rest/v0/block/:nodeId</code></pre>

  <h4>cURL Example</h4>
  <p>Unpair the block 'STEALTHYNODE02':</p>
<pre><code>curl -X 'DELETE' \
     -i https://api.ninja.is/rest/v0/block/STEALTHYNODE02?user_access_token=YOUR_ACCESS_TOKEN</code></pre>

  <h4>Sample JSON response</h4>
<pre><code>{
    "result": 1,
    "error": null,
    "id": 0
}</code></pre>

  <p>&nbsp;</p>
  <a name="block-heartbeat" id="block-heartbeat"></a>
  <h2>POST block/:nodeId/heartbeat</h2>
  <h3><em>DEPRECATED - use <a href="#block-data">Data</a> instead</em></h3>
  <p>Send a heartbeat from this block.<br /><strong>Important</strong>: the request body takes the form of an <strong>array of objects</strong>, whose parameters are outlined below.</p>
  <p>Heartbeat events are intended to be values to be analyzed in due course. For example, a temperature reading should be part of a 'heartbeat' event, whereas a button press should be a <a href="#block-data">'data'</a> event.</p>
  <table>
    <tbody>
      <tr>
        <th colspan="2">Each Array Element Parameters</th>
      </tr>
      <tr>
        <td><strong>G</strong><br /><em>string</em><br /><small>Required</small></td>
        <td>
          The port/channel number the device is located on.
          <br />
          <small>Example: 0</small>
        </td>
      </tr>
      <tr>
        <td><strong>V</strong><br /><em>number</em><br /><small>Required</small></td>
        <td>
          The Vendor ID of the device.
          <br />
          <small>Example: "0"</small>
        </td>
      </tr>
      <tr>
        <td><strong>D</strong><br /><em>number</em><br /><small>Required</small></td>
        <td>
          The device ID.
          <br />
          <small>Example: 11</small>
        </td>
      </tr>
      <tr>
        <td><strong>DA</strong><br /><em>string</em><br /><small>Required</small></td>
        <td>
          The data value that this device is reporting.
          <br />
          <small>Example: "-1"</small>
        </td>
      </tr>
    </tbody>
  </table>
  <h4>Notes</h4>
  <ul>
    <li><strong>X-Ninja-Token</strong> is required in the headers of this request, and corresponds to the token acquired via the <a href="#block-activate">GET block/:nodeId/activate</a> route.</li>
  </ul>
  <h4>Resource URL</h4>
<pre><code>https://api.ninja.is/rest/v0/block/:nodeId/heartbeat</code></pre>
  <h4>cURL Example</h4>
  <p>Send a heartbeat from a temperature device 20 degrees C and report RGB LED device as purple. Note that heartbeats contain an array of device data, it must be submitted as an array even if there is only a single device.</a></p>
<pre><code>curl -X 'POST' \
     -H 'X-Ninja-Token: YOUR_BLOCK_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '[{"G":0,"V":0,"D":9,"DA":"20"},{"G":0,"V":0,"D":1000,"DA":"FF00FF"}]' \
     -i https://api.ninja.is/rest/v0/block/123456789ABC/heartbeat </code></pre>
  <h4>Sample JSON response</h4>
<pre><code>{
  "result": 1,
  "error": null,
  "id": 0
}</code></pre>

  <p>&nbsp;</p>
  <a name="block-data" id="block-data"></a>
  <h2>POST block/:nodeId/data</h2>
  <p>Send a data event from this block.</p>
  <p>Data events are actioned immediately. You can POST a single data event object or an array of objects. Note that omiting the timestamp attibute will result in the server timestamping the event on receipt.</p>
  <table>
    <tbody>
      <tr>
        <th colspan="2">Parameters</th>
      </tr>
      <tr>
        <td><strong>G</strong><br /><em>string</em><br /><small>Required</small></td>
        <td>
          The port/channel the device is located on.
          <br />
          <small>Example: 0</small>
        </td>
      </tr>
      <tr>
        <td><strong>V</strong><br /><em>number</em><br /><small>Required</small></td>
        <td>
          The Vendor ID of the device.
          <br />
          <small>Example: "0"</small>
        </td>
      </tr>
      <tr>
        <td><strong>D</strong><br /><em>number</em><br /><small>Required</small></td>
        <td>
          The device ID.
          <br />
          <small>Example: 11</small>
        </td>
      </tr>
      <tr>
        <td><strong>DA</strong><br /><em>string</em><br /><small>Required</small></td>
        <td>
          The data value that this device is reporting.
          <br />
          <small>Example: "-1"</small>
        </td>
      </tr>
      <tr>
        <td><strong>TIMESTAMP</strong><br /><em>int (timestamp)</em><br /><small>Optional</small></td>
        <td>
          The time of the event in <a href="http://www.epochconverter.com/">Unix or Epoch time</a>.
          <br />
          <small>Example: "1356920901"</small>
        </td>
      </tr>

    </tbody>
  </table>
  <h4>Notes</h4>
  <ul>
    <li>This endpoint will also accept an object or an array of objects to send multiple datapoints in one request.</li>
    <li><strong>X-Ninja-Token</strong> is required in the headers of this request, and corresponds to the token acquired via the <a href="#block-activate">GET block/:nodeId/activate</a> route.</li>
  </ul>
  <h4>Resource URL</h4>
<pre><code>https://api.ninja.is/rest/v0/block/:nodeId/data</code></pre>
  <p>Set the temperature to 20 degrees C and report RGB LED device as purple.</a></p>
<pre><code>curl -X 'POST' \
     -H 'X-Ninja-Token: YOUR_BLOCK_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '[{"G":0,"V":0,"D":9,"DA":"20"},{"G":0,"V":0,"D":1000,"DA":"FF00FF"}]' \
     -i https://api.ninja.is/rest/v0/block/123456789ABC/data </code></pre>
  <h4>Sample JSON response</h4>
<pre><code>{
  "result": 1,
  "error": null,
  "id": 0
}</code></pre>


<p>&nbsp;</p>
  <a name="block-config" id="block-config"></a>
  <h2>POST block/:nodeId/config</h2>
  <p>Send a config event from this block.</p>
  <p>Config events are intended to be meta information about a device, for example its IP address if it were an IP camera, whether it's plugged in or not, etc.</p>
  <table>
    <tbody>
      <tr>
        <th colspan="2">Parameters</th>
      </tr>
      <tr>
        <td><strong>G</strong><br /><em>string</em><br /><small>Required</small></td>
        <td>
          The port/channel the device is located on.
          <br />
          <small>Example: 0</small>
        </td>
      </tr>
      <tr>
        <td><strong>V</strong><br /><em>number</em><br /><small>Required</small></td>
        <td>
          The Vendor ID of the device.
          <br />
          <small>Example: "0"</small>
        </td>
      </tr>
      <tr>
        <td><strong>D</strong><br /><em>number</em><br /><small>Required</small></td>
        <td>
          The device ID.
          <br />
          <small>Example: 11</small>
        </td>
      </tr>
      <tr>
        <td><strong>type</strong><br /><em>string</em><br /><small>Required</small></td>
        <td>
          The type of the config event. Currently in our dashboard we support "UNPLUG" & "PLUGIN", however this can be anything.
          <br />
          <small>Example: "PLUGIN"</small>
        </td>
      </tr>
    </tbody>
  </table>
  <h4>Notes</h4>
  <ul>
    <li>This endpoint will also accept an array of objects to send multiple config events in one request.</li>
    <li><strong>X-Ninja-Token</strong> is required in the headers of this request, and corresponds to the token acquired via the <a href="#block-activate">GET block/:nodeId/activate</a> route.</li>
  </ul>
  <h4>Resource URL</h4>
<pre><code>https://api.ninja.is/rest/v0/block/:nodeId/config</code></pre>
  <h4>cURL Example</h4>
<pre><code>curl -X 'POST' \
     -H 'X-Ninja-Token: YOUR_BLOCK_TOKEN' \
     -H 'Content-Type: application/json' \
     -d '{"G":0,"V":0,"D":5,"type":"UNPLUG"}' \
     -i https://api.ninja.is/rest/v0/block/123456789ABC/config </code></pre>

  <h4>Sample JSON response</h4>
<pre><code>{
  "result": 1,
  "error": null,
  "id": 0
}</code></pre>



  <p>&nbsp;</p>
  <a name="block-commands" id="block-commands"></a>
  <h2>GET block/:nodeId/commands</h2>
  <p>A block will receive commands from this endpoint. See notes for the behaviour of this endpoint.</p>
  <table>
    <tbody>
      <tr>
        <th colspan="2">Parameters</th>
      </tr>
      <tr>
        <td colspan="2"><em>none</em></td>
      </tr>
    </tbody>
  </table>
  <h4>Notes</h4>
  <ul>
    <li><strong>X-Ninja-Token</strong> is required in the headers of this request, and corresponds to the token acquired via the <a href="#block-activate">GET block/:nodeId/activate</a> route.</li>
    <li><strong>nodeId</strong> must be at least 12 characters in length.</li>
    <li>The request will end after each command is received, or after approximately 30 seconds. Requests should be reinitialized in these instances.</li>
  </ul>
  <h4>Resource URL</h4>
<pre><code>https://api.ninja.is/rest/v0/block/:nodeId/commands</code></pre>
  <h4>cURL Example</h4>
  <p>Await a command sent to this block:</p>
<pre><code>curl -H 'X-Ninja-Token: YOUR_BLOCK_TOKEN' \
     -H 'Content-Type: application/json' \
     -i https://api.ninja.is/rest/v0/block/123456789ABC/commands</code></pre>
  <h4>Sample JSON response</h4>
<pre><code>{"DEVICE":[{"G":"0","V":0,"D":1000,"DA":"FFFFFF"}]}</code></pre>

  <p>&nbsp;</p>
  <a name="device-send-image" id="device-send-image"></a>
  <h2>POST camera/:guid/snapshot</h2>
  <p>Send an image that has been requested via a 'snapshot' command.</p>
  <table>
    <tbody>
      <tr>
        <th colspan="2">Parameters</th>
      </tr>
      <tr>
        <td colspan="2"><em>none</em></td>
      </tr>
    </tbody>
  </table>
  <h4>Notes</h4>
  <ul>
    <li><strong>X-Ninja-Token</strong> is required in the headers of this request, and corresponds to the token acquired via the <a href="#block-activate">GET block/:nodeId/activate</a> route.</li>
    <li>The request body should contain the binary of the image, with the correct mime type in the headers</li>
    <li>This request should only be made when a 'DA' value of 1 is received by the device.</li>
  </ul>
  <h4>Resource URL</h4>
  <pre><code>https://stream.ninja.is/rest/v0/camera/:guid/snapshot</code></pre>
  <strong>Note: this call is to stream.ninja.is.</strong>
</section>