@lap v0.3
# Machine-readable API spec. Each @endpoint block is one API call.
@api Adafruit IO REST API
@base https://io.adafruit.com/api/v2
@version 2.0.0
@auth ApiKey X-AIO-Key in header | ApiKey X-AIO-Key in query | ApiKey X-AIO-Signature in header
@common_fields {username: any # a valid username string}
@endpoints 71
@hint download_for_search
@toc user(1), {username}(68), webhooks(2)

@group user
@endpoint GET /user
@desc Get information about the current user
@returns(200) A User record
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endgroup

@group {username}
@endpoint GET /{username}/throttle
@desc Get the user's data rate limit and current activity level.
@returns(200) Data rate limit and current actions.
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/activities
@desc All activities for current user
@optional {start_time: any # Start time for filtering, returns records created after given time., end_time: any # End time for filtering, returns records created before give time., limit: any # Limit the number of records returned.}
@returns(200) An array of activities
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint DELETE /{username}/activities
@desc All activities for current user
@returns(200) Deleted activities successfully
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/activities/{type}
@desc Get activities by type for current user
@required {type: any}
@optional {start_time: any # Start time for filtering, returns records created after given time., end_time: any # End time for filtering, returns records created before give time., limit: any # Limit the number of records returned.}
@returns(200) An array of activities
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/feeds
@desc All feeds for current user
@returns(200) An array of feeds
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint POST /{username}/feeds
@desc Create a new Feed
@required {feed: map}
@optional {group_key: any}
@returns(200) New feed
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/feeds/{feed_key}
@desc Get feed by feed key
@required {feed_key: any # a valid feed key}
@returns(200) Feed response
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint PUT /{username}/feeds/{feed_key}
@desc Replace an existing Feed
@required {feed_key: any # a valid feed key, feed: map}
@returns(200) Updated feed
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint PATCH /{username}/feeds/{feed_key}
@desc Update properties of an existing Feed
@required {feed_key: any # a valid feed key, feed: map}
@returns(200) Updated feed
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint DELETE /{username}/feeds/{feed_key}
@desc Delete an existing Feed
@required {feed_key: any # a valid feed key}
@returns(200) Deleted feed successfully
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/feeds/{feed_key}/details
@desc Get detailed feed by feed key
@required {feed_key: any # a valid feed key}
@returns(200) Feed response
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/feeds/{feed_key}/data
@desc Get all data for the given feed
@required {feed_key: any # a valid feed key}
@optional {start_time: any # Start time for filtering, returns records created after given time., end_time: any # End time for filtering, returns records created before give time., limit: any # Limit the number of records returned., include: any # List of Data record fields to include in response as comma separated list. Acceptable values are: `value`, `lat`, `lon`, `ele`, `id`, and `created_at`.}
@returns(200) An array of data
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint POST /{username}/feeds/{feed_key}/data
@desc Create new Data
@required {feed_key: any # a valid feed key, datum: map # Data record including a `value` field (required) and optionally including: `lat`, `lon`, `ele` (latitude, longitude, and elevation values), and `created_at` (a date/time string).}
@returns(200) New data
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/feeds/{feed_key}/data/chart
@desc Chart data for current feed
@required {feed_key: any # a valid feed key}
@optional {start_time: any # Start time for filtering, returns records created after given time., end_time: any # End time for filtering, returns records created before give time., resolution: any # A resolution size in minutes. By giving a resolution value you will get back grouped data points aggregated over resolution-sized intervals. NOTE: time span is preferred over resolution, so if you request a span of time that includes more than max limit points you may get a larger resolution than you requested. Valid resolutions are 1, 5, 10, 30, 60, and 120., hours: any # The number of hours the chart should cover.}
@returns(200) A JSON record containing chart data and the parameters used to generate it.
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint POST /{username}/feeds/{feed_key}/data/batch
@desc Create multiple new Data records
@required {feed_key: any # a valid feed key, data: [map] # A collection of data records including `value` (required) and optionally including: `lat`, `lon`, `ele` (latitude, longitude, and elevation values), and `created_at` (a date/time string).}
@returns(200) New data
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/feeds/{feed_key}/data/previous
@desc Previous Data in Queue
@required {feed_key: any # a valid feed key}
@optional {include: any # List of Data record fields to include in response as comma separated list. Acceptable values are: `value`, `lat`, `lon`, `ele`, `id`, and `created_at`.}
@returns(200) Data response
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/feeds/{feed_key}/data/next
@desc Next Data in Queue
@required {feed_key: any # a valid feed key}
@optional {include: any # List of Data record fields to include in response as comma separated list. Acceptable values are: `value`, `lat`, `lon`, `ele`, `id`, and `created_at`.}
@returns(200) Data response
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/feeds/{feed_key}/data/last
@desc Last Data in Queue
@required {feed_key: any # a valid feed key}
@optional {include: any # List of Data record fields to include in response as comma separated list. Acceptable values are: `value`, `lat`, `lon`, `ele`, `id`, and `created_at`.}
@returns(200) Data response
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/feeds/{feed_key}/data/first
@desc First Data in Queue
@required {feed_key: any # a valid feed key}
@optional {include: any # List of Data record fields to include in response as comma separated list. Acceptable values are: `value`, `lat`, `lon`, `ele`, `id`, and `created_at`.}
@returns(200) Data response
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/feeds/{feed_key}/data/retain
@desc Last Data in MQTT CSV format
@required {feed_key: any # a valid feed key}
@returns(200) CSV string in `value,lat,lon,ele` format. The lat, lon, and ele values are left blank if they are not set.
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/feeds/{feed_key}/data/{id}
@desc Returns data based on feed key
@required {feed_key: any # a valid feed key, id: any}
@optional {include: any # List of Data record fields to include in response as comma separated list. Acceptable values are: `value`, `lat`, `lon`, `ele`, `id`, and `created_at`.}
@returns(200) Data response
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint PUT /{username}/feeds/{feed_key}/data/{id}
@desc Replace existing Data
@required {feed_key: any # a valid feed key, id: any, datum: map # Data record including a `value` field (required) and optionally including: `lat`, `lon`, `ele` (latitude, longitude, and elevation values), and `created_at` (a date/time string).}
@returns(200) Updated Data
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint PATCH /{username}/feeds/{feed_key}/data/{id}
@desc Update properties of existing Data
@required {feed_key: any # a valid feed key, id: any, datum: map # Data record including a `value` field (required) and optionally including: `lat`, `lon`, `ele` (latitude, longitude, and elevation values), and `created_at` (a date/time string).}
@returns(200) Updated Data
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint DELETE /{username}/feeds/{feed_key}/data/{id}
@desc Delete existing Data
@required {feed_key: any # a valid feed key, id: any}
@returns(200) Deleted Group successfully
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/groups
@desc All groups for current user
@returns(200) An array of groups
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint POST /{username}/groups
@desc Create a new Group
@required {group: map}
@returns(200) New Group
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/groups/{group_key}
@desc Returns Group based on ID
@required {group_key: any}
@returns(200) Group response
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error"}

@endpoint PUT /{username}/groups/{group_key}
@desc Replace an existing Group
@required {group_key: any, group: map}
@returns(200) Updated group
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint PATCH /{username}/groups/{group_key}
@desc Update properties of an existing Group
@required {group_key: any, group: map}
@returns(200) Updated Group
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint DELETE /{username}/groups/{group_key}
@desc Delete an existing Group
@required {group_key: any}
@returns(200) Deleted Group successfully
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint POST /{username}/groups/{group_key}/add
@desc Add an existing Feed to a Group
@required {group_key: any}
@optional {feed_key: any}
@returns(200) Updated group
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint POST /{username}/groups/{group_key}/remove
@desc Remove a Feed from a Group
@required {group_key: any}
@optional {feed_key: any}
@returns(200) Updated group
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/groups/{group_key}/feeds
@desc All feeds for current user in a given group
@required {group_key: any}
@returns(200) An array of feeds
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint POST /{username}/groups/{group_key}/feeds
@desc Create a new Feed in a Group
@required {group_key: any, feed: map}
@returns(200) New feed
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint POST /{username}/groups/{group_key}/data
@desc Create new data for multiple feeds in a group
@required {group_key: any, group_feed_data: map}
@returns(200) New data
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/groups/{group_key}/feeds/{feed_key}/data
@desc All data for current feed in a specific group
@required {group_key: any, feed_key: any # a valid feed key}
@optional {start_time: any # Start time for filtering data. Returns data created after given time., end_time: any # End time for filtering data. Returns data created before give time., limit: any # Limit the number of records returned.}
@returns(200) An array of data
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint POST /{username}/groups/{group_key}/feeds/{feed_key}/data
@desc Create new Data in a feed belonging to a particular group
@required {group_key: any, feed_key: any # a valid feed key, datum: map # Data record including a `value` field (required) and optionally including: `lat`, `lon`, `ele` (latitude, longitude, and elevation values), and `created_at` (a date/time string).}
@returns(200) New data
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint POST /{username}/groups/{group_key}/feeds/{feed_key}/data/batch
@desc Create multiple new Data records in a feed belonging to a particular group
@required {group_key: any, feed_key: any # a valid feed key, data: [map] # A collection of data records including `value` (required) and optionally including: `lat`, `lon`, `ele` (latitude, longitude, and elevation values), and `created_at` (a date/time string).}
@returns(200) New data
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/dashboards
@desc All dashboards for current user
@returns(200) An array of dashboards
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint POST /{username}/dashboards
@desc Create a new Dashboard
@required {dashboard: map}
@returns(200) New Dashboard
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/dashboards/{id}
@desc Returns Dashboard based on ID
@required {id: any}
@returns(200) Dashboard response
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error"}

@endpoint PUT /{username}/dashboards/{id}
@desc Replace an existing Dashboard
@required {id: any, dashboard: map}
@returns(200) Updated dashboard
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint PATCH /{username}/dashboards/{id}
@desc Update properties of an existing Dashboard
@required {id: any, dashboard: map}
@returns(200) Updated Dashboard
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint DELETE /{username}/dashboards/{id}
@desc Delete an existing Dashboard
@required {id: any}
@returns(200) Deleted Dashboard successfully
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/dashboards/{dashboard_id}/blocks
@desc All blocks for current user
@required {dashboard_id: any}
@returns(200) An array of blocks
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint POST /{username}/dashboards/{dashboard_id}/blocks
@desc Create a new Block
@required {block: map, dashboard_id: any}
@returns(200) New Block
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/dashboards/{dashboard_id}/blocks/{id}
@desc Returns Block based on ID
@required {dashboard_id: any, id: any}
@returns(200) Block response
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error"}

@endpoint PUT /{username}/dashboards/{dashboard_id}/blocks/{id}
@desc Replace an existing Block
@required {dashboard_id: any, id: any, block: map}
@returns(200) Updated block
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint PATCH /{username}/dashboards/{dashboard_id}/blocks/{id}
@desc Update properties of an existing Block
@required {dashboard_id: any, id: any, block: map}
@returns(200) Updated Block
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint DELETE /{username}/dashboards/{dashboard_id}/blocks/{id}
@desc Delete an existing Block
@required {dashboard_id: any, id: any}
@returns(200) Deleted Block successfully
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/tokens
@desc All tokens for current user
@returns(200) An array of tokens
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint POST /{username}/tokens
@desc Create a new Token
@required {token: map}
@returns(200) New Token
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/tokens/{id}
@desc Returns Token based on ID
@required {id: any}
@returns(200) Token response
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error"}

@endpoint PUT /{username}/tokens/{id}
@desc Replace an existing Token
@required {id: any, token: map}
@returns(200) Updated token
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint PATCH /{username}/tokens/{id}
@desc Update properties of an existing Token
@required {id: any, token: map}
@returns(200) Updated Token
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint DELETE /{username}/tokens/{id}
@desc Delete an existing Token
@required {id: any}
@returns(200) Deleted Token successfully
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/triggers
@desc All triggers for current user
@returns(200) An array of triggers
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint POST /{username}/triggers
@desc Create a new Trigger
@required {trigger: map}
@returns(200) New Trigger
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/triggers/{id}
@desc Returns Trigger based on ID
@required {id: any}
@returns(200) Trigger response
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error"}

@endpoint PUT /{username}/triggers/{id}
@desc Replace an existing Trigger
@required {id: any, trigger: map}
@returns(200) Updated trigger
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint PATCH /{username}/triggers/{id}
@desc Update properties of an existing Trigger
@required {id: any, trigger: map}
@returns(200) Updated Trigger
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint DELETE /{username}/triggers/{id}
@desc Delete an existing Trigger
@required {id: any}
@returns(200) Deleted Trigger successfully
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/{type}/{type_id}/acl
@desc All permissions for current user and type
@required {type: any, type_id: any}
@returns(200) An array of permissions
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint POST /{username}/{type}/{type_id}/acl
@desc Create a new Permission
@required {type: any, type_id: any, permission: map}
@returns(200) New Permission
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint GET /{username}/{type}/{type_id}/acl/{id}
@desc Returns Permission based on ID
@required {type: any, type_id: any, id: any}
@returns(200) Permission response
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error"}

@endpoint PUT /{username}/{type}/{type_id}/acl/{id}
@desc Replace an existing Permission
@required {type: any, type_id: any, id: any, permission: map}
@returns(200) Updated permission
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint PATCH /{username}/{type}/{type_id}/acl/{id}
@desc Update properties of an existing Permission
@required {type: any, type_id: any, id: any, permission: map}
@returns(200) Updated Permission
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint DELETE /{username}/{type}/{type_id}/acl/{id}
@desc Delete an existing Permission
@required {type: any, type_id: any, id: any}
@returns(200) Deleted Permission successfully
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endgroup

@group webhooks
@endpoint POST /webhooks/feed/:token
@desc Send data to a feed via webhook URL.
@required {payload: map # Webhook payload containing data `value` parameter.}
@returns(200) New feed data record
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endpoint POST /webhooks/feed/:token/raw
@desc Send arbitrary data to a feed via webhook URL.
@returns(200) New feed data record
@errors {401: Unauthorized, 403: Forbidden, 404: Not Found, 500: Server Error}

@endgroup

@end