Adafruit IO Feeds API

openapi: 3.0.0
info:
  title: Adafruit IO REST Activities Feeds API
  description: "### The Internet of Things for Everyone\n\nThe 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 Adafruit IO learn guide](https://learn.adafruit.com/series/adafruit-io-basics) and [a simple Internet of Things capable device like the Feather Huzzah](https://www.adafruit.com/product/2821).\n\nThis API documentation is hosted on GitHub Pages and is available at [https://github.com/adafruit/io-api](https://github.com/adafruit/io-api). For questions or comments visit the [Adafruit IO Forums](https://forums.adafruit.com/viewforum.php?f=56) or the [adafruit-io channel on the Adafruit Discord server](https://discord.gg/adafruit).\n\n#### Authentication\n\nAuthentication for every API request happens through the `X-AIO-Key` header or query parameter and your IO API key. A simple cURL request to get all available feeds for a user with the username \"io_username\" and the key \"io_key_12345\" could look like this:\n\n    $ curl -H \"X-AIO-Key: io_key_12345\" https://io.adafruit.com/api/v2/io_username/feeds\n\nOr like this:\n\n    $ curl \"https://io.adafruit.com/api/v2/io_username/feeds?X-AIO-Key=io_key_12345\n\nUsing the node.js [request](https://github.com/request/request) library, IO HTTP requests are as easy as:\n\n```js\nvar request = require('request');\n\nvar options = {\n  url: 'https://io.adafruit.com/api/v2/io_username/feeds',\n  headers: {\n    'X-AIO-Key': 'io_key_12345',\n    'Content-Type': 'application/json'\n  }\n};\n\nfunction callback(error, response, body) {\n  if (!error && response.statusCode == 200) {\n    var feeds = JSON.parse(body);\n    console.log(feeds.length + \" FEEDS AVAILABLE\");\n\n    feeds.forEach(function (feed) {\n      console.log(feed.name, feed.key);\n    })\n  }\n}\n\nrequest(options, callback);\n```\n\nUsing the ESP8266 Arduino HTTPClient library, an HTTPS GET request would look like this (replacing `---` with your own values in the appropriate locations):\n\n```arduino\n/// based on\n/// https://github.com/esp8266/Arduino/blob/master/libraries/ESP8266HTTPClient/examples/Authorization/Authorization.ino\n\n#include <Arduino.h>\n#include <ESP8266WiFi.h>\n#include <ESP8266WiFiMulti.h>\n#include <ESP8266HTTPClient.h>\n\nESP8266WiFiMulti WiFiMulti;\n\nconst char* ssid = \"---\";\nconst char* password = \"---\";\n\nconst char* host = \"io.adafruit.com\";\n\nconst char* io_key = \"---\";\nconst char* path_with_username = \"/api/v2/---/dashboards\";\n\n// Use web browser to view and copy\n// SHA1 fingerprint of the certificate\nconst char* fingerprint = \"77 00 54 2D DA E7 D8 03 27 31 23 99 EB 27 DB CB A5 4C 57 18\";\n\nvoid setup() {\n  Serial.begin(115200);\n\n  for(uint8_t t = 4; t > 0; t--) {\n    Serial.printf(\"[SETUP] WAIT %d...\\n\", t);\n    Serial.flush();\n    delay(1000);\n  }\n\n  WiFi.mode(WIFI_STA);\n  WiFiMulti.addAP(ssid, password);\n\n  // wait for WiFi connection\n  while(WiFiMulti.run() != WL_CONNECTED) {\n    Serial.print('.');\n    delay(1000);\n  }\n\n  Serial.println(\"[WIFI] connected!\");\n\n  HTTPClient http;\n\n  // start request with URL and TLS cert fingerprint for verification\n  http.begin(\"https://\" + String(host) + String(path_with_username), fingerprint);\n\n  // IO API authentication\n  http.addHeader(\"X-AIO-Key\", io_key);\n\n  // start connection and send HTTP header\n  int httpCode = http.GET();\n\n  // httpCode will be negative on error\n  if(httpCode > 0) {\n    // HTTP header has been send and Server response header has been handled\n    Serial.printf(\"[HTTP] GET response: %d\\n\", httpCode);\n\n    // HTTP 200 OK\n    if(httpCode == HTTP_CODE_OK) {\n      String payload = http.getString();\n      Serial.println(payload);\n    }\n\n    http.end();\n  }\n}\n\nvoid loop() {}\n```\n\n#### Client Libraries\n\nWe have client libraries to help you get started with your project: [Python](https://github.com/adafruit/io-client-python), [Ruby](https://github.com/adafruit/io-client-ruby), [Arduino C++](https://github.com/adafruit/Adafruit_IO_Arduino), [Javascript](https://github.com/adafruit/adafruit-io-node), and [Go](https://github.com/adafruit/io-client-go) are available. They're all open source, so if they don't already do what you want, you can fork and add any feature you'd like.\n\n"
  version: 2.0.0
  x-logo:
    url: https://io.adafruit.com/api/docs/adafruit-flower-left.png
