Appio documentation

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, try our interactive demo, or explore our case studies.
We also offer no-code integrations.

Found an issue or have feedback? Let us know!

Getting Started

Before getting started, you'll need to create an account and obtain your service_id.
There are two integration options for Appio—both functionally identical.

Option 1

Preview

Mobile APP

Install code

<script src="https://cdn.appio.so/v1/appio.js"></script>

<script>
  const appio = Appio("svc_00dddddd000000ccccccssssss")
  
  function mobileApp() {
    appio.open({
      user: "docs-appio-so:[email protected]"
    })
  }
</script>

<a href="#" onclick="mobileApp()">Mobile APP</a>
Appio("svc_**YOUR*SERVICE*ID**")
Use your service ID, which was assigned to you during registration.
Replace `svc_**YOUR*SERVICE*ID**` with your service id.
user
Your user's identifier. Use a non-sequential and non-predictable string to ensure security.
Suggestion: Combine your customer's unique ID with their email address.

Option 2

Preview

Mobile APP

Install code

<script src="https://cdn.appio.so/v1/appio.js"></script>

<a
  data-appio="on"
  data-service="svc_00dddddd000000ccccccssssss"
  data-user="docs-appio-so:[email protected]"
  href="#"
>
  Mobile APP
</a>
data-appio
Activates Appio. The 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.
data-user
Your user's identifier. Use a non-sequential and non-predictable string to ensure security.
Suggestion: Combine your customer's unique ID with their email address.

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.
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

Service

title
String, max 255 characters.
description
String, max 1000 characters.
logo_url
Square image up to 1MB.
Allowed formats: .gif, .jpg, .png, .webp
Max 512 characters long.
banner_url
Image ration 16:9, up to 3MB.
Allowed formats: .gif, .jpg, .png, .webp
Max 512 characters long.
url
String, max 512 characters.

Get service details

Path

GET /v1/services/{id}

Request

curl -X GET https://api.appio.so/v1/services/svc_00dddddd000000ccccccssssss \
-H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A"

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/"
}

Update service details

Path

PATCH /v1/services/{id}

Request

curl -X PATCH https://api.appio.so/v1/services/svc_00dddddd000000ccccccssssss \
-H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A" \
-H "Content-Type: application/json" \
-d '{"title":"New service title"}'

Request body

{
    "title": "New service title"
}

Response

HTTP Code: 200
{
    "id": "svc_00dddddd000000ccccccssssss"
}

API Devices

List of devices subscribed to service

Path

GET /v1/devices

Request

curl -X GET https://api.appio.so/v1/devices \
-H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A"

Response

HTTP Code: 200
[
    {
        "id": "dvc_01jmpmh9fvxgyym44sqanjr9hs",
        "user_id": "docs-appio-so:[email protected]",
        "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"
    },
    ...
]

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"

Response

HTTP Code: 200
{
    "id": "dvc_01jmpmh9fvxgyym44sqanjr9hs",
    "user_id": "docs-appio-so:[email protected]",
    "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"

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=docs-appio-so%3Ahi%40appio.so \
-H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A"

Response

HTTP Code: 200
[
    {
        "id": "dvc_01jmpmh9fvxgyym44sqanjr9hs"
    },
    ...
]

API Notifications

Notification request

payload
Notification payload
scheduled_at
optional
String, date/time to start delivery, in RFC 3339 format.
Schedule notifications for future delivery, up to 30 days in advance.

Notification payload

title
String, max 50 characters.
message
String, max 200 characters.
link
optional
Valid URL.
image_url
optional
Image ration 16/9, up to 3MB.
Allowed formats: .gif, .jpg, .png, .webp

Filter options

status
optional
Filter notifications by status: created, queued, completed, failed, skipped
device_id
optional
Filter notifications for a specific device.
user_id
optional
Filter notifications for a specific user.

If both device_id and user_id are provided, only device_id is used.

List of notifications

Path

GET /v1/notifications

Request

curl -X GET https://api.appio.so/v1/notifications \
-H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A"

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"
    },
    ...
]

List of 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"

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"
    },
    ...
]

List of 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"

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"
    },
    ...
]

List of notifications for a user

Path

GET /v1/notifications?user_id={user_id}

Request

curl -X GET https://api.appio.so/v1/notifications?user_id=docs-appio-so%3Ahi%40appio.so \
-H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A"

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"
    },
    ...
]

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"

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" \
-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=docs-appio-so%3Ahi%40appio.so \
-H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A" \
-H "Content-Type: application/json" \
-d '{"payload":{"title":"Notification","message":"Hello from Appio Docs"},"scheduled_at":""}'

Request body

{
    "payload": {
        "title": "Notification",
        "message": "Hello from Appio Docs"
    },
    "scheduled_at": ""
}

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" \
-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 Widgets

A widget consists of a template (created via the WYSIWYG editor) and your data source that you link to the template.

Widget

template
String reference to saved template.
source
data
Data source.
type
Type of data source.

Create a new widget

Path

POST /v1/widgets

Request

curl -X POST https://api.appio.so/v1/widgets \
-H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A" \
-H "Content-Type: application/json" \
-d '{"template":"number","source":{"data":"123","type":"static"}}'

Request body

{
    "template": "number",
    "source": {
        "data": "123",
        "type": "static"
    }
}

Response

HTTP Code: 201
{
    "id": "wgt_01jmpr3vt1008txv1jehgdeny7"
}

View all widgets

Path

GET /v1/widgets

Request

curl -X GET https://api.appio.so/v1/widgets \
-H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A"

Response

HTTP Code: 200
[
    {
        "id": "wgt_01jmpr3vt1008txv1jehgdeny7",
        "service_id": "svc_00dddddd000000ccccccssssss",
        "template": "number",
        "source": {
            "type": "static",
            "data": "123"
        }
    },
    ...
]

View widget details

Path

GET /v1/widgets/{id}

Request

curl -X GET https://api.appio.so/v1/widgets/wgt_01jmpr3vt1008txv1jehgdeny7 \
-H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A"

Response

HTTP Code: 200
{
    "id": "wgt_01jmpr3vt1008txv1jehgdeny7",
    "service_id": "svc_00dddddd000000ccccccssssss",
    "template": "number",
    "source": {
        "type": "static",
        "data": "123"
    }
}

Update widgets details

Path

PATCH /v1/widgets/{id}

Request

curl -X PATCH https://api.appio.so/v1/widgets/wgt_01jmpr3vt1008txv1jehgdeny7 \
-H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A" \
-H "Content-Type: application/json" \
-d '{"template":"ring","source":{"data":"65","type":"static"}}'

Request body

{
    "template": "ring",
    "source": {
        "data": "65",
        "type": "static"
    }
}

Response

HTTP Code: 200
{
    "id": "wgt_01jmpr3vt1008txv1jehgdeny7"
}

Delete widget

Delete a widget when you no longer want to offer it to your users.

Path

DELETE /v1/widgets/{id}

Request

curl -X DELETE https://api.appio.so/v1/widgets/wgt_01jmpr3vt1008txv1jehgdeny7 \
-H "Content-Type: application/json" \
-H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A"

Response

HTTP Code: 200
{
    "id": "wgt_01jmpr3vt1008txv1jehgdeny7"
}

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.
409
Conflict
The request conflicts with existing data.
Review the request to ensure it does not duplicate or contradict the current state or existing records.
500
Internal Error
Something went wrong while processing your request.
Try again later or contact support if the issue persists.

AI Instructions

LLM-friendly content for AI agents is available at /llms.txt.