canonical: https://jentic.com/apis/adafruit.com/adafruit-adafruit-io-api # Adafruit IO REST API Jentic publishes the only available OpenAPI specification for Adafruit IO REST API, keeping it validated and agent-ready. The Adafruit IO REST API exposes the full IoT platform surface - feeds, dashboards and blocks, groups, throttle status, activities, charts, and signed-request authentication. The spec covers 71 endpoints and supports both header and query API key auth (X-AIO-Key) plus an X-AIO-Signature scheme for signed requests. Endpoints under /{username}/feeds include chart, batch, retain, previous, next, first, and last data accessors for finely controlled telemetry retrieval. ## For AI agents Manage feeds, dashboards, blocks, and signed requests across the full Adafruit IO REST surface for IoT projects. ## Scope Does not handle device firmware OTA, cellular connectivity, or paid IoT SIMs - use for Adafruit IO feeds, dashboards, blocks, throttle, and activity data only. ## Capabilities - Create and manage feeds, including batch ingest, chart data, and last/first/next/previous data points under /{username}/feeds - Build and update IoT dashboards and add blocks via /{username}/dashboards and /{username}/dashboards/{dashboard_id}/blocks - Inspect feed throughput limits using /{username}/throttle - Group related feeds together through /{username}/groups - Pull the user's recent activities at /{username}/activities and /{username}/activities/{type} - Configure feed retention policies through the /{username}/feeds/{feed_key}/data/retain endpoint - Authenticate with either header or query X-AIO-Key, or via signed requests using X-AIO-Signature ## Use cases ### Dashboard automation Makers and educators auto-provision Adafruit IO dashboards for student projects or home setups. An agent can POST to /{username}/dashboards to create the dashboard, then POST to /{username}/dashboards/{dashboard_id}/blocks for each chart, gauge, or toggle block. This avoids dragging blocks around the UI for every new project. Example prompt: Create a dashboard 'classroom-temp', then add chart blocks for the temperature, humidity, and pressure feeds via /{username}/dashboards/{dashboard_id}/blocks ### Time-series chart retrieval Analytics workflows need pre-aggregated chart data instead of raw points. /{username}/feeds/{feed_key}/data/chart returns chartable summaries that suit dashboards and ML feature pipelines without client-side bucketing. An agent can pull the chart series, then push it into a notebook or warehouse. Example prompt: GET /{username}/feeds/temp/data/chart with hours=24 and resolution=15 minutes, then export to a Parquet file ### Throttle-aware ingest Devices that send frequent telemetry can exhaust Adafruit IO's per-minute limits. An agent can periodically GET /{username}/throttle to read remaining capacity, then decide whether to batch via /{username}/feeds/{feed_key}/data/batch or pause ingest. This makes the device cooperative with the platform's fair-use limits. Example prompt: GET /{username}/throttle, and if remaining is low, batch the next 5 minutes of readings via /{username}/feeds/{feed_key}/data/batch ### Signed-request device auth Some constrained devices cannot safely store a long-lived API key. Adafruit IO supports signed requests using the X-AIO-Signature header alongside an X-AIO-Key, so a backend can pre-sign a request that a device executes within a short window. An agent can act as the signing service for a fleet of devices. Example prompt: Generate an X-AIO-Signature for a POST to /{username}/feeds/temp/data and hand it to the device for execution ### AI agent integration Makers building agent assistants for their lab or home expose Adafruit IO REST through Jentic alongside notification and dashboarding APIs. The X-AIO-Key (and signature where used) live in your Jentic One instance; the agent searches by intent - 'create a dashboard', 'read a chart', 'check throttle' - without seeing raw keys. Example prompt: Search Jentic for 'create an Adafruit IO dashboard with charts', load the dashboard and block schemas, and execute them in sequence ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | /{username}/feeds | List feeds | | POST | /{username}/feeds/{feed_key}/data/batch | Batch ingest data points | | GET | /{username}/feeds/{feed_key}/data/chart | Get chart-aggregated feed data | | GET | /{username}/feeds/{feed_key}/data/last | Get the latest data point | | POST | /{username}/dashboards | Create a dashboard | | POST | /{username}/dashboards/{dashboard_id}/blocks | Add a block to a dashboard | | GET | /{username}/throttle | Read throttle status | | GET | /{username}/activities | List recent activities | ## Key resources - **Feeds** — Telemetry streams with batch, chart, retain, and positional data accessors - **Dashboards** — Visual layouts of feeds - IoT dashboards - **Blocks** — Chart, gauge, toggle and other UI elements on a dashboard - **Groups** — Logical groupings of feeds - **Throttle** — Per-account throughput status - **Activities** — Recent platform activity for the authenticated user - **User** — Authenticated user metadata ## Why Jentic - **Setup:** Wiring the Adafruit IO REST API by hand means attaching the X-AIO-Key and X-AIO-Signature headers on every call and threading the username, feed key, and dashboard id through feed and dashboard endpoints. Through Jentic you install once, import the Adafruit IO REST API from the API Directory, store the key and signature once, and your agent calls it. - **Permission scoping:** Adafruit IO puts the feed key in the URL path (/{username}/feeds/{feed_key}/...), so a rule can pin your agent to one feed: it can batch data into that feed and read its chart and nothing else. You choose the operations it may call, so creating dashboards or blocks is not included unless you add it. - **Credential handling:** Your Adafruit IO X-AIO-Key and X-AIO-Signature are stored once, encrypted, by your own Jentic One instance and injected as headers at execution time. They never enter the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'create an Adafruit IO dashboard' or 'check throttle status', and Jentic returns the matching operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **Adafruit IO API** — Slimmer 18-endpoint Adafruit IO surface - feeds, groups, and user only. - **Particle API** — End-to-end IoT platform with hardware, cellular SIM, and OTA firmware updates. - **Blynk API** — Mobile-first IoT platform with a drag-and-drop dashboard builder. ## FAQ ### Why is there no official OpenAPI spec for Adafruit IO REST API? Adafruit publishes API documentation but not a structured OpenAPI specification. Jentic generates and maintains this spec so that AI agents and developers can call Adafruit IO REST API via structured tooling. It is validated against the live API and kept up to date. Get started with Jentic One, the self-hosted execution layer. ### What authentication does the Adafruit IO REST API use? The API supports an X-AIO-Key API key, in either the request header or query string, and an X-AIO-Signature header for signed requests. Through Jentic, both values are stored encrypted in your Jentic One instance and the agent receives a scoped execution handle, so the raw key and signature never appear in prompts. ### Can I create dashboards and blocks with the Adafruit IO REST API? Yes. POST /{username}/dashboards creates a dashboard, and POST /{username}/dashboards/{dashboard_id}/blocks adds chart, gauge, or toggle blocks tied to specific feeds. The full block lifecycle (create, update, delete) is exposed under /{username}/dashboards/{dashboard_id}/blocks/{id}. ### What are the rate limits for the Adafruit IO REST API? Adafruit IO enforces a per-minute throughput cap that depends on the account tier. Use GET /{username}/throttle to read your current remaining capacity, and prefer batch ingest via /{username}/feeds/{feed_key}/data/batch over single-point posts to stay within budget. ### How do I create an Adafruit IO dashboard through Jentic? Run pip install jentic, search Jentic for 'create an Adafruit IO dashboard', load the schema for POST /{username}/dashboards, and execute it with a name. Then chain a search for 'add a block to an Adafruit IO dashboard' to load POST /{username}/dashboards/{dashboard_id}/blocks. Jentic injects the X-AIO-Key from the vault. ### Does the Adafruit IO REST API support data retention rules? Yes. The /{username}/feeds/{feed_key}/data/retain endpoint configures retention behaviour for a feed - useful when you want long-term storage for some feeds but not others, or when you need to cap storage for a constrained tier. ### Can I limit what my agent is allowed to do with the Adafruit IO REST API? Yes. Because you run Jentic One yourself, your own rules decide which Adafruit IO operations and credentials the agent may use, and only the operations you allow are callable. Adafruit IO puts the feed key in the URL path (/{username}/feeds/{feed_key}/...), so a rule can pin the agent to a single feed, letting it batch data into that feed via /{username}/feeds/{feed_key}/data/batch and read its chart via /data/chart and nothing else. Operations are opt-in, so creating dashboards through /{username}/dashboards or adding blocks is not available to the agent unless you explicitly include them.