# Appio Documentation - [Overview](#overview) - [Getting Started](#getting-started) - [API Overview](#api-overview) - [API Services](#api-services) - [API Devices](#api-devices) - [API Notifications](#api-notifications) - [API errors](#api-errors) - [AI Instructions](#ai) ## Overview Appio helps businesses add widgets and notifications to their products, without building or maintaining mobile apps, hiring developers, or dealing with app stores. Learn more about [Appio](https://appio.so), try our [interactive demo](https://demo.appio.so), or explore our [case studies](https://appio.so/#case-studies). Found an issue or have feedback? [Let us know!](https://appio.so/contact) ## Getting Started Before getting started, you'll need to [create an account](https://my.appio.so) and obtain your service\_id. There are two integration options for Appio, both functionally identical. ### Option 1 Preview Install code ``` Mobile APP ``` Appio service Use your service ID, which was assigned to you during registration. Replace svc\_\*\*YOUR\*SERVICE\*ID\*\* with your [service id](https://my.appio.so). eventCallback _optional_ Callback function to receive events from Appio. function (type, data) Appio.open user A unique identifier for your user. For security, use a non-sequential, non-predictable string. Suggestion: Hash the customer’s unique ID and registration date using a function like SHA-256 or MD5. service _optional_ Use your service ID, which was assigned to you during registration. * * * ### Option 2 Preview Install code ``` Mobile APP ``` data-appio Activates Appio. The field is required, but its _value_ is optional and can be omitted. data-service Use your service ID, which was assigned to you during registration. Replace svc\_\*\*YOUR\*SERVICE\*ID\*\* with your [service id](https://my.appio.so). data-user A unique identifier for your user. For security, use a non-sequential, non-predictable string. Suggestion: Hash the customer’s unique ID and registration date using a function like SHA-256 or MD5. ## API Overview All commands in this documentation are live and ready for testing. **NOTE**: Data is automatically reset every 15 minutes. This will deactivate the "Appio Docs" service on your device. ### Authentication All API requests must include an [authentication token](https://my.appio.so). Each registered service is issued a unique authentication token. You can validate your token by calling the testing endpoint: Request ``` curl https://api.appio.so/hi \ -H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A" ``` Response ``` HTTP Code: 200 ``` ``` 👋 ``` ## API Services ### View service details Path ``` GET /v1/services/{id} ``` Request ``` curl -X GET https://api.appio.so/v1/services/svc_00dddddd000000ccccccssssss \ -H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A" \ -H "X-Service-Id: svc_00dddddd000000ccccccssssss" ``` Response ``` HTTP Code: 200 ``` ``` { "id": "svc_00dddddd000000ccccccssssss", "title": "Appio Docs", "description": "Try out the functionality of Appio by downloading the app.", "logo_url": "https://cdn.appio.so/app/docs.appio.so/logo.png", "banner_url": "https://cdn.appio.so/app/docs.appio.so/banner.jpg", "url": "https://docs.appio.so", "text_color": "#000000", "background_color": "#ffffff", "accent_color": "#0066cc" } ``` ## API Devices ### List devices subscribed to service #### Pagination parameters limit _optional_ Integer. Default: 50. Min: 1, Max: 100. Maximum number of items to return. after _optional_ String. Cursor ID for pagination — returns items after this ID. Path ``` GET /v1/devices ``` Request ``` curl -X GET https://api.appio.so/v1/devices \ -H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A" \ -H "X-Service-Id: svc_00dddddd000000ccccccssssss" ``` Response ``` HTTP Code: 200 ``` ``` { "data": [ { "id": "dvc_01jmpmh9fvxgyym44sqanjr9hs", "user_id": "23d0e9848fe0ad06272dea39a03679ff", "name": "iPhone 13", "platform": "ios", "os_version": "18.3", "model": "iPhone", "device_token": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "notifications_enabled": true, "device_identifier": "iPhone14,5", "marketing_name": "iPhone 13" }, ... ], "pagination": { "next": "https://api.appio.so/v1/devices?after=dvc_01jmpmh9fvxgyym44sqanjr9hs" } } ``` * * * ### View device details Path ``` GET /v1/devices/{id} ``` Request ``` curl -X GET https://api.appio.so/v1/devices/dvc_01jmpmh9fvxgyym44sqanjr9hs \ -H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A" \ -H "X-Service-Id: svc_00dddddd000000ccccccssssss" ``` Response ``` HTTP Code: 200 ``` ``` { "id": "dvc_01jmpmh9fvxgyym44sqanjr9hs", "user_id": "23d0e9848fe0ad06272dea39a03679ff", "name": "iPhone 13", "platform": "ios", "os_version": "18.3", "model": "iPhone", "device_token": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "notifications_enabled": true, "device_identifier": "iPhone14,5", "marketing_name": "iPhone 13" } ``` * * * ### Deactivate device Deactivate a device when it should no longer receive notifications or when its associated user has been deactivated. Path ``` DELETE /v1/devices/{id} ``` Request ``` curl -X DELETE https://api.appio.so/v1/devices/dvc_01jmpmh9fvxgyym44sqanjr9hs \ -H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A" \ -H "X-Service-Id: svc_00dddddd000000ccccccssssss" ``` Response ``` HTTP Code: 200 ``` ``` { "id": "dvc_01jmpmh9fvxgyym44sqanjr9hs" } ``` * * * ### Deactivate all user devices Deactivate all of a user’s devices when they should no longer receive notifications or when the user has been deactivated. Path ``` DELETE /v1/devices?user_id={user_id} ``` Request ``` curl -X DELETE https://api.appio.so/v1/devices?user_id=23d0e9848fe0ad06272dea39a03679ff \ -H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A" \ -H "X-Service-Id: svc_00dddddd000000ccccccssssss" ``` Response ``` HTTP Code: 200 ``` ``` [ { "id": "dvc_01jmpmh9fvxgyym44sqanjr9hs" }, ... ] ``` ## API Notifications ### Notification request payload [Notification payload](#api-notifications-payload) scheduled\_at _optional_ String. [RFC 3339 format](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). Specifies the date and time to schedule the notification for future delivery, up to 30 days in advance. ### Notification payload title String. Max 50 characters. message String. Max 200 characters. link _optional_ String. Valid URL. image\_url _optional_ String. Image url. Image dimension ratio 16/9, up to 3MB. Allowed formats: .gif, .jpg, .png, .webp ### Filter options status _optional_ String. Filter notifications by status: created, queued, completed, failed, skipped device\_id _optional_ String. Filter notifications for a specific device. user\_id _optional_ String. Filter notifications for a specific user. If both device\_id and user\_id are provided, only device\_id is used. ### Pagination parameters limit _optional_ Integer. Default: 50. Min: 1, Max: 100. Maximum number of items to return. after _optional_ String. Cursor ID for pagination — returns items after this ID. * * * ### List notifications Path ``` GET /v1/notifications ``` Request ``` curl -X GET https://api.appio.so/v1/notifications \ -H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A" \ -H "X-Service-Id: svc_00dddddd000000ccccccssssss" ``` Response ``` HTTP Code: 200 ``` ``` { "data": [ { "id": "ntf_01jmpmgb6my0s57c960q1s862v", "service_id": "svc_00dddddd000000ccccccssssss", "status": "completed", "payload": { "link": "https://docs.appio.so", "title": "Notification", "message": "Hello from Appio Docs", "image_url": "https://cdn.appio.so/app/docs.appio.so/banner.jpg" }, "scheduled_at": "2025-03-24T14:23:37.016526Z" }, ... ], "pagination": { "next": "https://api.appio.so/v1/notifications?after=ntf_01jmpmgb6my0s57c960q1s862v" } } ``` * * * ### List delivered notifications Path ``` GET /v1/notifications?status=completed ``` Request ``` curl -X GET https://api.appio.so/v1/notifications?status=completed \ -H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A" \ -H "X-Service-Id: svc_00dddddd000000ccccccssssss" ``` Response ``` HTTP Code: 200 ``` ``` { "data": [ { "id": "ntf_01jmpmgb6my0s57c960q1s862v", "service_id": "svc_00dddddd000000ccccccssssss", "status": "completed", "payload": { "link": "https://docs.appio.so", "title": "Notification", "message": "Hello from Appio Docs", "image_url": "https://cdn.appio.so/app/docs.appio.so/banner.jpg" }, "scheduled_at": "2025-03-24T14:23:37.016526Z" }, ... ], "pagination": { "next": "https://api.appio.so/v1/notifications?status=completed&after=ntf_01jmpmgb6my0s57c960q1s862v" } } ``` * * * ### List notifications for a device Path ``` GET /v1/notifications?device_id={device_id} ``` Request ``` curl -X GET https://api.appio.so/v1/notifications?device_id=dvc_01jmpmh9fvxgyym44sqanjr9hs \ -H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A" \ -H "X-Service-Id: svc_00dddddd000000ccccccssssss" ``` Response ``` HTTP Code: 200 ``` ``` { "data": [ { "id": "ntf_01jmpmgb6my0s57c960q1s862v", "service_id": "svc_00dddddd000000ccccccssssss", "status": "completed", "payload": { "link": "https://docs.appio.so", "title": "Notification", "message": "Hello from Appio Docs", "image_url": "https://cdn.appio.so/app/docs.appio.so/banner.jpg" }, "scheduled_at": "2025-03-24T14:23:37.016526Z" }, ... ], "pagination": { "next": "https://api.appio.so/v1/notifications?device_id=dvc_01jmpmh9fvxgyym44sqanjr9hs&after=ntf_01jmpmgb6my0s57c960q1s862v" } } ``` * * * ### List notifications for a user Path ``` GET /v1/notifications?user_id={user_id} ``` Request ``` curl -X GET https://api.appio.so/v1/notifications?user_id=23d0e9848fe0ad06272dea39a03679ff \ -H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A" \ -H "X-Service-Id: svc_00dddddd000000ccccccssssss" ``` Response ``` HTTP Code: 200 ``` ``` { "data": [ { "id": "ntf_01jmpmgb6my0s57c960q1s862v", "service_id": "svc_00dddddd000000ccccccssssss", "status": "completed", "payload": { "link": "https://docs.appio.so", "title": "Notification", "message": "Hello from Appio Docs", "image_url": "https://cdn.appio.so/app/docs.appio.so/banner.jpg" }, "scheduled_at": "2025-03-24T14:23:37.016526Z" }, ... ], "pagination": { "next": "https://api.appio.so/v1/notifications?user_id=23d0e9848fe0ad06272dea39a03679ff&after=ntf_01jmpmgb6my0s57c960q1s862v" } } ``` * * * ### View notification details View a notification's details, including its sending status. Each notification may be delivered to multiple devices. Path ``` GET /v1/notifications/{id} ``` Request ``` curl -X GET https://api.appio.so/v1/notifications/ntf_01jmpmgb6my0s57c960q1s862v \ -H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A" \ -H "X-Service-Id: svc_00dddddd000000ccccccssssss" ``` Response ``` HTTP Code: 200 ``` ``` { "id": "ntf_01jmpmgb6my0s57c960q1s862v", "service_id": "svc_00dddddd000000ccccccssssss", "status": "completed", "payload": { "link": "https://docs.appio.so", "title": "Notification", "message": "Hello from Appio Docs", "image_url": "https://cdn.appio.so/app/docs.appio.so/banner.jpg" }, "scheduled_at": "2025-03-24T14:23:37.016526Z", "delivery_stats": { "total": 1, "created": 0, "queued": 0, "completed": 1, "failed": 0 } } ``` * * * ### Send a notification to all subscribed devices Path ``` POST /v1/notifications ``` Request ``` curl -X POST https://api.appio.so/v1/notifications \ -H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A" \ -H "Content-Type: application/json" \ -H "X-Service-Id: svc_00dddddd000000ccccccssssss" \ -d '{"payload":{"title":"Notification","message":"Hello from Appio Docs"}}' ``` Request body ``` { "payload": { "title": "Notification", "message": "Hello from Appio Docs" } } ``` Response ``` HTTP Code: 201 ``` ``` { "id": "ntf_01jv7938vhvsccakmeq7c1hcy8" } ``` * * * ### Send a scheduled notification to a user The User's Device must be active. Sends a notification to all active devices belonging to this user. Path ``` POST /v1/notifications?user_id={user_id} ``` Request ``` curl -X POST https://api.appio.so/v1/notifications?user_id=23d0e9848fe0ad06272dea39a03679ff \ -H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A" \ -H "Content-Type: application/json" \ -H "X-Service-Id: svc_00dddddd000000ccccccssssss" \ -d '{"payload":{"title":"Notification","message":"Hello from Appio Docs"},"scheduled_at":"2025-03-24T14:23:37.016526Z"}' ``` Request body ``` { "payload": { "title": "Notification", "message": "Hello from Appio Docs" }, "scheduled_at": "2025-03-24T14:23:37.016526Z" } ``` Response ``` HTTP Code: 201 ``` ``` { "id": "ntf_01jv7akwwbj47rf3je11jgpvvf" } ``` * * * ### Send a notification to a single device The Device has to be active. Path ``` POST /v1/notifications?device_id={device_id} ``` Request ``` curl -X POST https://api.appio.so/v1/notifications?device_id=dvc_01jmpmh9fvxgyym44sqanjr9hs \ -H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A" \ -H "Content-Type: application/json" \ -H "X-Service-Id: svc_00dddddd000000ccccccssssss" \ -d '{"payload":{"title":"Notification","message":"Hello from Appio Docs"}}' ``` Request body ``` { "payload": { "title": "Notification", "message": "Hello from Appio Docs" } } ``` Response ``` HTTP Code: 201 ``` ``` { "id": "ntf_01jmpmgb6my0s57c960q1s862v" } ``` ## API Errors 400 Bad Request The request contains invalid or missing data. Please double-check the API endpoint URL and ensure the request body is correctly formatted and complete. 401 Unauthorized Authentication is required. Ensure that a valid access token is included in the request headers. 403 Forbidden You do not have permission to perform this action. Check that your account has the necessary permissions or roles for this operation. 404 Not Found The requested entity doesn't exist. Verify that the resource identifier is correct, exists, and is currently active. 500 Internal Error Something went wrong while processing your request. Try again later or [contact support](https://appio.so/contact) if the issue persists. ## AI Instructions LLM-friendly content for AI agents is available at [/llms.txt](/llms.txt). OpenAPI definition is available at [/openapi-v1.yaml](/openapi-v1.yaml).