servers:
- url: https://io.adafruit.com/api/v2
- url: http://io.adafruit.com/api/v2
security:
- HeaderKey: []
- HeaderSignature: []
- QueryKey: []
tags:
- name: Feeds
paths:
  /{username}/feeds:
    get:
      x-swagger-router-controller: Feeds
      x-swagger-router-action: all
      operationId: allFeeds
      summary: All feeds for current user
      description: The Feeds endpoint returns information about the user's feeds. The response includes the latest value of each feed, and other metadata about each feed.
      tags:
      - Feeds
      parameters:
      - $ref: '#/components/parameters/UsernamePath'
      responses:
        '200':
          description: An array of feeds
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Feed'
            text/csv:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Feed'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Server Error
    post:
      summary: Create a new Feed
      description: ''
      x-swagger-router-controller: Feeds
      x-swagger-router-action: create
      operationId: createFeed
      parameters:
      - $ref: '#/components/parameters/UsernamePath'
      - $ref: '#/components/parameters/GroupParam'
      requestBody:
        $ref: '#/components/requestBodies/createFeedFeed'
      tags:
      - Feeds
      responses:
        '200':
          description: New feed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feed'
            text/csv:
              schema:
                $ref: '#/components/schemas/Feed'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Server Error
  /{username}/feeds/{feed_key}:
    get:
      description: Returns feed based on the feed key
      summary: Get feed by feed key
      x-swagger-router-controller: Feeds
      x-swagger-router-action: get
      operationId: getFeed
      tags:
      - Feeds
      responses:
        '200':
          description: Feed response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feed'
            text/csv:
              schema:
                $ref: '#/components/schemas/Feed'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Server Error
      parameters:
      - $ref: '#/components/parameters/UsernamePath'
      - $ref: '#/components/parameters/FeedPath'
    put:
      summary: Replace an existing Feed
      x-swagger-router-controller: Feeds
      x-swagger-router-action: replace
      operationId: replaceFeed
      description: ''
      parameters:
      - $ref: '#/components/parameters/UsernamePath'
      - $ref: '#/components/parameters/FeedPath'
      requestBody:
        $ref: '#/components/requestBodies/createFeedFeed'
      tags:
      - Feeds
      responses:
        '200':
          description: Updated feed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feed'
            text/csv:
              schema:
                $ref: '#/components/schemas/Feed'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Server Error
    patch:
      summary: Update properties of an existing Feed
      description: ''
      x-swagger-router-controller: Feeds
      x-swagger-router-action: update
      operationId: updateFeed
      parameters:
      - $ref: '#/components/parameters/UsernamePath'
      - $ref: '#/components/parameters/FeedPath'
      requestBody:
        $ref: '#/components/requestBodies/createFeedFeed'
      tags:
      - Feeds
      responses:
        '200':
          description: Updated feed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feed'
            text/csv:
              schema:
                $ref: '#/components/schemas/Feed'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Server Error
    delete:
      summary: Delete an existing Feed
      description: ''
      x-swagger-router-controller: Feeds
      x-swagger-router-action: destroy
      operationId: destroyFeed
      parameters:
      - $ref: '#/components/parameters/UsernamePath'
      - $ref: '#/components/parameters/FeedPath'
      tags:
      - Feeds
      responses:
        '200':
          description: Deleted feed successfully
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Server Error
  /{username}/feeds/{feed_key}/details:
    get:
      description: Returns more detailed feed record based on the feed key
      summary: Get detailed feed by feed key
      x-swagger-router-controller: Feeds
      x-swagger-router-action: details
      operationId: getFeedDetails
      tags:
      - Feeds
      responses:
        '200':
          description: Feed response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feed'
            text/csv:
              schema:
                $ref: '#/components/schemas/Feed'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Server Error
      parameters:
      - $ref: '#/components/parameters/UsernamePath'
      - $ref: '#/components/parameters/FeedPath'
  /{username}/groups/{group_key}/add:
    post:
      summary: Add an existing Feed to a Group
      description: ''
      x-swagger-router-controller: Groups
      x-swagger-router-action: add_feed
      operationId: addFeedToGroup
      tags:
      - Feeds
      parameters:
      - $ref: '#/components/parameters/GroupPath'
      - $ref: '#/components/parameters/UsernamePath'
      - $ref: '#/components/parameters/FeedParam'
      responses:
        '200':
          description: Updated group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
            text/csv:
              schema:
                $ref: '#/components/schemas/Group'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Server Error
  /{username}/groups/{group_key}/remove:
    post:
      summary: Remove a Feed from a Group
      description: ''
      x-swagger-router-controller: Groups
      x-swagger-router-action: remove_feed
      operationId: removeFeedFromGroup
      tags:
      - Feeds
      parameters:
      - $ref: '#/components/parameters/GroupPath'
      - $ref: '#/components/parameters/UsernamePath'
      - $ref: '#/components/parameters/FeedParam'
      responses:
        '200':
          description: Updated group
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Group'
            text/csv:
              schema:
                $ref: '#/components/schemas/Group'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Server Error
  /{username}/groups/{group_key}/feeds:
    get:
      x-swagger-router-controller: GroupFeeds
      x-swagger-router-action: group_all
      operationId: allGroupFeeds
      summary: All feeds for current user in a given group
      description: The Group Feeds endpoint returns information about the user's feeds. The response includes the latest value of each feed, and other metadata about each feed, but only for feeds within the given group.
      tags:
      - Feeds
      parameters:
      - $ref: '#/components/parameters/GroupPath'
      - $ref: '#/components/parameters/UsernamePath'
      responses:
        '200':
          description: An array of feeds
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Feed'
            text/csv:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Feed'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Server Error
    post:
      summary: Create a new Feed in a Group
      description: ''
      x-swagger-router-controller: GroupFeeds
      x-swagger-router-action: group_create
      operationId: createGroupFeed
      parameters:
      - $ref: '#/components/parameters/UsernamePath'
      - $ref: '#/components/parameters/GroupPath'
      requestBody:
        $ref: '#/components/requestBodies/createFeedFeed'
      tags:
      - Feeds
      responses:
        '200':
          description: New feed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Feed'
            text/csv:
              schema:
                $ref: '#/components/schemas/Feed'
        '401':
          description: Unauthorized
        '403':
          description: Forbidden
        '404':
          description: Not Found
        '500':
          description: Server Error
