CINXE.COM

<!doctype html> <html> <head> <meta charset="utf-8"> <meta content="IE=edge,chrome=1" http-equiv="X-UA-Compatible"> <meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1"> <title>Adafruit IO API Reference</title> <link href="images/favicon/favicon.ico" rel="icon" type="image/ico" /> <link rel="apple-touch-icon" sizes="180x180" href="images/favicon/apple-touch-icon.png" /> <link rel="icon" type="image/png" sizes="32x32" href="images/favicon/favicon-32x32.png"> <link rel="icon" type="image/png" sizes="16x16" href="images/favicon/favicon-16x16.png"> <link rel="manifest" href="images/favicon/site.webmanifest"> <link rel="mask-icon" href="images/favicon/safari-pinned-tab.svg" color="#00A7E9"> <meta name="msapplication-TileColor" content="#00A7E9"> <meta name="theme-color" content="#000000"> <style> .highlight table td { padding: 5px; } .highlight table pre { margin: 0; } .highlight .gh { color: #999999; } .highlight .sr { color: #f6aa11; } .highlight .go { color: #888888; } .highlight .gp { color: #555555; } .highlight .gs { } .highlight .gu { color: #aaaaaa; } .highlight .nb { color: #f6aa11; } .highlight .cm { color: #75715e; } .highlight .cp { color: #75715e; } .highlight .c1 { color: #75715e; } .highlight .cs { color: #75715e; } .highlight .c, .highlight .ch, .highlight .cd, .highlight .cpf { color: #75715e; } .highlight .err { color: #960050; } .highlight .gr { color: #960050; } .highlight .gt { color: #960050; } .highlight .gd { color: #49483e; } .highlight .gi { color: #49483e; } .highlight .ge { color: #49483e; } .highlight .kc { color: #66d9ef; } .highlight .kd { color: #66d9ef; } .highlight .kr { color: #66d9ef; } .highlight .no { color: #66d9ef; } .highlight .kt { color: #66d9ef; } .highlight .mf { color: #ae81ff; } .highlight .mh { color: #ae81ff; } .highlight .il { color: #ae81ff; } .highlight .mi { color: #ae81ff; } .highlight .mo { color: #ae81ff; } .highlight .m, .highlight .mb, .highlight .mx { color: #ae81ff; } .highlight .sc { color: #ae81ff; } .highlight .se { color: #ae81ff; } .highlight .ss { color: #ae81ff; } .highlight .sd { color: #e6db74; } .highlight .s2 { color: #e6db74; } .highlight .sb { color: #e6db74; } .highlight .sh { color: #e6db74; } .highlight .si { color: #e6db74; } .highlight .sx { color: #e6db74; } .highlight .s1 { color: #e6db74; } .highlight .s, .highlight .sa, .highlight .dl { color: #e6db74; } .highlight .na { color: #a6e22e; } .highlight .nc { color: #a6e22e; } .highlight .nd { color: #a6e22e; } .highlight .ne { color: #a6e22e; } .highlight .nf, .highlight .fm { color: #a6e22e; } .highlight .vc { color: #ffffff; background-color: #272822; } .highlight .nn { color: #ffffff; background-color: #272822; } .highlight .nl { color: #ffffff; background-color: #272822; } .highlight .ni { color: #ffffff; background-color: #272822; } .highlight .bp { color: #ffffff; background-color: #272822; } .highlight .vg { color: #ffffff; background-color: #272822; } .highlight .vi { color: #ffffff; background-color: #272822; } .highlight .nv, .highlight .vm { color: #ffffff; background-color: #272822; } .highlight .w { color: #ffffff; background-color: #272822; } .highlight { color: #ffffff; background-color: #272822; } .highlight .n, .highlight .py, .highlight .nx { color: #ffffff; background-color: #272822; } .highlight .ow { color: #f92672; } .highlight .nt { color: #f92672; } .highlight .k, .highlight .kv { color: #f92672; } .highlight .kn { color: #f92672; } .highlight .kp { color: #f92672; } .highlight .o { color: #f92672; } </style> <link href="stylesheets/screen.css" rel="stylesheet" media="screen" /> <link href="stylesheets/print.css" rel="stylesheet" media="print" /> <script src="javascripts/all.js"></script> </head> <body class="index" data-languages="["shell","cpp","python","python","ruby"]"> <a href="#" id="nav-button"> NAV <img src="images/navbar.png" alt="" /> </a> <div class="toc-wrapper"> <img src="images/logo.png" class="logo" alt="" /> <div class="lang-selector"> <a href="#" data-language-name="shell">CURL</a> <a href="#" data-language-name="cpp">Arduino</a> <a href="#" data-language-name="python">Python</a> <a href="#" data-language-name="python">Circuitpython</a> <a href="#" data-language-name="ruby">Ruby</a> </div> <div class="search"> <input type="text" class="search" id="input-search" placeholder="Search"> </div> <ul class="search-results"></ul> <ul id="toc" class="toc-list-h1"> <li class="on-screen"> <a href="#adafruit-io-http-api" class="toc-h1 toc-link" data-title="Adafruit IO HTTP API"> Adafruit IO HTTP API <svg width="18" height="18" viewBox="0 0 1792 1792" xmlns="http://www.w3.org/2000/svg"><path d="M1171 960q0 13-10 23l-466 466q-10 10-23 10t-23-10l-50-50q-10-10-10-23t10-23l393-393-393-393q-10-10-10-23t10-23l50-50q10-10 23-10t23 10l466 466q10 10 10 23z"/></svg>  </a> <ul class="toc-list-h2"> <li> <a href="#about-the-api-docs" class="toc-h2 toc-link" data-title="About the API Docs">About the API Docs</a> </li> </ul> </li> <li class="on-screen"> <a href="#authentication" class="toc-h1 toc-link" data-title="Authentication"> Authentication <svg width="18" height="18" viewBox="0 0 1792 1792" xmlns="http://www.w3.org/2000/svg"><path d="M1171 960q0 13-10 23l-466 466q-10 10-23 10t-23-10l-50-50q-10-10-10-23t10-23l393-393-393-393q-10-10-10-23t10-23l50-50q10-10 23-10t23 10l466 466q10 10 10 23z"/></svg>  </a> <ul class="toc-list-h2"> <li> <a href="#including-an-adafruit-io-key" class="toc-h2 toc-link" data-title="Including an Adafruit IO Key">Including an Adafruit IO Key</a> </li> </ul> </li> <li class="on-screen"> <a href="#client-libraries" class="toc-h1 toc-link" data-title="Client Libraries"> Client Libraries </a> </li> <li class="on-screen"> <a href="#rate-limiting" class="toc-h1 toc-link" data-title="Rate Limiting"> Rate Limiting </a> </li> <li class="on-screen"> <a href="#pagination" class="toc-h1 toc-link" data-title="Pagination"> Pagination <svg width="18" height="18" viewBox="0 0 1792 1792" xmlns="http://www.w3.org/2000/svg"><path d="M1171 960q0 13-10 23l-466 466q-10 10-23 10t-23-10l-50-50q-10-10-10-23t10-23l393-393-393-393q-10-10-10-23t10-23l50-50q10-10 23-10t23 10l466 466q10 10 10 23z"/></svg>  </a> <ul class="toc-list-h2"> <li> <a href="#pagination-headers" class="toc-h2 toc-link" data-title="Pagination Headers">Pagination Headers</a> </li> <li> <a href="#the-link-header" class="toc-h2 toc-link" data-title="The Link Header">The Link Header</a> </li> </ul> </li> <li class="on-screen"> <a href="#data" class="toc-h1 toc-link" data-title="Data"> Data <svg width="18" height="18" viewBox="0 0 1792 1792" xmlns="http://www.w3.org/2000/svg"><path d="M1171 960q0 13-10 23l-466 466q-10 10-23 10t-23-10l-50-50q-10-10-10-23t10-23l393-393-393-393q-10-10-10-23t10-23l50-50q10-10 23-10t23 10l466 466q10 10 10 23z"/></svg>  </a> <ul class="toc-list-h2"> <li> <a href="#create-data" class="toc-h2 toc-link" data-title="Create Data">Create Data</a> </li> <li> <a href="#get-feed-data" class="toc-h2 toc-link" data-title="Get Feed Data">Get Feed Data</a> </li> <li> <a href="#chart-feed-data" class="toc-h2 toc-link" data-title="Chart Feed Data">Chart Feed Data</a> </li> <li> <a href="#create-multiple-data-records" class="toc-h2 toc-link" data-title="Create Multiple Data Records">Create Multiple Data Records</a> </li> <li> <a href="#get-previous-data" class="toc-h2 toc-link" data-title="Get Previous Data">Get Previous Data</a> </li> <li> <a href="#get-next-data" class="toc-h2 toc-link" data-title="Get Next Data">Get Next Data</a> </li> <li> <a href="#get-last-data" class="toc-h2 toc-link" data-title="Get Last Data">Get Last Data</a> </li> <li> <a href="#get-first-data" class="toc-h2 toc-link" data-title="Get First Data">Get First Data</a> </li> <li> <a href="#get-most-recent-data" class="toc-h2 toc-link" data-title="Get Most Recent Data">Get Most Recent Data</a> </li> <li> <a href="#get-data-point" class="toc-h2 toc-link" data-title="Get Data Point">Get Data Point</a> </li> <li> <a href="#update-data-point" class="toc-h2 toc-link" data-title="Update Data Point">Update Data Point</a> </li> <li> <a href="#delete-data-point" class="toc-h2 toc-link" data-title="Delete Data Point">Delete Data Point</a> </li> <li> <a href="#create-group-data" class="toc-h2 toc-link" data-title="Create Group Data">Create Group Data</a> </li> <li> <a href="#get-data-for-group-39-s-feed" class="toc-h2 toc-link" data-title="Get Data for Group's Feed">Get Data for Group's Feed</a> </li> <li> <a href="#create-data-in-a-group-39-s-feed" class="toc-h2 toc-link" data-title="Create Data in a Group's Feed">Create Data in a Group's Feed</a> </li> <li> <a href="#create-data-in-a-group-39-s-feed-2" class="toc-h2 toc-link" data-title="Create Data in a Group's Feed">Create Data in a Group's Feed</a> </li> </ul> </li> <li class="on-screen"> <a href="#feeds" class="toc-h1 toc-link" data-title="Feeds"> Feeds <svg width="18" height="18" viewBox="0 0 1792 1792" xmlns="http://www.w3.org/2000/svg"><path d="M1171 960q0 13-10 23l-466 466q-10 10-23 10t-23-10l-50-50q-10-10-10-23t10-23l393-393-393-393q-10-10-10-23t10-23l50-50q10-10 23-10t23 10l466 466q10 10 10 23z"/></svg>  </a> <ul class="toc-list-h2"> <li> <a href="#all-feeds" class="toc-h2 toc-link" data-title="All Feeds">All Feeds</a> </li> <li> <a href="#create-feed" class="toc-h2 toc-link" data-title="Create Feed">Create Feed</a> </li> <li> <a href="#get-feed" class="toc-h2 toc-link" data-title="Get Feed">Get Feed</a> </li> <li> <a href="#update-feed" class="toc-h2 toc-link" data-title="Update Feed">Update Feed</a> </li> <li> <a href="#delete-feed" class="toc-h2 toc-link" data-title="Delete Feed">Delete Feed</a> </li> <li> <a href="#get-feed-2" class="toc-h2 toc-link" data-title="Get Feed">Get Feed</a> </li> </ul> </li> <li class="on-screen"> <a href="#groups" class="toc-h1 toc-link" data-title="Groups"> Groups <svg width="18" height="18" viewBox="0 0 1792 1792" xmlns="http://www.w3.org/2000/svg"><path d="M1171 960q0 13-10 23l-466 466q-10 10-23 10t-23-10l-50-50q-10-10-10-23t10-23l393-393-393-393q-10-10-10-23t10-23l50-50q10-10 23-10t23 10l466 466q10 10 10 23z"/></svg>  </a> <ul class="toc-list-h2"> <li> <a href="#get-all-groups" class="toc-h2 toc-link" data-title="Get All Groups">Get All Groups</a> </li> <li> <a href="#create-group" class="toc-h2 toc-link" data-title="Create Group">Create Group</a> </li> <li> <a href="#get-group" class="toc-h2 toc-link" data-title="Get Group">Get Group</a> </li> <li> <a href="#update-group" class="toc-h2 toc-link" data-title="Update Group">Update Group</a> </li> <li> <a href="#delete-group" class="toc-h2 toc-link" data-title="Delete Group">Delete Group</a> </li> <li> <a href="#create-feed-in-a-group" class="toc-h2 toc-link" data-title="Create Feed in a Group">Create Feed in a Group</a> </li> <li> <a href="#add-feed-to-group" class="toc-h2 toc-link" data-title="Add Feed to Group">Add Feed to Group</a> </li> <li> <a href="#remove-feed-from-group" class="toc-h2 toc-link" data-title="Remove Feed from Group">Remove Feed from Group</a> </li> <li> <a href="#get-group-feeds" class="toc-h2 toc-link" data-title="Get Group Feeds">Get Group Feeds</a> </li> </ul> </li> <li class="on-screen"> <a href="#webhooks" class="toc-h1 toc-link" data-title="Webhooks"> Webhooks <svg width="18" height="18" viewBox="0 0 1792 1792" xmlns="http://www.w3.org/2000/svg"><path d="M1171 960q0 13-10 23l-466 466q-10 10-23 10t-23-10l-50-50q-10-10-10-23t10-23l393-393-393-393q-10-10-10-23t10-23l50-50q10-10 23-10t23 10l466 466q10 10 10 23z"/></svg>  </a> <ul class="toc-list-h2"> <li> <a href="#send-data-via-webhook" class="toc-h2 toc-link" data-title="Send Data via Webhook">Send Data via Webhook</a> </li> <li> <a href="#send-arbitrary-data-via-webhook" class="toc-h2 toc-link" data-title="Send Arbitrary Data via Webhook">Send Arbitrary Data via Webhook</a> </li> <li> <a href="#send-notification-via-webhook" class="toc-h2 toc-link" data-title="Send Notification via Webhook">Send Notification via Webhook</a> </li> </ul> </li> <li class="on-screen"> <a href="#actions" class="toc-h1 toc-link" data-title="Actions"> Actions <svg width="18" height="18" viewBox="0 0 1792 1792" xmlns="http://www.w3.org/2000/svg"><path d="M1171 960q0 13-10 23l-466 466q-10 10-23 10t-23-10l-50-50q-10-10-10-23t10-23l393-393-393-393q-10-10-10-23t10-23l50-50q10-10 23-10t23 10l466 466q10 10 10 23z"/></svg>  </a> <ul class="toc-list-h2"> <li> <a href="#get-all-actions" class="toc-h2 toc-link" data-title="Get All Actions">Get All Actions</a> </li> <li> <a href="#create-action" class="toc-h2 toc-link" data-title="Create Action">Create Action</a> </li> <li> <a href="#return-action" class="toc-h2 toc-link" data-title="Return Action">Return Action</a> </li> <li> <a href="#replace-action" class="toc-h2 toc-link" data-title="Replace Action">Replace Action</a> </li> <li> <a href="#delete-action" class="toc-h2 toc-link" data-title="Delete Action">Delete Action</a> </li> </ul> </li> <li class="on-screen"> <a href="#activities" class="toc-h1 toc-link" data-title="Activities"> Activities <svg width="18" height="18" viewBox="0 0 1792 1792" xmlns="http://www.w3.org/2000/svg"><path d="M1171 960q0 13-10 23l-466 466q-10 10-23 10t-23-10l-50-50q-10-10-10-23t10-23l393-393-393-393q-10-10-10-23t10-23l50-50q10-10 23-10t23 10l466 466q10 10 10 23z"/></svg>  </a> <ul class="toc-list-h2"> <li> <a href="#all-activities" class="toc-h2 toc-link" data-title="All Activities">All Activities</a> </li> <li> <a href="#get-activities-by-type" class="toc-h2 toc-link" data-title="Get Activities by Type">Get Activities by Type</a> </li> </ul> </li> <li class="on-screen"> <a href="#blocks" class="toc-h1 toc-link" data-title="Blocks"> Blocks <svg width="18" height="18" viewBox="0 0 1792 1792" xmlns="http://www.w3.org/2000/svg"><path d="M1171 960q0 13-10 23l-466 466q-10 10-23 10t-23-10l-50-50q-10-10-10-23t10-23l393-393-393-393q-10-10-10-23t10-23l50-50q10-10 23-10t23 10l466 466q10 10 10 23z"/></svg>  </a> <ul class="toc-list-h2"> <li> <a href="#all-blocks" class="toc-h2 toc-link" data-title="All blocks">All blocks</a> </li> <li> <a href="#create-a-block" class="toc-h2 toc-link" data-title="Create a Block">Create a Block</a> </li> <li> <a href="#returns-block" class="toc-h2 toc-link" data-title="Returns Block">Returns Block</a> </li> <li> <a href="#replace-a-block" class="toc-h2 toc-link" data-title="Replace A Block">Replace A Block</a> </li> <li> <a href="#delete-a-block" class="toc-h2 toc-link" data-title="Delete a Block">Delete a Block</a> </li> </ul> </li> <li class="on-screen"> <a href="#dashboards" class="toc-h1 toc-link" data-title="Dashboards"> Dashboards <svg width="18" height="18" viewBox="0 0 1792 1792" xmlns="http://www.w3.org/2000/svg"><path d="M1171 960q0 13-10 23l-466 466q-10 10-23 10t-23-10l-50-50q-10-10-10-23t10-23l393-393-393-393q-10-10-10-23t10-23l50-50q10-10 23-10t23 10l466 466q10 10 10 23z"/></svg>  </a> <ul class="toc-list-h2"> <li> <a href="#all-dashboards" class="toc-h2 toc-link" data-title="All dashboards">All dashboards</a> </li> <li> <a href="#create-a-dashboard" class="toc-h2 toc-link" data-title="Create a Dashboard">Create a Dashboard</a> </li> <li> <a href="#return-dashboard" class="toc-h2 toc-link" data-title="Return Dashboard">Return Dashboard</a> </li> <li> <a href="#replace-a-dashboard" class="toc-h2 toc-link" data-title="Replace a Dashboard">Replace a Dashboard</a> </li> <li> <a href="#delete-a-dashboard" class="toc-h2 toc-link" data-title="Delete a Dashboard">Delete a Dashboard</a> </li> </ul> </li> <li class="on-screen"> <a href="#permissions" class="toc-h1 toc-link" data-title="Permissions"> Permissions <svg width="18" height="18" viewBox="0 0 1792 1792" xmlns="http://www.w3.org/2000/svg"><path d="M1171 960q0 13-10 23l-466 466q-10 10-23 10t-23-10l-50-50q-10-10-10-23t10-23l393-393-393-393q-10-10-10-23t10-23l50-50q10-10 23-10t23 10l466 466q10 10 10 23z"/></svg>  </a> <ul class="toc-list-h2"> <li> <a href="#get-all-permissions" class="toc-h2 toc-link" data-title="Get All Permissions">Get All Permissions</a> </li> <li> <a href="#create-permission" class="toc-h2 toc-link" data-title="Create Permission">Create Permission</a> </li> <li> <a href="#returns-permission" class="toc-h2 toc-link" data-title="Returns Permission">Returns Permission</a> </li> <li> <a href="#replace-permission" class="toc-h2 toc-link" data-title="Replace Permission">Replace Permission</a> </li> <li> <a href="#delete-permission" class="toc-h2 toc-link" data-title="Delete Permission">Delete Permission</a> </li> </ul> </li> <li class="on-screen"> <a href="#users" class="toc-h1 toc-link" data-title="Users"> Users <svg width="18" height="18" viewBox="0 0 1792 1792" xmlns="http://www.w3.org/2000/svg"><path d="M1171 960q0 13-10 23l-466 466q-10 10-23 10t-23-10l-50-50q-10-10-10-23t10-23l393-393-393-393q-10-10-10-23t10-23l50-50q10-10 23-10t23 10l466 466q10 10 10 23z"/></svg>  </a> <ul class="toc-list-h2"> <li> <a href="#get-user-info" class="toc-h2 toc-link" data-title="Get User Info">Get User Info</a> </li> <li> <a href="#get-detailed-user-info" class="toc-h2 toc-link" data-title="Get Detailed User Info">Get Detailed User Info</a> </li> </ul> </li> <li class="on-screen"> <a href="#tokens" class="toc-h1 toc-link" data-title="Tokens"> Tokens <svg width="18" height="18" viewBox="0 0 1792 1792" xmlns="http://www.w3.org/2000/svg"><path d="M1171 960q0 13-10 23l-466 466q-10 10-23 10t-23-10l-50-50q-10-10-10-23t10-23l393-393-393-393q-10-10-10-23t10-23l50-50q10-10 23-10t23 10l466 466q10 10 10 23z"/></svg>  </a> <ul class="toc-list-h2"> <li> <a href="#get-all-tokens" class="toc-h2 toc-link" data-title="Get All Tokens">Get All Tokens</a> </li> <li> <a href="#create-token" class="toc-h2 toc-link" data-title="Create Token">Create Token</a> </li> <li> <a href="#returns-token" class="toc-h2 toc-link" data-title="Returns Token">Returns Token</a> </li> <li> <a href="#delete-token" class="toc-h2 toc-link" data-title="Delete Token">Delete Token</a> </li> </ul> </li> <li class="on-screen"> <a href="#services" class="toc-h1 toc-link" data-title="Services"> Services <svg width="18" height="18" viewBox="0 0 1792 1792" xmlns="http://www.w3.org/2000/svg"><path d="M1171 960q0 13-10 23l-466 466q-10 10-23 10t-23-10l-50-50q-10-10-10-23t10-23l393-393-393-393q-10-10-10-23t10-23l50-50q10-10 23-10t23 10l466 466q10 10 10 23z"/></svg>  </a> <ul class="toc-list-h2"> <li> <a href="#time" class="toc-h2 toc-link" data-title="Time">Time</a> </li> <li> <a href="#randomizer" class="toc-h2 toc-link" data-title="Randomizer">Randomizer</a> </li> <li> <a href="#weather" class="toc-h2 toc-link" data-title="Weather">Weather</a> </li> </ul> </li> <li class="on-screen"> <a href="#errors" class="toc-h1 toc-link" data-title="Errors"> Errors </a> </li> <li> <a href="mqtt.html" class="toc-h1 toc-link append"> Adafruit IO MQTT API </a> </li> <li> <a href="cookbook.html" class="toc-h1 toc-link append"> API Cookbook </a> </li> </ul> <ul class="toc-footer"> <li><a href='http://io.adafruit.com'>Adafruit IO</a></li> <li><a href='https://io.adafruit.com/blog'>Adafruit IO News</a></li> <li><a href='https://io.adafruit.com/plus'>Adafruit IO Plus</a></li> <li><a href='https://io.adafruit.com/terms'>Adafruit IO ToS</a></li> <li><a href='https://io.adafruit.com/feedback'>Submit Feedback</a></li> </ul> </div> <div class="page-wrapper"> <div class="dark-box"></div> <div class="content"> <h1 id='adafruit-io-http-api'>Adafruit IO HTTP API</h1> The Adafruit IO HTTP API provides access to your Adafruit IO data from any programming language or hardware environment that can speak HTTP. The easiest way to get started is with an <a href="https://learn.adafruit.com/series/adafruit-io-basics">Adafruit Learning Guide</a> and a simple Internet of Things capable device like the <a href="https://www.adafruit.com/product/2821">Feather Huzzah</a> or a more complicated one like the <a href="https://www.adafruit.com/product/4116">PyPortal</a>. <h2 id='about-the-api-docs'>About the API Docs</h2> This API documentation is hosted on GitHub Pages and is available <a href="https://github.com/adafruit/Adafruit_IO_Documentation">on GitHub</a>. Spotted something incorrect or broken? <a href="https://github.com/adafruit/Adafruit_IO_Documentation/issues/new">Click here to file an issue on the repository</a> For questions or comments <a href="https://io.adafruit.com/feedback">visit the Adafruit IO Feedback page</a> or the <a href="https://discord.gg/adafruit">#help-with-adafruit-io channel on the Adafruit Discord server</a>. <h1 id='authentication'>Authentication</h1> Your Adafruit IO Key is used to restrict or grant access to your data. The key is unique and covers every use of the Adafruit IO API for your account. You can access your key on any IO page by clicking on the golden key icon: <img src="images/authentication/aio-key-dashboard-link.png" alt="" /> Or by clicking on the "View Adafruit IO Key" link in the small screen drop-down menu while you're visiting Adafruit IO. <img src="images/authentication/aio-key-sidebar-link.png" alt="" /> Now you can copy the key directly from the information form that pops up, or copy one of the code samples that includes your key and username together. <img src="images/authentication/aio-key-modal.png" alt="" /> <h2 id='including-an-adafruit-io-key'>Including an Adafruit IO Key</h2><div class="highlight"><pre class="highlight shell tab-shell"><code>curl -H "X-AIO-Key: b780002b85d6411ca0ad9f9c60195f72" \ https://io.adafruit.com/api/v2/test_username/feeds # or curl "https://io.adafruit.com/api/v2/test_username/feeds?x-aio-key=b780002b85d6411ca0ad9f9c60195f72" </code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code>require 'adafruit/io' username = "test_username" api_key = "b780002b85d6411ca0ad9f9c60195f72" api = Adafruit::IO::Client.new key: api_key, username: username </code></pre></div> When making HTTP requests to Adafruit IO, you can include the API key as a query parameter named <code>x-aio-key</code> or as a request header named <code>X-AIO-Key</code>. In both cases, "X-AIO-Key" is case insensitive. NOTE: if you regenerate your AIO key, your old key will be immediately invalidated, so you'll have to replace it in any scripts or sketches where it is in use. NOTE: it is a best practice to avoid including your API key in the URL as a query parameter. Some situations may require this, but try to avoid it if you can. <h1 id='client-libraries'>Client Libraries</h1> We have lots of client libraries to help you get started with your project: <ul> <li><a href="https://github.com/adafruit/Adafruit_IO_Arduino">Arduino C++</a></li> <li><a href="https://github.com/adafruit/Adafruit_CircuitPython_AdafruitIO/">CircuitPython</a></li> <li><a href="https://github.com/adafruit/Adafruit_IO_Python">Python</a></li> <li><a href="https://github.com/adafruit/io-client-ruby">Ruby</a></li> </ul> Note: The following two libraries use V1 of the Adafruit API which have been <a href="https://io.adafruit.com/api/docs/">deprecated</a>. <ul> <li><a href="https://github.com/adafruit/adafruit-io-node-client">Node.js</a></li> <li><a href="https://github.com/adafruit/io-client-go">Go</a></li> </ul> They're all open source, so if they don't already do what you want, you can fork them and add any feature you'd like. <h1 id='rate-limiting'>Rate Limiting</h1> Adafruit IO imposes a rate limit on all data modification APIs to prevent excessive load on the service. If a user performs too many data create, update, or delete actions in a short period of time then the system will start rejecting requests. If you have a free Adafruit IO Account, the rate limit is 30 data points per minute. If you have <a href="https://io.adafruit.com/plus">upgraded to an Adafruit IO Plus account</a>, the base rate limit is 60 data points per minute. If you exceed this limit, a notice will be sent to the <code>{username}/throttle</code> MQTT topic. You can subscribe to the topic if you wish to know when the Adafruit IO rate limit has been exceeded for your user account. This limit applies to all Data record modification actions over the HTTP and MQTT APIs, so if you have multiple devices or clients publishing data, be sure to delay their updates enough that the total rate is below your account limit. One data record modification is any action that creates, updates, or deletes a single Data record. A best practice is to only save or modify data within the hot part of your code loop. You want to handle authentication and any other API requests (creating/getting feeds, etc) before you start your main code loop where you save data. We have general API throttles to ensure the API isn't being improperly used either by accident or for nefarious purposes. This throttle level is higher than any data rate limit throttles, but you may run into it if your code isn't optimized. One example would be if in the main loop of your code you are not only sending data, but also authenticating, retrieving all feeds, or anything else that doesn't involve saving or modifying data to a feed. In that scenario, you would be hitting the API 3x more times than necessary, and could get throttled, even if you're saving data within your allotted rate limit. <h1 id='pagination'>Pagination</h1> Adafruit IO’s API returns at most 1000 data points at a time. To get more data if your feed is over 1000 data points, you’ll need to “paginate” the data. What does this mean? When you perform <a href="#get-all-data-for-the-given-feed">an HTTP data GET query</a>, the results are always sorted newest-to-oldest and include 5 <code>X-Pagination-*</code> headers and <a href="https://tools.ietf.org/html/rfc5988#section-5">the Link header field</a> in the response. You can see an example of the headers on the right. <h2 id='pagination-headers'>Pagination Headers</h2><div class="highlight"><pre class="highlight yaml tab-yaml"><code>X-Pagination-Count: 250 X-Pagination-Limit: 250 X-Pagination-Total: 83027 X-Pagination-Start: X-Pagination-End: 2019-05-03T17:35:13.637+0000 Link: <https://io.adafruit.com/api/v2/abachman/feeds/humidity/data?end_time=2019-05-03+17%3A35%3A13+UTC&limit=250>;rel="next", <https://io.adafruit.com/api/v2/abachman/feeds/humidity/data?before=eyJ0aW1lX2lkIjoiMEU1M043N0syUjdUR1Y3MEY3UjJFUVlRVlkiLCJmZWVkX2lkIjoiNjE3MzcwLjAifQ%3D%3D&end_time=2019-05-03+17%3A35%3A13+UTC&limit=250> </code></pre></div> <ul> <li>Count (<code>X-Pagination-Count</code>) is the number of data points in the current request.</li> <li>Limit (<code>X-Pagination-Limit</code>) is either the requested limit if it was included as a parameter or 1000, whichever is less.</li> <li>Total (<code>X-Pagination-Total</code>) is the total number of data points in the feed for the given <code>start_time</code> and <code>end_time</code>. Note, this value may be up to 5 minutes behind real time.</li> <li>Start (<code>X-Pagination-Start</code>) is an ISO-8601 formatted date value based on the <code>start_time</code> parameter in the original request, if one was given.</li> <li>End (<code>X-Pagination-End</code>) is an ISO-8601 formatted date value based either on the <code>end_time</code> parameter from the original request or the time when the original request was made.</li> <li>Link is a set of one or more URLs that point you to related resources.</li> </ul> Whenever Limit and Count are both 1000 and Total is more than 1000, that’s evidence that more data is available. That's where the Link (<code>Link</code>) header comes in. <h2 id='the-link-header'>The Link Header</h2> For Adafruit IO Link always contains at least one URL inside angle brackets, that's the link to the page of data you are currently looking at. In the example above, the first URL is <code>https://io.adafruit.com/api/v2/abachman/feeds/example.counter-1/data?end_time=2019-05-02+22%3A33%3A22+UTC&limit=250</code>. The first URL given in the Link header can be used to request the same data set again in the future. Even if your original request didn't include any parameters, the Link URL will include a <code>start_time</code> parameter that reflects the time at which you made the request. This is how we can make sure you can request the same data repeatedly. The example Link value above also includes a next section: <code>rel="next", <https://io.adafruit.com/api/v2/abachman/feeds/example.counter-1/data?before=eyJ0aW1lX2lkIjoiMEU0V0RWSk1SNlgxNUgxV0FSR0c2SzFIRUgiLCJmZWVkX2lkIjoiNzMuMCJ9&end_time=2019-05-02+22%3A33%3A22+UTC&limit=250></code>. The <code>rel="next"</code> part means the URL that follows is a link to the next page of data. As long as there is more data available, the Link header will include a <code>rel="next"</code> URL. It updates on each request, so you can page through data by making a request, parsing the Link header to get a next URL, and then using that URL to make another request. If your initial request includes <code>end_time</code>, <code>start_time</code>, or <code>limit</code> parameters, those parameters will be included in the <code>rel="next"</code> URL. Note that since data request are always sorted by descending <code>created_at</code> date (newest first, oldest last), the next page of data is always the next older page of data. When visualized on a timeline, the concept of pagination looks like this: <img src="images/http/api-pagination.png" alt="" /> Note that long running, frequently updated feeds could have more than a hundred pages of data. In the example above, with a limit of 250 records, it would take 330 requests to get all the data. If you make requests without a small delay in between, you will hit a rate limit. To avoid this, watch for 429 HTTP error responses and handle them in code by adding a 30 second timeout between requests and request the largest size permitted, right now that's 1000 records. If your goal is to store and study the data offline, though, you would be better off downloading the whole feed using the Download button built into Adafruit IO on the web. You can find an example of a paginated data downloading script in Python <a href="https://gist.github.com/abachman/12df0b34503edd5692be22f6b9695539">at this link</a>. Stop by <a href="https://forums.adafruit.com/viewforum.php?f=56">the forums</a> or <a href="https://discord.gg/adafruit">Discord</a> if you have more questions about getting your Data out of IO. <h1 id='data'>Data</h1> Data is at the heart of Adafruit IO. Everything your device measures and records becomes a data point on an Adafruit IO <a href="#feeds">Feed</a>. You can create, read, update, or delete data records. Every CREATE, UPDATE, or DELETE action on a data record counts against your rate limit. Data points belong to feeds, so every Data API call starts with a Feed URL. Note that there are endpoints for submitting multiple data points to a feed, and multiple feed values to a group, see feeds/{feed_key}/batch and groups/{groupname}/data endpoints. <h2 id='create-data'>Create Data</h2> <blockquote> HTTP Request <div class="http">POST<code class="path">/api/v2/{username}/feeds/{feed_key}/data</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code># Send new data with a value of 42 $ curl -F 'value=42' -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data # Send new data with a value of 42 and include optional location metadata curl -H "Content-Type: application/json" -d '{"value": 42, "lat": 23.1, "lon": "-73.3"}' -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code># Adafruit IO Python # Send data to feed feed_name with a value of 42 io.send_data(location_feed.key, '42') # Send data to feed `feed_name` with a value of 42 and include optional location metadata metadata = {'lat': 40.726190, 'lon': -74.005334, 'ele': -6, 'created_at': None} io.send_data(feed_name.key, data_value, metadata) # Adafruit IO CircuitPython # Send data to feed feed_name with a value of 42 io.send_data(location_feed['key'], '42') # Send data to feed `feed_name` with a value of 42 and include optional location metadata metadata = {'lat': 40.726190, 'lon': -74.005334, 'ele': -6, 'created_at': None} io.send_data(feed_name['key'], data_value, metadata) </code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code>// Send data to Feed `feedName` with value of 42 feedName->save(42); // Send data to Feed `feedName` with value 42 and include optional location metadata feedName->save(42, latValue, lonValue, eleValue); </code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": "string", "value": "string", "feed_id": 0, "feed_key": "string", "created_at": "datetime", "location": {}, "lat": 0.0, "lon": 0.0, "ele": 0.0, "created_epoch": 0, "expiration": "datetime" } </code></pre></div> New data <h3 id='path-parameters'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>feed_key</td> <td>string</td> <td>true</td> <td>a valid feed key</td> </tr> </tbody></table> <h3 id='body-parameters'>Body Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>Request Body</td> <td>object</td> <td>true</td> <td>Data record (datum) including a <code>value</code> field (required) and optionally including: <code>lat</code>, <code>lon</code>, <code>ele</code> (latitude, longitude, and elevation values), and <code>created_at</code> (a date/time string).</td> </tr> </tbody></table> <h2 id='get-feed-data'>Get Feed Data</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/feeds/{feed_key}/data</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data # get the most recent value $ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data?limit=1 # get the most recent value before a particular time $ curl -H "X-AIO-Key: {io_key}" "https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data?limit=1&end_time=2019-05-05T00:00Z" # get all values in a date range $ curl -H "X-AIO-Key: {io_key}" "https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data?start_time=2019-05-04T00:00Z&end_time=2019-05-05T00:00Z" </code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code>// Not implemented in Adafruit IO Arduino </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code># Not implemented in Adafruit IO Python # Not implemented in Adafruit IO CircuitPython </code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>[ { "id": "string", "value": "string", "feed_id": 0, "feed_key": "string", "created_at": "datetime", "location": {}, "lat": 0.0, "lon": 0.0, "ele": 0.0, "created_epoch": 0, "expiration": "datetime" } ] </code></pre></div> <h3 id='response-parameters'>Response Parameters</h3> An array of zero or more data points. This API is paginated. <h3 id='path-parameters-2'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>feed_key</td> <td>string</td> <td>true</td> <td>a valid feed key</td> </tr> </tbody></table> <h3 id='query-parameters'>Query Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>start_time</td> <td>string</td> <td>false</td> <td>Start time for filtering, returns records created after given time. Use <a href="https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations">ISO8601 formatted dates</a>.</td> </tr> <tr> <td>end_time</td> <td>string</td> <td>false</td> <td>End time for filtering, returns records created before give time. Use <a href="https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations">ISO8601 formatted dates</a>.</td> </tr> <tr> <td>limit</td> <td>integer</td> <td>false</td> <td>Limit the number of records returned.</td> </tr> <tr> <td>include</td> <td>csv string</td> <td>false</td> <td>List of Data record fields to include in response records. Acceptable values are: <code>value</code>, <code>lat</code>, <code>lon</code>, <code>ele</code>, <code>id</code>, and <code>created_at</code>.</td> </tr> <tr> <td>before</td> <td>string</td> <td>false</td> <td>System generated token used to produce the next page of data. See <a href="#the-link-header">The Link Header</a> for details.</td> </tr> </tbody></table> <h2 id='chart-feed-data'>Chart Feed Data</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/feeds/{feed_key}/data/chart</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code># Query the chart API for the previous hour. $ curl -H "X-AIO-Key: {io_key}" 'https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data/chart?hours=1' </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "feed": { "id": 0, "key": "string", "name": "string" }, "parameters": { "start_time": "2019-02-28T16:17:09Z", "end_time": "2019-04-29T16:17:09Z", "resolution": 120, "hours": 1440, "field": "avg" }, "columns": ["date", "avg"], "data": [ [ "2019-03-01T14:00:00Z", "62.579827586206896" ], [ "2019-03-02T18:00:00Z", "64.94642857142857" ], [ "...", "..."] ] } </code></pre></div> A JSON record containing chart data and the parameters used to generate it. This API will automatically calculate <code>resolution</code> based on the optimal time slice for the given <code>start_time</code> to <code>end_time</code> range or <code>hours</code> value given. Charts on io.adafruit.com use this API with only the <code>hours</code> parameter to render charts on dashboards and feed pages. <h3 id='path-parameters-3'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>feed_key</td> <td>string</td> <td>true</td> <td>a valid feed key</td> </tr> </tbody></table> <h3 id='query-parameters-2'>Query Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>start_time</td> <td>string</td> <td>false</td> <td>Start time for filtering, returns records created after given time. Use <a href="https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations">ISO8601 formatted dates</a>.</td> </tr> <tr> <td>end_time</td> <td>string</td> <td>false</td> <td>End time for filtering, returns records created before give time. Use <a href="https://en.wikipedia.org/wiki/ISO_8601#Combined_date_and_time_representations">ISO8601 formatted dates</a>.</td> </tr> <tr> <td>resolution</td> <td>int</td> <td>false</td> <td>Size of aggregation slice in minutes. Must be one of: <code>1</code>, <code>5</code>, <code>10</code>, <code>30</code>, <code>60</code>, <code>120</code>, <code>240</code>, <code>480</code>, or <code>960</code></td> </tr> <tr> <td>hours</td> <td>int</td> <td>false</td> <td>Number of hours to include in the chart. This value is ignored if <code>start_time</code> and <code>end_time</code> are given.</td> </tr> <tr> <td>field</td> <td>string</td> <td>false</td> <td>Aggregate field to return. Must be one of: <code>avg</code>, <code>sum</code>, <code>val</code>, <code>min</code>, <code>max</code>, <code>val_count</code></td> </tr> <tr> <td>raw</td> <td>boolean</td> <td>false</td> <td>Force raw chart data to be returned. Not compatible with <code>field</code> or <code>resolution</code> parameters. Use <code>1</code> or <code>true</code> for boolean true value.</td> </tr> </tbody></table> <h2 id='create-multiple-data-records'>Create Multiple Data Records</h2> <blockquote> HTTP Request <div class="http">POST<code class="path">/api/v2/{username}/feeds/{feed_key}/data/batch</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "Content-Type: application/json" -d @batch.json -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/data/batch </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code># Adafruit IO Python data_list = [Data(value=50), Data(value=33)] aio.send_batch_data(feed_name.key, data_list) # Not implemented in Adafruit IO CircuitPython </code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>[ { "id": "string", "value": "string", "feed_id": 0, "feed_key": "string", "created_at": "datetime", "location": {}, "lat": 0.0, "lon": 0.0, "ele": 0.0, "created_epoch": 0, "expiration": "datetime" } ] </code></pre></div> New data <h3 id='path-parameters-4'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>feed_key</td> <td>string</td> <td>true</td> <td>a valid feed key</td> </tr> </tbody></table> <h3 id='body-parameters-2'>Body Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>data</td> <td>array</td> <td>true</td> <td>A collection of data records including <code>value</code> (required) and optionally including: <code>lat</code>, <code>lon</code>, <code>ele</code> (latitude, longitude, and elevation values), and <code>created_at</code> (a date/time string).</td> </tr> </tbody></table> <h2 id='get-previous-data'>Get Previous Data</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/feeds/{feed_key}/data/previous</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code></code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code># Adafruit IO Python data = aio.receive_previous(feed.key) </code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": "string", "value": "string", "feed_id": 0, "feed_key": "string", "created_at": "datetime", "location": {}, "lat": 0.0, "lon": 0.0, "ele": 0.0, "created_epoch": 0, "expiration": "datetime" } </code></pre></div> Data response <h3 id='path-parameters-5'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>feed_key</td> <td>string</td> <td>true</td> <td>a valid feed key</td> </tr> </tbody></table> <h3 id='query-parameters-3'>Query Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>include</td> <td>string</td> <td>false</td> <td>List of Data record fields to include in response as comma separated list. Acceptable values are: <code>value</code>, <code>lat</code>, <code>lon</code>, <code>ele</code>, <code>id</code>, and <code>created_at</code>.</td> </tr> </tbody></table> <h2 id='get-next-data'>Get Next Data</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/feeds/{feed_key}/data/next</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code></code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code># Adafruit IO Python data = aio.receive_next(feed.key) </code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": "string", "value": "string", "feed_id": 0, "feed_key": "string", "created_at": "datetime", "location": {}, "lat": 0.0, "lon": 0.0, "ele": 0.0, "created_epoch": 0, "expiration": "datetime" } </code></pre></div> Data response <h3 id='path-parameters-6'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>feed_key</td> <td>string</td> <td>true</td> <td>a valid feed key</td> </tr> </tbody></table> <h3 id='query-parameters-4'>Query Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>include</td> <td>string</td> <td>false</td> <td>List of Data record fields to include in response as comma separated list. Acceptable values are: <code>value</code>, <code>lat</code>, <code>lon</code>, <code>ele</code>, <code>id</code>, and <code>created_at</code>.</td> </tr> </tbody></table> <h2 id='get-last-data'>Get Last Data</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/feeds/{feed_key}/data/last</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code></code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": "string", "value": "string", "feed_id": 0, "feed_key": "string", "created_at": "datetime", "location": {}, "lat": 0.0, "lon": 0.0, "ele": 0.0, "created_epoch": 0, "expiration": "datetime" } </code></pre></div> Data response <h3 id='path-parameters-7'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>feed_key</td> <td>string</td> <td>true</td> <td>a valid feed key</td> </tr> </tbody></table> <h3 id='query-parameters-5'>Query Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>include</td> <td>string</td> <td>false</td> <td>List of Data record fields to include in response as comma separated list. Acceptable values are: <code>value</code>, <code>lat</code>, <code>lon</code>, <code>ele</code>, <code>id</code>, and <code>created_at</code>.</td> </tr> </tbody></table> <h2 id='get-first-data'>Get First Data</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/feeds/{feed_key}/data/first</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code></code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code># Adafruit IO Python data = aio.receive(feed.key) </code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": "string", "value": "string", "feed_id": 0, "feed_key": "string", "created_at": "datetime", "location": {}, "lat": 0.0, "lon": 0.0, "ele": 0.0, "created_epoch": 0, "expiration": "datetime" } </code></pre></div> Data response. <h3 id='path-parameters-8'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>feed_key</td> <td>string</td> <td>true</td> <td>a valid feed key</td> </tr> </tbody></table> <h3 id='query-parameters-6'>Query Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>include</td> <td>string</td> <td>false</td> <td>List of Data record fields to include in response as comma separated list. Acceptable values are: <code>value</code>, <code>lat</code>, <code>lon</code>, <code>ele</code>, <code>id</code>, and <code>created_at</code>.</td> </tr> </tbody></table> <h2 id='get-most-recent-data'>Get Most Recent Data</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/feeds/{feed_key}/data/retain</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code></code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight plaintext"><code>"string",0.0,0.0,0.0 </code></pre></div> CSV string in <code>value,lat,lon,ele</code> format. The lat, lon, and ele values are left blank if they are not set. <h3 id='path-parameters-9'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>feed_key</td> <td>string</td> <td>true</td> <td>a valid feed key</td> </tr> </tbody></table> <h2 id='get-data-point'>Get Data Point</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/feeds/{feed_key}/data/{id}</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code></code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code># Adafruit IO Python data = aio.receive(feed_name.key) # Adafruit IO CircuitPython data = aio.receive(feed_name['key']) </code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": "string", "value": "string", "feed_id": 0, "feed_key": "string", "created_at": "datetime", "location": {}, "lat": 0.0, "lon": 0.0, "ele": 0.0, "created_epoch": 0, "expiration": "datetime" } </code></pre></div> Data response <h3 id='path-parameters-10'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>feed_key</td> <td>string</td> <td>true</td> <td>a valid feed key</td> </tr> <tr> <td>id</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h3 id='query-parameters-7'>Query Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>include</td> <td>string</td> <td>false</td> <td>List of Data record fields to include in response as comma separated list. Acceptable values are: <code>value</code>, <code>lat</code>, <code>lon</code>, <code>ele</code>, <code>id</code>, and <code>created_at</code>.</td> </tr> </tbody></table> <h2 id='update-data-point'>Update Data Point</h2> <blockquote> HTTP Request <div class="http">PUT<code class="path">/api/v2/{username}/feeds/{feed_key}/data/{id}</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code></code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": "string", "value": "string", "feed_id": 0, "feed_key": "string", "created_at": "datetime", "location": {}, "lat": 0.0, "lon": 0.0, "ele": 0.0, "created_epoch": 0, "expiration": "datetime" } </code></pre></div> Updated Data <h3 id='path-parameters-11'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>feed_key</td> <td>string</td> <td>true</td> <td>a valid feed key</td> </tr> <tr> <td>id</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h3 id='body-parameters-3'>Body Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>Request Body</td> <td>object</td> <td>true</td> <td>Data record (datum) including a <code>value</code> field (required) and optionally including: <code>lat</code>, <code>lon</code>, <code>ele</code> (latitude, longitude, and elevation values), and <code>created_at</code> (a date/time string).</td> </tr> </tbody></table> <h2 id='delete-data-point'>Delete Data Point</h2> <blockquote> HTTP Request <div class="http">DELETE<code class="path">/api/v2/{username}/feeds/{feed_key}/data/{id}</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code></code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code># Adafruit IO Python aio.delete(feed_name.key, data_id) # Adafruit IO CircuitPython aio.delete_data(feed_name['key'], data_id) </code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code></code></pre></div> Deleted Group successfully <h3 id='path-parameters-12'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>feed_key</td> <td>string</td> <td>true</td> <td>a valid feed key</td> </tr> <tr> <td>id</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h2 id='create-group-data'>Create Group Data</h2> <blockquote> HTTP Request <div class="http">POST<code class="path">/api/v2/{username}/groups/{group_key}/data</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code></code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": "string", "value": "string", "feed_id": 0, "feed_key": "string", "created_at": "datetime", "location": {}, "lat": 0.0, "lon": 0.0, "ele": 0.0, "created_epoch": 0, "expiration": "datetime" } </code></pre></div> New data <h3 id='path-parameters-13'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>group_key</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h3 id='body-parameters-4'>Body Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>group_feed_data</td> <td>object</td> <td>true</td> <td>A record with the <code>feeds</code> property, containing a collection of records with <code>key</code> and <code>value</code> properties.</td> </tr> </tbody></table> Example for <code>group_feed_data</code> in the body is as follows: <code>{ feeds: [ { key: string, value: string }, ... ], created_at: string (optional), location: { lat: number, lon: number, ele: number } (optional)}</code> <h2 id='get-data-for-group-39-s-feed'>Get Data for Group's Feed</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/groups/{group_key}/feeds/{feed_key}/data</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code># Send new data with a value of 42 to the group's feeds as json $ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/groups/{group_key}/data.json -d '{"feeds":[{"key":"{feed_key}","value":42}]}' </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": "string", "value": "string", "feed_id": 0, "feed_key": "string", "created_at": "datetime", "location": {}, "lat": 0.0, "lon": 0.0, "ele": 0.0, "created_epoch": 0, "expiration": "datetime" } </code></pre></div> An array of data <h3 id='path-parameters-14'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>group_key</td> <td>string</td> <td>true</td> <td></td> </tr> <tr> <td>feed_key</td> <td>string</td> <td>true</td> <td>a valid feed key</td> </tr> </tbody></table> <h2 id='create-data-in-a-group-39-s-feed'>Create Data in a Group's Feed</h2> <blockquote> HTTP Request <div class="http">POST<code class="path">/api/v2/{username}/groups/{group_key}/feeds/{feed_key}/data</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code></code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": "string", "value": "string", "feed_id": 0, "feed_key": "string", "created_at": "datetime", "location": {}, "lat": 0.0, "lon": 0.0, "ele": 0.0, "created_epoch": 0, "expiration": "datetime" } </code></pre></div> New data <h3 id='path-parameters-15'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>group_key</td> <td>string</td> <td>true</td> <td></td> </tr> <tr> <td>feed_key</td> <td>string</td> <td>true</td> <td>a valid feed key</td> </tr> </tbody></table> <h3 id='body-parameters-5'>Body Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>Request Body</td> <td>object</td> <td>true</td> <td>Data record (datum) including a <code>value</code> field (required) and optionally including: <code>lat</code>, <code>lon</code>, <code>ele</code> (latitude, longitude, and elevation values), and <code>created_at</code> (a date/time string).</td> </tr> </tbody></table> <h2 id='create-data-in-a-group-39-s-feed-2'>Create Data in a Group's Feed</h2> <blockquote> HTTP Request <div class="http">POST<code class="path">/api/v2/{username}/groups/{group_key}/feeds/{feed_key}/data/batch</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code></code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>[ { "id": "string", "value": "string", "feed_id": 0, "feed_key": "string", "created_at": "datetime", "location": {}, "lat": 0.0, "lon": 0.0, "ele": 0.0, "created_epoch": 0, "expiration": "datetime" } ] </code></pre></div> New data <h3 id='path-parameters-16'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>group_key</td> <td>string</td> <td>true</td> <td></td> </tr> <tr> <td>feed_key</td> <td>string</td> <td>true</td> <td>a valid feed key</td> </tr> </tbody></table> <h3 id='body-parameters-6'>Body Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>data</td> <td>array</td> <td>true</td> <td>A collection of data records including <code>value</code> (required) and optionally including: <code>lat</code>, <code>lon</code>, <code>ele</code> (latitude, longitude, and elevation values), and <code>created_at</code> (a date/time string).</td> </tr> </tbody></table> <h1 id='feeds'>Feeds</h1> Feeds are the core of the Adafruit IO system. The feed holds metadata about the data you push to Adafruit IO. This includes settings for whether the data is public or private, what license the stored data falls under, and a general description of the data. The feed also contains the sensor data values that get pushed to Adafruit IO from your device. You will need to create one feed for each unique source of data you send to Adafruit IO. You can create, read, update, or delete feeds. Every CREATE, UPDATE, or DELETE action on a feed record counts against your rate limit. There are also endpoints for submitting multiple data points to a feed, or multiple feed values to a group, see feeds/{feed_key}/batch and groups/{groupname}/data endpoints. <h2 id='all-feeds'>All Feeds</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/feeds</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/ </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code># Adafruit IO Python feeds = aio.feeds() # Not implemented in Adafruit IO CircuitPython </code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>[ { "id": 0, "name": "string", "key": "string", "group": { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" }, "groups": [ { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" } ], "description": "string", "details": { "shared_with": null, "data": { "first": { "id": "string", "value": "string", "feed_id": 0, "group_id": 0, "expiration": "string", "lat": 0, "lon": 0, "ele": 0, "completed_at": "string", "created_at": "string", "updated_at": "string", "created_epoch": 0 }, "last": { "id": "string", "value": "string", "feed_id": 0, "group_id": 0, "expiration": "string", "lat": 0, "lon": 0, "ele": 0, "completed_at": "string", "created_at": "string", "updated_at": "string", "created_epoch": 0 }, "count": 0 } }, "unit_type": "string", "unit_symbol": "string", "history": true, "visibility": "string", "license": "string", "enabled": true, "last_value": "string", "status": "string", "status_notify": true, "status_timeout": 0, "created_at": "string", "updated_at": "string" } ] </code></pre></div> An array of feeds <h3 id='path-parameters'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> </tbody></table> <h2 id='create-feed'>Create Feed</h2> <blockquote> HTTP Request <div class="http">POST<code class="path">/api/v2/{username}/feeds</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -X POST -H "Content-Type: application/json" -H "X-AIO-Key: {io_key}" \ --data '{"feed": {"name": "New Feed"}}' \ /{username}/feeds </code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code>AdafruitIO_Feed *newFeed = io.feed("newfeed"); </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code># Adafruit IO Python new_feed = Feed(name="newfeed") aio.create_feed(new_feed) # Adafruit IO CircuitPython new_feed = io.create_new_feed('newfeed') </code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code>puts "create" Feed = api.create_feed(name: "Feed #{SecureRandom.hex(4)}") </code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": 0, "name": "string", "key": "string", "group": { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" }, "groups": [ { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" } ], "description": "string", "details": { "shared_with": null, "data": { "first": { "id": "string", "value": "string", "feed_id": 0, "group_id": 0, "expiration": "string", "lat": 0, "lon": 0, "ele": 0, "completed_at": "string", "created_at": "string", "updated_at": "string", "created_epoch": 0 }, "last": { "id": "string", "value": "string", "feed_id": 0, "group_id": 0, "expiration": "string", "lat": 0, "lon": 0, "ele": 0, "completed_at": "string", "created_at": "string", "updated_at": "string", "created_epoch": 0 }, "count": 0 } }, "unit_type": "string", "unit_symbol": "string", "history": true, "visibility": "string", "license": "string", "enabled": true, "last_value": "string", "status": "string", "status_notify": true, "status_timeout": 0, "created_at": "string", "updated_at": "string" } </code></pre></div> New feed <h3 id='path-parameters-2'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> </tbody></table> <h3 id='query-parameters'>Query Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>group_key</td> <td>string</td> <td>false</td> <td></td> </tr> </tbody></table> <h3 id='body-parameters'>Body Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>feed</td> <td>object</td> <td>true</td> <td></td> </tr> </tbody></table> <h2 id='get-feed'>Get Feed</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/feeds/{feed_key}</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {io_key}" /{username}/feeds/{feed_key} </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code># Adafruit IO Python new_feed = aio.feeds('feedkey') # Adafruit IO CircuitPython new_feed = io.get_feed('feedkey') </code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code>puts "read?" # ... get 404 begin api.feed(feedname['key']) rescue => ex if ex.response.status === 404 puts "expected error #{ex.response.status}: #{ex.message}" else puts "unexpected error! #{ex.message}" end end </code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": 0, "name": "string", "key": "string", "group": { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" }, "groups": [ { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" } ], "description": "string", "details": { "shared_with": null, "data": { "first": { "id": "string", "value": "string", "feed_id": 0, "group_id": 0, "expiration": "string", "lat": 0, "lon": 0, "ele": 0, "completed_at": "string", "created_at": "string", "updated_at": "string", "created_epoch": 0 }, "last": { "id": "string", "value": "string", "feed_id": 0, "group_id": 0, "expiration": "string", "lat": 0, "lon": 0, "ele": 0, "completed_at": "string", "created_at": "string", "updated_at": "string", "created_epoch": 0 }, "count": 0 } }, "unit_type": "string", "unit_symbol": "string", "history": true, "visibility": "string", "license": "string", "enabled": true, "last_value": "string", "status": "string", "status_notify": true, "status_timeout": 0, "created_at": "string", "updated_at": "string" } </code></pre></div> Feed response <h3 id='path-parameters-3'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>feed_key</td> <td>string</td> <td>true</td> <td>a valid feed key</td> </tr> </tbody></table> <h2 id='update-feed'>Update Feed</h2> <blockquote> HTTP Request <div class="http">PUT<code class="path">/api/v2/{username}/feeds/{feed_key}</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/{feed_key} </code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code>// Not implemented in Adafruit IO Arduino </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code># Not implemented in Adafruit IO Python # Not implemented in Adafruit IO CircuitPython </code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": 0, "name": "string", "key": "string", "group": { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" }, "groups": [ { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" } ], "description": "string", "details": { "shared_with": null, "data": { "first": { "id": "string", "value": "string", "feed_id": 0, "group_id": 0, "expiration": "string", "lat": 0, "lon": 0, "ele": 0, "completed_at": "string", "created_at": "string", "updated_at": "string", "created_epoch": 0 }, "last": { "id": "string", "value": "string", "feed_id": 0, "group_id": 0, "expiration": "string", "lat": 0, "lon": 0, "ele": 0, "completed_at": "string", "created_at": "string", "updated_at": "string", "created_epoch": 0 }, "count": 0 } }, "unit_type": "string", "unit_symbol": "string", "history": true, "visibility": "string", "license": "string", "enabled": true, "last_value": "string", "status": "string", "status_notify": true, "status_timeout": 0, "created_at": "string", "updated_at": "string" } </code></pre></div> Updated feed <h3 id='path-parameters-4'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>feed_key</td> <td>string</td> <td>true</td> <td>a valid feed key</td> </tr> </tbody></table> <h3 id='body-parameters-2'>Body Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>feed</td> <td>object</td> <td>true</td> <td></td> </tr> </tbody></table> <h2 id='delete-feed'>Delete Feed</h2> <blockquote> HTTP Request <div class="http">DELETE<code class="path">/api/v2/{username}/feeds/{feed_key}</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/{feed_key} </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code># Adafruit IO Python io.delete_feed(feed_name.key) # Adafruit IO CircuitPython io.delete_feed(feed_name['key']) </code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code>puts "delete" api.delete_feed(feed) </code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code> </code></pre></div> Deleted feed successfully <h3 id='path-parameters-5'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>feed_key</td> <td>string</td> <td>true</td> <td>a valid feed key</td> </tr> </tbody></table> <h2 id='get-feed-2'>Get Feed</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/feeds/{feed_key}/details</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/feeds/{feed_key}/details </code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code>// Not implemented in Adafruit IO Arduino </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code># Not implemented in Adafruit IO Python # Not implemented in Adafruit IO CircuitPython </code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code>puts "read" puts JSON.pretty_generate(api.feed_details(feed)) </code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": 0, "name": "string", "key": "string", "group": { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" }, "groups": [ { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" } ], "description": "string", "details": { "shared_with": null, "data": { "first": { "id": "string", "value": "string", "feed_id": 0, "group_id": 0, "expiration": "string", "lat": 0, "lon": 0, "ele": 0, "completed_at": "string", "created_at": "string", "updated_at": "string", "created_epoch": 0 }, "last": { "id": "string", "value": "string", "feed_id": 0, "group_id": 0, "expiration": "string", "lat": 0, "lon": 0, "ele": 0, "completed_at": "string", "created_at": "string", "updated_at": "string", "created_epoch": 0 }, "count": 0 } }, "unit_type": "string", "unit_symbol": "string", "history": true, "visibility": "string", "license": "string", "enabled": true, "last_value": "string", "status": "string", "status_notify": true, "status_timeout": 0, "created_at": "string", "updated_at": "string" } </code></pre></div> Feed response <h3 id='path-parameters-6'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>feed_key</td> <td>string</td> <td>true</td> <td>a valid feed key</td> </tr> </tbody></table> <h1 id='groups'>Groups</h1> <blockquote> A Group Record </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": 0, "name": "string", "description": "string", "feeds": [ { "id": 0, "name": "string", "key": "string", "group": { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" }, "groups": [ { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" } ], "description": "string", "unit_type": "string", "unit_symbol": "string", "history": true, "visibility": "string", "license": "string", "enabled": true, "last_value": "string", "status": "string", "status_notify": true, "status_timeout": 0, "created_at": "string", "updated_at": "string" } ], "created_at": "string", "updated_at": "string" } </code></pre></div> Groups are a set of Feeds. They're used for publishing and reading to multiple feeds at a time. For example, if you are building a weather station, you would add feeds for <code>humidity</code> and <code>temperature</code> to a new <code>weatherstation</code> group. You can create, read, update, or delete group records. Every CREATE, UPDATE, or DELETE action on a group record counts against your rate limit. There is also an endpoint for submitting multiple feed values to a group, see the groups/{groupname}/data endpoint. <h2 id='get-all-groups'>Get All Groups</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/groups</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {your_aio_key}" http://io.adafruit.com/api/v2/{your_username}/groups </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>[ { "id": 0, "name": "string", "description": "string", "feeds": [ { "id": 0, "name": "string", "key": "string", "group": { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" }, "groups": [ { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" } ], "description": "string", "details": { "shared_with": null, "data": { "first": { "id": "string", "value": "string", "feed_id": 0, "group_id": 0, "expiration": "string", "lat": 0, "lon": 0, "ele": 0, "completed_at": "string", "created_at": "string", "updated_at": "string", "created_epoch": 0 }, "last": { "id": "string", "value": "string", "feed_id": 0, "group_id": 0, "expiration": "string", "lat": 0, "lon": 0, "ele": 0, "completed_at": "string", "created_at": "string", "updated_at": "string", "created_epoch": 0 }, "count": 0 } }, "unit_type": "string", "unit_symbol": "string", "history": true, "visibility": "string", "license": "string", "enabled": true, "last_value": "string", "status": "string", "status_notify": true, "status_timeout": 0, "created_at": "string", "updated_at": "string" } ], "created_at": "string", "updated_at": "string" } ] </code></pre></div> An array of groups with their respective feeds . <h3 id='path-parameters'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> </tbody></table> <h2 id='create-group'>Create Group</h2> <blockquote> HTTP Request <div class="http">POST<code class="path">/api/v2/{username}/groups</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -F 'name=New Group' -H "X-AIO-Key: {your_aio_key}" https://io.adafruit.com/api/v2/{username}/groups/ </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code>AdafruitIO_Group *group = io.group("example"); </code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": 0, "name": "string", "description": "string", "feeds": [ { "id": 0, "name": "string", "key": "string", "group": { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" }, "groups": [ { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" } ], "description": "string", "details": { "shared_with": null, "data": { "first": { "id": "string", "value": "string", "feed_id": 0, "group_id": 0, "expiration": "string", "lat": 0, "lon": 0, "ele": 0, "completed_at": "string", "created_at": "string", "updated_at": "string", "created_epoch": 0 }, "last": { "id": "string", "value": "string", "feed_id": 0, "group_id": 0, "expiration": "string", "lat": 0, "lon": 0, "ele": 0, "completed_at": "string", "created_at": "string", "updated_at": "string", "created_epoch": 0 }, "count": 0 } }, "unit_type": "string", "unit_symbol": "string", "history": true, "visibility": "string", "license": "string", "enabled": true, "last_value": "string", "status": "string", "status_notify": true, "status_timeout": 0, "created_at": "string", "updated_at": "string" } ], "created_at": "string", "updated_at": "string" } </code></pre></div> New Group <h3 id='path-parameters-2'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> </tbody></table> <h3 id='body-parameters'>Body Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>group</td> <td>object</td> <td>true</td> <td></td> </tr> </tbody></table> <h2 id='get-group'>Get Group</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/groups/{group_key}</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>curl -H "X-AIO-Key: {your_aio_key}" https://io.adafruit.com/api/v2/{username}/groups/{group_key} </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": 0, "name": "string", "description": "string", "feeds": [ { "id": 0, "name": "string", "key": "string", "group": { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" }, "groups": [ { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" } ], "description": "string", "details": { "shared_with": null, "data": { "first": { "id": "string", "value": "string", "feed_id": 0, "group_id": 0, "expiration": "string", "lat": 0, "lon": 0, "ele": 0, "completed_at": "string", "created_at": "string", "updated_at": "string", "created_epoch": 0 }, "last": { "id": "string", "value": "string", "feed_id": 0, "group_id": 0, "expiration": "string", "lat": 0, "lon": 0, "ele": 0, "completed_at": "string", "created_at": "string", "updated_at": "string", "created_epoch": 0 }, "count": 0 } }, "unit_type": "string", "unit_symbol": "string", "history": true, "visibility": "string", "license": "string", "enabled": true, "last_value": "string", "status": "string", "status_notify": true, "status_timeout": 0, "created_at": "string", "updated_at": "string" } ], "created_at": "string", "updated_at": "string" } </code></pre></div> Group response <h3 id='path-parameters-3'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>group_key</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h2 id='update-group'>Update Group</h2> <blockquote> HTTP Request <div class="http">PUT<code class="path">/api/v2/{username}/groups/{group_key}</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -F 'name=Group' -H "X-AIO-Key: {your_aio_key}" https://io.adafruit.com/api/v2/{username}/groups/{group_key} </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": 0, "name": "string", "description": "string", "feeds": [ { "id": 0, "name": "string", "key": "string", "group": { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" }, "groups": [ { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" } ], "description": "string", "details": { "shared_with": null, "data": { "first": { "id": "string", "value": "string", "feed_id": 0, "group_id": 0, "expiration": "string", "lat": 0, "lon": 0, "ele": 0, "completed_at": "string", "created_at": "string", "updated_at": "string", "created_epoch": 0 }, "last": { "id": "string", "value": "string", "feed_id": 0, "group_id": 0, "expiration": "string", "lat": 0, "lon": 0, "ele": 0, "completed_at": "string", "created_at": "string", "updated_at": "string", "created_epoch": 0 }, "count": 0 } }, "unit_type": "string", "unit_symbol": "string", "history": true, "visibility": "string", "license": "string", "enabled": true, "last_value": "string", "status": "string", "status_notify": true, "status_timeout": 0, "created_at": "string", "updated_at": "string" } ], "created_at": "string", "updated_at": "string" } </code></pre></div> Updated group <h3 id='path-parameters-4'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>group_key</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h3 id='body-parameters-2'>Body Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>group</td> <td>object</td> <td>true</td> <td></td> </tr> </tbody></table> <h2 id='delete-group'>Delete Group</h2> <blockquote> HTTP Request <div class="http">DELETE<code class="path">/api/v2/{username}/groups/{group_key}</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {your_aio_key}" https://io.adafruit.com/api/v2/{username}/groups/{group_key} </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>"string" </code></pre></div> Deleted Group successfully <h3 id='path-parameters-5'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>group_key</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h2 id='create-feed-in-a-group'>Create Feed in a Group</h2> <blockquote> HTTP Request <div class="http">POST<code class="path">/api/v2/{username}/groups/{group_key}/feeds</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl --data '{"feed": {"name": "Feed Name"}}' \ -H "Content-Type: application/json" \ -H "X-AIO-Key: {io_key}" \ https://io.adafruit.com/api/v2/{username}/groups/{group_key}/feeds </code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code>// Not implemented in Adafruit IO Arduino </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code># Not implemented in Adafruit IO Python # Not implemented in Adafruit IO CircuitPython </code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": 0, "name": "string", "key": "string", "group": { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" }, "groups": [ { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" } ], "description": "string", "details": { "shared_with": null, "data": { "first": { "id": "string", "value": "string", "feed_id": 0, "group_id": 0, "expiration": "string", "lat": 0, "lon": 0, "ele": 0, "completed_at": "string", "created_at": "string", "updated_at": "string", "created_epoch": 0 }, "last": { "id": "string", "value": "string", "feed_id": 0, "group_id": 0, "expiration": "string", "lat": 0, "lon": 0, "ele": 0, "completed_at": "string", "created_at": "string", "updated_at": "string", "created_epoch": 0 }, "count": 0 } }, "unit_type": "string", "unit_symbol": "string", "history": true, "visibility": "string", "license": "string", "enabled": true, "last_value": "string", "status": "string", "status_notify": true, "status_timeout": 0, "created_at": "string", "updated_at": "string" } </code></pre></div> New feed <h3 id='path-parameters-6'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>group_key</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h3 id='body-parameters-3'>Body Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>feed</td> <td>object</td> <td>true</td> <td></td> </tr> </tbody></table> <h2 id='add-feed-to-group'>Add Feed to Group</h2> <blockquote> HTTP Request <div class="http">POST<code class="path">/api/v2/{username}/groups/{group_key}/add</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -F 'feed_key={feed_key}' -H "X-AIO-Key: {your_aio_key}" https://io.adafruit.com/api/v2/{username}/groups/{group_key}/add </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": 0, "name": "string", "description": "string", "feeds": [ { "id": 0, "name": "string", "key": "string", "group": { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" }, "groups": [ { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" } ], "description": "string", "details": { "shared_with": null, "data": { "first": { "id": "string", "value": "string", "feed_id": 0, "group_id": 0, "expiration": "string", "lat": 0, "lon": 0, "ele": 0, "completed_at": "string", "created_at": "string", "updated_at": "string", "created_epoch": 0 }, "last": { "id": "string", "value": "string", "feed_id": 0, "group_id": 0, "expiration": "string", "lat": 0, "lon": 0, "ele": 0, "completed_at": "string", "created_at": "string", "updated_at": "string", "created_epoch": 0 }, "count": 0 } }, "unit_type": "string", "unit_symbol": "string", "history": true, "visibility": "string", "license": "string", "enabled": true, "last_value": "string", "status": "string", "status_notify": true, "status_timeout": 0, "created_at": "string", "updated_at": "string" } ], "created_at": "string", "updated_at": "string" } </code></pre></div> Returns updated group. <h3 id='path-parameters-7'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>group_key</td> <td>string</td> <td>true</td> <td></td> </tr> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> </tbody></table> <h3 id='query-parameters'>Query Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>feed_key</td> <td>string</td> <td>false</td> <td></td> </tr> </tbody></table> <h2 id='remove-feed-from-group'>Remove Feed from Group</h2> <blockquote> HTTP Request <div class="http">POST<code class="path">/api/v2/{username}/groups/{group_key}/remove</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -F 'feed_key={feed_key}' -H "X-AIO-Key: {your_aio_key}" https://io.adafruit.com/api/v2/{username}/groups/{group_key}/remove </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": 0, "name": "string", "description": "string", "feeds": [ { "id": 0, "name": "string", "key": "string", "group": { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" }, "groups": [ { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" } ], "description": "string", "details": { "shared_with": null, "data": { "first": { "id": "string", "value": "string", "feed_id": 0, "group_id": 0, "expiration": "string", "lat": 0, "lon": 0, "ele": 0, "completed_at": "string", "created_at": "string", "updated_at": "string", "created_epoch": 0 }, "last": { "id": "string", "value": "string", "feed_id": 0, "group_id": 0, "expiration": "string", "lat": 0, "lon": 0, "ele": 0, "completed_at": "string", "created_at": "string", "updated_at": "string", "created_epoch": 0 }, "count": 0 } }, "unit_type": "string", "unit_symbol": "string", "history": true, "visibility": "string", "license": "string", "enabled": true, "last_value": "string", "status": "string", "status_notify": true, "status_timeout": 0, "created_at": "string", "updated_at": "string" } ], "created_at": "string", "updated_at": "string" } </code></pre></div> Updated group <h3 id='path-parameters-8'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>group_key</td> <td>string</td> <td>true</td> <td></td> </tr> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> </tbody></table> <h3 id='query-parameters-2'>Query Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>feed_key</td> <td>string</td> <td>false</td> <td></td> </tr> </tbody></table> <h2 id='get-group-feeds'>Get Group Feeds</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/groups/{group_key}/feeds</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {your_aio_key}" https://io.adafruit.com/api/v2/{username}/groups/{group_key}/feeds </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>[ { "id": 0, "name": "string", "key": "string", "group": { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" }, "groups": [ { "id": 0, "name": "string", "description": "string", "created_at": "string", "updated_at": "string" } ], "description": "string", "details": { "shared_with": null, "data": { "first": { "id": "string", "value": "string", "feed_id": 0, "group_id": 0, "expiration": "string", "lat": 0, "lon": 0, "ele": 0, "completed_at": "string", "created_at": "string", "updated_at": "string", "created_epoch": 0 }, "last": { "id": "string", "value": "string", "feed_id": 0, "group_id": 0, "expiration": "string", "lat": 0, "lon": 0, "ele": 0, "completed_at": "string", "created_at": "string", "updated_at": "string", "created_epoch": 0 }, "count": 0 } }, "unit_type": "string", "unit_symbol": "string", "history": true, "visibility": "string", "license": "string", "enabled": true, "last_value": "string", "status": "string", "status_notify": true, "status_timeout": 0, "created_at": "string", "updated_at": "string" } ] </code></pre></div> An array of feeds <h3 id='path-parameters-9'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>group_key</td> <td>string</td> <td>true</td> <td></td> </tr> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> </tbody></table> <h1 id='webhooks'>Webhooks</h1> Webhooks are one way disconnected web services can share data with each other, automatically. For example, say you wanted to get a user’s latest Twitter message. Instead of constantly connecting to the twitter API every minute to check if a new message has been posted, you can ask Twitter to update a webhook URL on each post. That means Twitter will contact you when there’s new data. But, as you can imagine, you need a webserver to listen for that posting. In this case, Adafruit IO can act as that webhook destination. Adafruit IO only supports receiving data at this time. <aside class="notice"> These data publishing webhook methods do not require authentication. That means you can freely use the URL from a public form without leaking your authentication data. </aside> You can create new feed webhook receivers by visiting a feed page and using the "Webhooks" link. <h2 id='send-data-via-webhook'>Send Data via Webhook</h2> Create a data value. The request body should include a value parameter named either <code>value</code> or <code>payload</code> and may optionally include <code>lat</code>, <code>lon</code>, and <code>ele</code> parameters if you want to tag the data with a location. <blockquote> HTTP Request <div class="http">POST<code class="path">/api/v2/webhooks/feed/:token</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code># publish as form data curl -F "value=42" https://io.adafruit.com/api/v2/webhooks/feed/:token # publish as JSON curl -F '{"value":"42"}' -H 'Content-Type: application/json' \ https://io.adafruit.com/api/v2/webhooks/feed/:token </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": "string", "value": "42", "feed_id": 0, "feed_key": "string", "created_at": "datetime", "location": {}, "lat": 0.0, "lon": 0.0, "ele": 0.0, "created_epoch": 0, "expiration": "datetime" } </code></pre></div> <h3 id='path-parameters'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>token</td> <td>string</td> <td>true</td> <td>the webhook token</td> </tr> </tbody></table> <h3 id='body-parameters'>Body Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>value</td> <td>string</td> <td>true</td> <td>Data value</td> </tr> <tr> <td>lat</td> <td>float</td> <td>false</td> <td>latitude value for location</td> </tr> <tr> <td>lon</td> <td>float</td> <td>false</td> <td>longitude value for location</td> </tr> <tr> <td>ele</td> <td>float</td> <td>false</td> <td>elevation value for location</td> </tr> </tbody></table> <h2 id='send-arbitrary-data-via-webhook'>Send Arbitrary Data via Webhook</h2> New feed data record whose value is the raw contents of the webhook request body. Use this path if the web service you're connecting to can't be configured to match the webhook <code>Send Data</code> API body format. <blockquote> HTTP Request <div class="http">POST<code class="path">/api/v2/webhooks/feed/:token/raw</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>curl -H "Content-Type: text/plain" \ --data "this is raw data, { 'not properly formatted json' }" \ https://io.adafruit.com/api/v2/webhooks/feed/:token/raw </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": "string", "value": "this is raw data, { 'not properly formatted json' }", "feed_id": 0, "feed_key": "string", "created_at": "datetime", "location": {}, "lat": 0.0, "lon": 0.0, "ele": 0.0, "created_epoch": 0, "expiration": "datetime" } </code></pre></div> <h3 id='path-parameters-2'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>token</td> <td>string</td> <td>true</td> <td>the webhook token</td> </tr> </tbody></table> <h2 id='send-notification-via-webhook'>Send Notification via Webhook</h2> <blockquote> HTTP Request <div class="http">POST<code class="path">/api/v2/webhooks/feed/:token/notify</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -X POST https://io.adafruit.com/api/v2/webhooks/feed/:token/notify </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": "string", "value": "ping", "feed_id": 0, "feed_key": "string", "created_at": "datetime", "location": {}, "lat": 0.0, "lon": 0.0, "ele": 0.0, "created_epoch": 0, "expiration": "datetime" } </code></pre></div> Creates a new feed data record with the value "ping", regardless of what was posted. This path is helpful if you're using a low-memory MQTT client that can't handle the large webhook payloads that a service like GitHub publishes and all you care about is that something happened, not precisely what happened. <h1 id='actions'>Actions</h1> Actions are a way to do something when a certain situation occurs. There are two kinds of actions supported at this time: Scheduled and Reactive. Scheduled actions repeatedly perform an action after a scheduled interval. Reactive actions are much more advanced, and can integrate basic logic. At a basic level, they check if a feed value is somehow comparable to a value or to even another feed. If so, you’ll be able to send an email notification, post a webhook or even publish a message to another feed. For example, you can set up a reactive action to notify you when the temperature falls below a certain value. When paired with Feed Notification you can easily keep track of the health of your feed and also when something’s gone wrong. <h2 id='get-all-actions'>Get All Actions</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/actions</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/actions </code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>[ { "name": "string" } ] </code></pre></div> An array of actions <h3 id='path-parameters'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> </tbody></table> <h2 id='create-action'>Create Action</h2> <blockquote> HTTP Request <div class="http">POST<code class="path">/api/v2/{username}/actions</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/actions </code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "name": "string" } </code></pre></div> New Action <h3 id='path-parameters-2'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> </tbody></table> <h3 id='body-parameters'>Body Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>trigger</td> <td>object</td> <td>true</td> <td></td> </tr> </tbody></table> <h2 id='return-action'>Return Action</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/actions/{id}</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/actions/{id} </code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "name": "string" } </code></pre></div> Action response <h3 id='path-parameters-3'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>id</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h2 id='replace-action'>Replace Action</h2> <blockquote> HTTP Request <div class="http">PUT<code class="path">/api/v2/{username}/actions/{id}</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/actions/{id} </code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "name": "string" } </code></pre></div> Updated action <h3 id='path-parameters-4'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>id</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h3 id='body-parameters-2'>Body Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>trigger</td> <td>object</td> <td>true</td> <td></td> </tr> </tbody></table> <h2 id='delete-action'>Delete Action</h2> <blockquote> HTTP Request <div class="http">DELETE<code class="path">/api/v2/{username}/actions/{id}</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/actions/{id} </code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>"string" </code></pre></div> Deleted Action successfully <h3 id='path-parameters-5'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>id</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h1 id='activities'>Activities</h1> Activities are Adafruit IO's list of actions you've taken to create, update, or delete objects in your Adafruit IO account. We store the last 1000 actions taken for: <ul> <li>Dashboards</li> <li>Blocks</li> <li>Feeds</li> <li>Groups</li> <li>Actions</li> </ul> <h2 id='all-activities'>All Activities</h2> <blockquote> HTTP Request <div class="http">GET <code class="path">/api/v2/{username}/activities</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>curl -H "X-AIO-Key: {io_key}" \ https://io.adafruit.com/api/v2/{username}/activities </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>[ { "id": 0, "action": "string", "model": "string", "data": { }, "user_id": 0, "created_at": "string", "updated_at": "string" } ] </code></pre></div><h3 id='path-parameters'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> </tbody></table> <h3 id='query-parameters'>Query Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>start_time</td> <td>string</td> <td>false</td> <td>Start time for filtering, returns records created after given time.</td> </tr> <tr> <td>end_time</td> <td>string</td> <td>false</td> <td>End time for filtering, returns records created before give time.</td> </tr> <tr> <td>limit</td> <td>integer</td> <td>false</td> <td>Limit the number of records returned.</td> </tr> </tbody></table> <h2 id='get-activities-by-type'>Get Activities by Type</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/activities/{type}</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code># Returns two records $ curl -F 'limit=2' -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/activities/{type} </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>[ { "id": 0, "action": "string", "model": "string", "data": { }, "user_id": 0, "created_at": "string", "updated_at": "string" } ] </code></pre></div> An array of activities <h3 id='path-parameters-2'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>type</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h3 id='query-parameters-2'>Query Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>start_time</td> <td>string</td> <td>false</td> <td>Start time for filtering, returns records created after given time.</td> </tr> <tr> <td>end_time</td> <td>string</td> <td>false</td> <td>End time for filtering, returns records created before give time.</td> </tr> <tr> <td>limit</td> <td>integer</td> <td>false</td> <td>Limit the number of records returned.</td> </tr> </tbody></table> <h1 id='blocks'>Blocks</h1> Blocks are objects which can be placed on an Adafruit IO Dasboard for a user. Blocks IO range from input blocks (sliders and buttons) to output blocks (such as maps or other visual displays). The <code>dashboard_key</code> can be obtained by either the response of a dashboard API call, or via the UI within IO at https://io.adafruit.com/{username}/dashboards. <h2 id='all-blocks'>All blocks</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/dashboards/{dashboard_key}/blocks</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code></code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>[ { "name": "string", "description": "string", "key": "string", "visual_type": "string", "column": 0, "row": 0, "size_x": 0, "size_y": 0, "block_feeds": [ { "id": "string", "feed": null, "group": null } ] } ] </code></pre></div> An array of blocks <h3 id='path-parameters'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>dashboard_key</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h2 id='create-a-block'>Create a Block</h2> <blockquote> HTTP Request <div class="http">POST<code class="path">/api/v2/{username}/dashboards/{dashboard_key}/blocks</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code></code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "name": "string", "description": "string", "key": "string", "visual_type": "string", "column": 0, "row": 0, "size_x": 0, "size_y": 0, "block_feeds": [ { "id": "string", "feed": null, "group": null } ] } </code></pre></div> New Block <h3 id='path-parameters-2'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>dashboard_key</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h3 id='body-parameters'>Body Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>block</td> <td>object</td> <td>true</td> <td></td> </tr> </tbody></table> <h2 id='returns-block'>Returns Block</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/dashboards/{dashboard_key}/blocks/{id}</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code></code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "name": "string", "description": "string", "key": "string", "visual_type": "string", "column": 0, "row": 0, "size_x": 0, "size_y": 0, "block_feeds": [ { "id": "string", "feed": null, "group": null } ] } </code></pre></div> Block response <h3 id='path-parameters-3'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>dashboard_key</td> <td>string</td> <td>true</td> <td></td> </tr> <tr> <td>id</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h2 id='replace-a-block'>Replace A Block</h2> <blockquote> HTTP Request <div class="http">PUT<code class="path">/api/v2/{username}/dashboards/{dashboard_key}/blocks/{id}</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code></code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "name": "string", "description": "string", "key": "string", "visual_type": "string", "column": 0, "row": 0, "size_x": 0, "size_y": 0, "block_feeds": [ { "id": "string", "feed": null, "group": null } ] } </code></pre></div> Updated block <h3 id='path-parameters-4'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>dashboard_key</td> <td>string</td> <td>true</td> <td></td> </tr> <tr> <td>id</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h3 id='body-parameters-2'>Body Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>block</td> <td>object</td> <td>true</td> <td></td> </tr> </tbody></table> <h2 id='delete-a-block'>Delete a Block</h2> <blockquote> HTTP Request <div class="http">DELETE<code class="path">/api/v2/{username}/dashboards/{dashboard_key}/blocks/{id}</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code></code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>"string" </code></pre></div> Deleted Block successfully <h3 id='path-parameters-5'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>dashboard_key</td> <td>string</td> <td>true</td> <td></td> </tr> <tr> <td>id</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h1 id='dashboards'>Dashboards</h1> Dashboards allow you to visualize data and control Adafruit IO connected projects from any modern web browser. Blocks such as charts, sliders, and buttons are available to help you quickly get your IoT project up and running without the need for any custom code. <h2 id='all-dashboards'>All dashboards</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/dashboards</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/dashboards </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>[ { "name": "string", "description": "string", "key": "string", "blocks": [ { "name": "string", "description": "string", "key": "string", "visual_type": "string", "column": 0, "row": 0, "size_x": 0, "size_y": 0, "block_feeds": [ { "id": "string", "feed": null, "group": null } ] } ] } ] </code></pre></div> An array of dashboards <h3 id='path-parameters'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> </tbody></table> <h2 id='create-a-dashboard'>Create a Dashboard</h2> <blockquote> HTTP Request <div class="http">POST<code class="path">/api/v2/{username}/dashboards</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -F 'name=newdash' -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/dashboards </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "name": "string", "description": "string", "key": "string", "blocks": [ { "name": "string", "description": "string", "key": "string", "visual_type": "string", "column": 0, "row": 0, "size_x": 0, "size_y": 0, "block_feeds": [ { "id": "string", "feed": null, "group": null } ] } ] } </code></pre></div> New Dashboard <h3 id='path-parameters-2'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> </tbody></table> <h3 id='body-parameters'>Body Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>dashboard</td> <td>object</td> <td>true</td> <td></td> </tr> </tbody></table> <h2 id='return-dashboard'>Return Dashboard</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/dashboards/{id}</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/dashboards/{id} </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "name": "string", "description": "string", "key": "string", "blocks": [ { "name": "string", "description": "string", "key": "string", "visual_type": "string", "column": 0, "row": 0, "size_x": 0, "size_y": 0, "block_feeds": [ { "id": "string", "feed": null, "group": null } ] } ] } </code></pre></div> Dashboard response <h3 id='path-parameters-3'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>id</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h2 id='replace-a-dashboard'>Replace a Dashboard</h2> <blockquote> HTTP Request <div class="http">PUT<code class="path">/api/v2/{username}/dashboards/{id}</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -F 'name=newdash' -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/dashboards/{id} </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "name": "string", "description": "string", "key": "string", "blocks": [ { "name": "string", "description": "string", "key": "string", "visual_type": "string", "column": 0, "row": 0, "size_x": 0, "size_y": 0, "block_feeds": [ { "id": "string", "feed": null, "group": null } ] } ] } </code></pre></div> Updated dashboard <h3 id='path-parameters-4'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>id</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h3 id='body-parameters-2'>Body Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>dashboard</td> <td>object</td> <td>true</td> <td></td> </tr> </tbody></table> <h2 id='delete-a-dashboard'>Delete a Dashboard</h2> <blockquote> HTTP Request <div class="http">DELETE<code class="path">/api/v2/{username}/dashboards/{id}</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/dashboards/{id} </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>"string" </code></pre></div> Deleted Dashboard successfully <h3 id='path-parameters-5'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>id</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h1 id='permissions'>Permissions</h1> Each Adafruit IO user contains permissions which can be set and modified. <h2 id='get-all-permissions'>Get All Permissions</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/{type}/{type_id}/acl</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/{type}/{type_id}/acl </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>[ { "id": 0, "user_id": 0, "scope": "string", "scope_value": "string", "model": "string", "object_id": 0, "created_at": "string", "updated_at": "string" } ] </code></pre></div> An array of permissions <h3 id='path-parameters'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>type</td> <td>string</td> <td>true</td> <td></td> </tr> <tr> <td>type_id</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h2 id='create-permission'>Create Permission</h2> <blockquote> HTTP Request <div class="http">POST<code class="path">/api/v2/{username}/{type}/{type_id}/acl</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/{type}/{type_id}/acl </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": 0, "user_id": 0, "scope": "string", "scope_value": "string", "model": "string", "object_id": 0, "created_at": "string", "updated_at": "string" } </code></pre></div> New Permission <h3 id='path-parameters-2'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>type</td> <td>string</td> <td>true</td> <td></td> </tr> <tr> <td>type_id</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h3 id='body-parameters'>Body Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>permission</td> <td>object</td> <td>true</td> <td></td> </tr> </tbody></table> <h2 id='returns-permission'>Returns Permission</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/{type}/{type_id}/acl/{id}</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/{type}/{type_id}/acl{id} </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": 0, "user_id": 0, "scope": "string", "scope_value": "string", "model": "string", "object_id": 0, "created_at": "string", "updated_at": "string" } </code></pre></div> Permission response <h3 id='path-parameters-3'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>type</td> <td>string</td> <td>true</td> <td></td> </tr> <tr> <td>type_id</td> <td>string</td> <td>true</td> <td></td> </tr> <tr> <td>id</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h2 id='replace-permission'>Replace Permission</h2> <blockquote> HTTP Request <div class="http">PUT<code class="path">/api/v2/{username}/{type}/{type_id}/acl/{id}</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/{type}/{type_id}/acl{id} </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": 0, "user_id": 0, "scope": "string", "scope_value": "string", "model": "string", "object_id": 0, "created_at": "string", "updated_at": "string" } </code></pre></div> Updated permission <h3 id='path-parameters-4'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>type</td> <td>string</td> <td>true</td> <td></td> </tr> <tr> <td>type_id</td> <td>string</td> <td>true</td> <td></td> </tr> <tr> <td>id</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h3 id='body-parameters-2'>Body Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>permission</td> <td>object</td> <td>true</td> <td></td> </tr> </tbody></table> <h2 id='delete-permission'>Delete Permission</h2> <blockquote> HTTP Request <div class="http">DELETE<code class="path">/api/v2/{username}/{type}/{type_id}/acl/{id}</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/{type}/{type_id}/acl{id} </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>"string" </code></pre></div> Deleted Permission successfully <h3 id='path-parameters-5'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>type</td> <td>string</td> <td>true</td> <td></td> </tr> <tr> <td>type_id</td> <td>string</td> <td>true</td> <td></td> </tr> <tr> <td>id</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h1 id='users'>Users</h1> Adafruit IO can return information about your username, activity-level, rate-limit and current actions. <h2 id='get-user-info'>Get User Info</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/user</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/user </code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "id": 0, "name": "string", "color": "string", "username": "string", "time_zone": "string", "created_at": "string", "updated_at": "string" } </code></pre></div> A User record <h2 id='get-detailed-user-info'>Get Detailed User Info</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/throttle</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/throttle </code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "data_rate_limit": 0, "active_data_rate": 0 } </code></pre></div> Data rate limit and current actions. <h3 id='path-parameters'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> </tbody></table> <h1 id='tokens'>Tokens</h1> Tokens are used for authenticating an Adafruit IO user. See the Authentication page for more information about this. <h2 id='get-all-tokens'>Get All Tokens</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/tokens</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/tokens </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>[ { "token": "string" } ] </code></pre></div> An array of tokens <h3 id='path-parameters'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> </tbody></table> <h2 id='create-token'>Create Token</h2> <blockquote> HTTP Request <div class="http">POST<code class="path">/api/v2/{username}/tokens</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -F 'token=uniqueToken' -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/tokens </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "token": "string" } </code></pre></div> New Token <h3 id='path-parameters-2'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> </tbody></table> <h3 id='body-parameters'>Body Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>token</td> <td>object</td> <td>true</td> <td></td> </tr> </tbody></table> <h2 id='returns-token'>Returns Token</h2> <blockquote> HTTP Request <div class="http">GET<code class="path">/api/v2/{username}/tokens/{id}</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/tokens/{id} </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>{ "token": "string" } </code></pre></div> Token response <h3 id='path-parameters-3'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>id</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h2 id='delete-token'>Delete Token</h2> <blockquote> HTTP Request <div class="http">DELETE<code class="path">/api/v2/{username}/tokens/{id}</code></div> </blockquote> <div class="highlight"><pre class="highlight shell tab-shell"><code>$ curl -H "X-AIO-Key: {io_key}" https://io.adafruit.com/api/v2/{username}/tokens/{id} </code></pre></div><div class="highlight"><pre class="highlight python tab-python"><code></code></pre></div><div class="highlight"><pre class="highlight cpp tab-cpp"><code></code></pre></div><div class="highlight"><pre class="highlight ruby tab-ruby"><code></code></pre></div> <blockquote> Response Sample: </blockquote> <div class="highlight"><pre class="highlight json tab-json"><code>"string" </code></pre></div> Deleted Token successfully <h3 id='path-parameters-4'>Path Parameters</h3> <table><thead> <tr> <th>Parameter</th> <th>Type</th> <th>Required</th> <th>Description</th> </tr> </thead><tbody> <tr> <td>username</td> <td>string</td> <td>true</td> <td>a valid username string</td> </tr> <tr> <td>id</td> <td>string</td> <td>true</td> <td></td> </tr> </tbody></table> <h1 id='services'>Services</h1> Adafruit IO provides access to several connected services. The current services offered are <a href="https://io.adafruit.com/services/ifttt">IFTTT</a>, <a href="https://io.adafruit.com/services/zapier">Zapier</a>, <a href="https://io.adafruit.com/services/weather">Weather</a>, <a href="https://io.adafruit.com/services/words">Randomizer</a> and <a href="https://io.adafruit.com/services/time">Time</a>. Each of these services is unique in that you may need to do some setup at the links above prior to utilizing the service via the Adafruit IO HTTP API. <h2 id='time'>Time</h2> The Adafruit IO time service does not replace a time-synchronization service like NTP, but it can help you figure out your local time on an Internet of Things device that doesn't have a built in clock. Detailed documentation on the usage of the time API is found within <a href="https://io.adafruit.com/services/time">Adafruit IO on the time services page</a>. <h2 id='randomizer'>Randomizer</h2> Create random data streams that can generate colors, words, numbers, or pick a value from a custom data set and send it directly to your devices. The four available data types are: <ul> <li>Pronounceable nonsense words</li> <li>Colors (RGB values, HSL values, CSS hex, or CSS color name)</li> <li>Numbers</li> <li>Preset (sample from a given set of values)</li> </ul> Detailed documentation on the usage and setup of the randomizer API is found within <a href="https://io.adafruit.com/services/words">Adafruit IO on the randomizer services page</a>. <h2 id='weather'>Weather</h2> With access to weather data powered by Dark Sky, you can get hyper-local forecasts sent directly to your devices. Weather data is updated at most once every 20 minutes. When you have an IO Plus account, you can track the weather through our HTTP or MQTT APIs for up to 5 locations at a time. Detailed documentation on the usage and setup of the weather API is found within <a href="https://io.adafruit.com/services/weather">Adafruit IO on the weather services page</a>. <h1 id='errors'>Errors</h1> The Adafruit IO API uses the following error codes: <table><thead> <tr> <th>Error Code</th> <th>Meaning</th> </tr> </thead><tbody> <tr> <td>400</td> <td>Bad Request -- Your request is invalid or was in the wrong format.</td> </tr> <tr> <td>401</td> <td>Unauthorized -- Your API key is wrong or you're trying to view a resource you don't own.</td> </tr> <tr> <td>403</td> <td>Forbidden -- This action is not permitted.</td> </tr> <tr> <td>404</td> <td>Not Found -- The specified record could not be found.</td> </tr> <tr> <td>406</td> <td>Not Acceptable -- You requested a format that we don't serve.</td> </tr> <tr> <td>422</td> <td>Unprocessable Entity -- You've sent data we can't accept/understand. Is the value field (string/number) missing?</td> </tr> <tr> <td>429</td> <td>Too Many Requests -- You're sending or requesting data too quickly! Slow down!</td> </tr> <tr> <td>500</td> <td>Internal Server Error -- We had a problem with our server. Try again later.</td> </tr> <tr> <td>503</td> <td>Service Unavailable -- We're temporarily offline for maintenance. Please try again later.</td> </tr> </tbody></table> </div> <div class="dark-box"> <div class="lang-selector"> <a href="#" data-language-name="shell">CURL</a> <a href="#" data-language-name="cpp">Arduino</a> <a href="#" data-language-name="python">Python</a> <a href="#" data-language-name="python">Circuitpython</a> <a href="#" data-language-name="ruby">Ruby</a> </div> </div> </div> </body> </html>