# https://docs.appio.so/ llms-full.txt

## Appio Documentation
# 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](https://appio.so/), try our [interactive demo](https://demo.appio.so/), or explore our [case studies](https://appio.so/case-studies).

We also offer no-code [integrations](https://appio.so/integrations).

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

[Mobile APP](https://docs.appio.so/#)

Install code

```html hljs-copy hljs language-xml
<script src="https://cdn.appio.so/v1/appio.js"></script>

<script>
  const appio = Appio("svc_00dddddd000000ccccccssssss")

  function mobileApp() {
    appio.open({
      user: "docs-appio-so:hi@appio.so"
    })
  }
</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](https://my.appio.so/).userYour 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](https://docs.appio.so/#)

Install code

```html hljs-copy hljs language-xml
<script src="https://cdn.appio.so/v1/appio.js"></script>

<a
  data-appio="on"
  data-service="svc_00dddddd000000ccccccssssss"
  data-user="docs-appio-so:hi@appio.so"
  href="#"
>
  Mobile APP
</a>

```

data-appioActivates Appio. The value is optional and can be omitted.data-serviceUse your service ID, which was assigned to you during registration.

Replace \`svc\_\*\*YOUR\*SERVICE\*ID\*\*\` with your [service id](https://my.appio.so/).data-userYour 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](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 hljs-copy hljs
curl https://api.appio.so/hi \
-H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A"

```

Response

```plaintext hljs
HTTP Code: 200
```

```json hljs
👋
```

## API Services

### Service

titleString, max 255 characters.descriptionString, max 1000 characters.logo\_urlSquare image up to 1MB.

Allowed formats: .gif, .jpg, .png, .webp

Max 512 characters long.banner\_urlImage ration 16:9, up to 3MB.

Allowed formats: .gif, .jpg, .png, .webp

Max 512 characters long.urlString, max 512 characters.

### Get service details

Path

```curl hljs
GET /v1/services/{id}
```

Request

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

```

Response

```plaintext hljs
HTTP Code: 200
```

```json hljs
{
    "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

```curl hljs
PATCH /v1/services/{id}
```

Request

```curl hljs-copy hljs
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

```json hljs
{
    "title": "New service title"
}
```

Response

```plaintext hljs
HTTP Code: 200
```

```json hljs
{
    "id": "svc_00dddddd000000ccccccssssss"
}
```

## API Devices

### List of devices subscribed to service

Path

```curl hljs
GET /v1/devices
```

Request

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

```

Response

```plaintext hljs
HTTP Code: 200
```

```json hljs
[\
    {\
        "marketing_name": "iPhone 13",\
        "id": "dvc_01jmpmh9fvxgyym44sqanjr9hs",\
        "user_id": "docs-appio-so:hi@appio.so",\
        "name": "iPhone 13",\
        "platform": "ios",\
        "os_version": "18.3",\
        "model": "iPhone",\
        "device_token": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",\
        "notifications_enabled": true,\
        "device_identifier": "iPhone14,5"\
    },\
    ...\
]
```

* * *

### View device details

Path

```curl hljs
GET /v1/devices/{id}
```

Request

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

```

Response

```plaintext hljs
HTTP Code: 200
```

```json hljs
{
    "marketing_name": "iPhone 13",
    "id": "dvc_01jmpmh9fvxgyym44sqanjr9hs",
    "user_id": "docs-appio-so:hi@appio.so",
    "name": "iPhone 13",
    "platform": "ios",
    "os_version": "18.3",
    "model": "iPhone",
    "device_token": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "notifications_enabled": true,
    "device_identifier": "iPhone14,5"
}
```

* * *

### Deactivate device

Deactivate a device when it should no longer receive notifications or when its associated user has been deactivated.

Path

```curl hljs
DELETE /v1/devices/{id}
```

Request

```curl hljs-copy hljs
curl -X DELETE https://api.appio.so/v1/devices/dvc_01jmpmh9fvxgyym44sqanjr9hs \
-H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A"

```

Response

```plaintext hljs
HTTP Code: 200
```

```json hljs
{
    "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

```curl hljs
DELETE /v1/devices?user_id={user_id}
```

Request

```curl hljs-copy hljs
curl -X DELETE https://api.appio.so/v1/devices?user_id=docs-appio-so%3Ahi%40appio.so \
-H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A"

```

Response

```plaintext hljs
HTTP Code: 200
```

```json hljs
[\
    {\
        "id": "dvc_01jmpmh9fvxgyym44sqanjr9hs"\
    },\
    ...\
]
```

## API Notifications

### Notification request

payload[Notification payload](https://docs.appio.so/#api-notifications-payload)scheduled\_at_optional_

String, date/time to start delivery, in [RFC 3339 format](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6).

Schedule notifications for future delivery, up to 30 days in advance.

### Notification payload

titleString, max 50 characters.messageString, 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, skippeddevice\_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

```curl hljs
GET /v1/notifications
```

Request

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

```

Response

```plaintext hljs
HTTP Code: 200
```

```json hljs
[\
    {\
        "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

```curl hljs
GET /v1/notifications?status=completed
```

Request

```curl hljs-copy hljs
curl -X GET https://api.appio.so/v1/notifications?status=completed \
-H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A"

```

Response

```plaintext hljs
HTTP Code: 200
```

```json hljs
[\
    {\
        "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

```curl hljs
GET /v1/notifications?device_id={device_id}
```

Request

```curl hljs-copy hljs
curl -X GET https://api.appio.so/v1/notifications?device_id=dvc_01jmpmh9fvxgyym44sqanjr9hs \
-H "Authorization: Bearer docs_g3psUMsuKZ7NGGJvuk1csf47pvJfukz97cS5ZrOuHnY98yhY5A"

```

Response

```plaintext hljs
HTTP Code: 200
```

```json hljs
[\
    {\
        "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

```curl hljs
GET /v1/notifications?user_id={user_id}
```

Request

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

```

Response

```plaintext hljs
HTTP Code: 200
```

```json hljs
[\
    {\
        "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

```curl hljs
GET /v1/notifications/{id}
```

Request

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

```

Response

```plaintext hljs
HTTP Code: 200
```

```json hljs
{
    "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

```curl hljs
POST /v1/notifications
```

Request

```curl hljs-copy hljs
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

```json hljs
{
    "payload": {
        "title": "Notification",
        "message": "Hello from Appio Docs"
    }
}
```

Response

```plaintext hljs
HTTP Code: 201
```

```json hljs
{
    "id": "ntf_01jv7938vhvsccakmeq7c1hcy8"
}
```

* * *

### Send a scheduled notification to a user

Sends a notification to all active devices belonging to this user.

Path

```curl hljs
POST /v1/notifications?user_id={user_id}
```

Request

```curl hljs-copy hljs
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":"2025-06-25T09:00:00.000Z"}'

```

Request body

```json hljs
{
    "payload": {
        "title": "Notification",
        "message": "Hello from Appio Docs"
    },
    "scheduled_at": "2025-06-25T09:00:00.000Z"
}
```

Response

```plaintext hljs
HTTP Code: 201
```

```json hljs
{
    "id": "ntf_01jv7akwwbj47rf3je11jgpvvf"
}
```

* * *

### Send a notification to a single device

The Device has to be active.

Path

```curl hljs
POST /v1/notifications?device_id={device_id}
```

Request

```curl hljs-copy hljs
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

```json hljs
{
    "payload": {
        "title": "Notification",
        "message": "Hello from Appio Docs"
    }
}
```

Response

```plaintext hljs
HTTP Code: 201
```

```json hljs
{
    "id": "ntf_01jmpmgb6my0s57c960q1s862v"
}
```

## API Widgets

A widget consists of a template (created via the [WYSIWYG editor](https://my.appio.so/)) and your data source that you link to the template.

### Widget

templateString reference to saved template.sourcedataData source.typeType of data source.

### Create a new widget

Path

```curl hljs
POST /v1/widgets
```

Request

```curl hljs-copy hljs
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

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

Response

```plaintext hljs
HTTP Code: 201
```

```json hljs
{
    "id": "wgt_01jmpr3vt1008txv1jehgdeny7"
}
```

* * *

### View all widgets

Path

```curl hljs
GET /v1/widgets
```

Request

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

```

Response

```plaintext hljs
HTTP Code: 200
```

```json hljs
[\
    {\
        "id": "wgt_01jmpr3vt1008txv1jehgdeny7",\
        "service_id": "svc_00dddddd000000ccccccssssss",\
        "template": "number",\
        "source": {\
            "type": "static",\
            "data": "123"\
        }\
    },\
    ...\
]
```

* * *

### View widget details

Path

```curl hljs
GET /v1/widgets/{id}
```

Request

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

```

Response

```plaintext hljs
HTTP Code: 200
```

```json hljs
{
    "id": "wgt_01jmpr3vt1008txv1jehgdeny7",
    "service_id": "svc_00dddddd000000ccccccssssss",
    "template": "number",
    "source": {
        "type": "static",
        "data": "123"
    }
}
```

* * *

### Update widgets details

Path

```curl hljs
PATCH /v1/widgets/{id}
```

Request

```curl hljs-copy hljs
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

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

Response

```plaintext hljs
HTTP Code: 200
```

```json hljs
{
    "id": "wgt_01jmpr3vt1008txv1jehgdeny7"
}
```

* * *

### Delete widget

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

Path

```curl hljs
DELETE /v1/widgets/{id}
```

Request

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

```

Response

```plaintext hljs
HTTP Code: 200
```

```json hljs
{
    "id": "wgt_01jmpr3vt1008txv1jehgdeny7"
}
```

## API Errors

400Bad 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.401Unauthorized

Authentication is required.

Ensure that a valid access token is included in the request headers.403Forbidden

You do not have permission to perform this action.

Check that your account has the necessary permissions or roles for this operation.404Not Found

The requested entity doesn't exist.

Verify that the resource identifier is correct, exists, and is currently active.409Conflict

The request conflicts with existing data.

Review the request to ensure it does not duplicate or contradict the current state or existing records.500Internal 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](https://docs.appio.so/llms.txt).