components:
  requestBodies:
    createFeedFeed:
      content:
        application/json:
          schema:
            type: object
            properties:
              name:
                type: string
              key:
                type: string
              description:
                type: string
              license:
                type: string
        application/x-www-form-urlencoded:
          schema:
            type: object
            properties:
              name:
                type: string
              key:
                type: string
              description:
                type: string
              license:
                type: string
      required: true
  parameters:
    UsernamePath:
      name: username
      in: path
      required: true
      description: a valid username string
      schema:
        type: string
    GroupPath:
      name: group_key
      in: path
      required: true
      schema:
        type: string
    GroupParam:
      name: group_key
      in: query
      schema:
        type: string
    FeedParam:
      name: feed_key
      in: query
      schema:
        type: string
    FeedPath:
      name: feed_key
      description: a valid feed key
      in: path
      required: true
      schema:
        type: string
  schemas:
    ShallowGroup:
      type: object
      properties:
        id:
          type: number
          readOnly: true
        name:
          type: string
        description:
          type: string
        created_at:
          type: string
          readOnly: true
        updated_at:
          readOnly: true
          type: string
    Feed:
      type: object
      properties:
        id:
          type: number
          readOnly: true
        name:
          type: string
        key:
          type: string
        group:
          type: object
          readOnly: true
          additionalProperties:
            $ref: '#/components/schemas/ShallowGroup'
        groups:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/ShallowGroup'
        description:
          type: string
        details:
          type: object
          description: Additional details about this feed.
          readOnly: true
          properties:
            shared_with:
              type: array
              description: Access control list for this feed
              items:
                type: object
            data:
              type: object
              properties:
                first:
                  type: object
                  additionalProperties:
                    $ref: '#/components/schemas/Data'
                last:
                  type: object
                  additionalProperties:
                    $ref: '#/components/schemas/Data'
                count:
                  type: integer
                  description: Number of data points stored by this feed.
        unit_type:
          type: string
        unit_symbol:
          type: string
        history:
          type: boolean
        visibility:
          type: string
          default: private
          enum:
          - private
          - public
        license:
          type: string
        enabled:
          type: boolean
          readOnly: true
        last_value:
          type: string
          readOnly: true
        status:
          type: string
          readOnly: true
        status_notify:
          type: boolean
          description: Is status notification active?
        status_timeout:
          type: integer
          description: Status notification timeout in minutes.
        created_at:
          type: string
          readOnly: true
        updated_at:
          type: string
          readOnly: true
    Group:
      type: object
      properties:
        id:
          type: number
          readOnly: true
        name:
          type: string
        description:
          type: string
        feeds:
          type: array
          readOnly: true
          items:
            $ref: '#/components/schemas/Feed'
        created_at:
          type: string
          readOnly: true
        updated_at:
          readOnly: true
          type: string
    Data:
      type: object
      properties:
        id:
          type: string
          readOnly: true
        value:
          type: string
        feed_id:
          type: number
        group_id:
          readOnly: true
          type: number
        expiration:
          type: string
        lat:
          type: number
        lon:
          type: number
        ele:
          type: number
        completed_at:
          readOnly: true
          type: string
        created_at:
          readOnly: true
          type: string
        updated_at:
          readOnly: true
          type: string
        created_epoch:
          readOnly: true
          type: number
  securitySchemes:
    HeaderKey:
      description: The AIO Key is used to restrict or grant access to your data. The key is unique, and you can generate a key per feed, and control it in many different ways. The easiest process is to just use your automatically generated master key. You can access this key right from the right-hand side of your dashboard or from an individual feed page.
      type: apiKey
      in: header
      name: X-AIO-Key
    QueryKey:
      description: The AIO Key is used to restrict or grant access to your data. The key is unique, and you can generate a key per feed, and control it in many different ways. The easiest process is to just use your automatically generated master key. You can access this key right from the right-hand side of your dashboard or from an individual feed page.
      type: apiKey
      in: query
      name: X-AIO-Key
    HeaderSignature:
      description: The AIO Signature is an AWS inspired request signature.
      type: apiKey
      in: header
      name: X-AIO-Signature