# Subscriptions

The Mirror API allows you to [subscribe to notifications](https://developers.google.com/glass/v1/reference/subscriptions/insert) that are sent when the user takes specific actions on a timeline item or when the user location has been updated.

For a list of [methods](https://developers.google.com/glass/v1/reference/subscriptions#methods) for this resource, see the end of this page.

## Resource representations

A subscription to events on a collection.

```
{
  "kind": "mirror#subscription",
  "id": string,
  "updated": datetime,
  "collection": string,
  "operation": [
    string
  ],
  "callbackUrl": string,
  "verifyToken": string,
  "userToken": string,
  "notification": {
    "collection": string,
    "itemId": string,
    "operation": string,
    "userActions": [
      {
        "type": string,
        "payload": string
      }
    ],
    "verifyToken": string,
    "userToken": string
  }
}
```

| Property name | Value | Description | Notes |
|---|---|---|---|
| `callbackUrl` | `string` | The URL where notifications should be delivered (must start with `https://`). | writable |
| `collection` | `string` | The collection to subscribe to. Allowed values are: - `timeline` - Changes in the timeline including insertion, deletion, and updates. - `locations` - Location updates. - `settings` - Settings updates. | writable |
| `id` | `string` | The ID of the subscription. |   |
| `kind` | `string` | The type of resource. This is always `mirror#subscription`. |   |
| `notification` | `nested object` | Container object for notifications. This is not populated in the `Subscription` resource. |   |
| `notification.collection` | `string` | The collection that generated the notification. |   |
| `notification.itemId` | `string` | The ID of the item that generated the notification. |   |
| `notification.operation` | `string` | The type of operation that generated the notification. <br /> Acceptable values are: - "`DELETE`" - "`INSERT`" - "`MENU_ACTION`" - "`UPDATE`" |   |
| `notification.userActions[]` | `list` | A list of actions taken by the user that triggered the notification. |   |
| `notification.userActions[].payload` | `string` | An optional payload for the action. For actions of type `CUSTOM`, this is the ID of the custom menu item that was selected. |   |
| `notification.userActions[].type` | `string` | The type of action. The value of this can be: - `SHARE` - the user shared an item. - `REPLY` - the user replied to an item. - `REPLY_ALL` - the user replied to all recipients of an item. - `CUSTOM` - the user selected a custom menu item on the timeline item. - `DELETE` - the user deleted the item. - `PIN` - the user pinned the item. - `UNPIN` - the user unpinned the item. - `LAUNCH` - the user initiated a voice command. In the future, additional types may be added. UserActions with unrecognized types should be ignored. |   |
| `notification.userToken` | `string` | The user token provided by the service when it subscribed for notifications. |   |
| `notification.verifyToken` | `string` | The secret verify token provided by the service when it subscribed for notifications. |   |
| `operation[]` | `list` | A list of operations that should be subscribed to. An empty list indicates that all operations on the collection should be subscribed to. Allowed values are: - `UPDATE` - The item has been updated. - `INSERT` - A new item has been inserted. - `DELETE` - The item has been deleted. | writable |
| `updated` | `datetime` | The time at which this subscription was last modified, formatted according to RFC 3339. |   |
| `userToken` | `string` | An opaque token sent to the subscriber in notifications so that it can determine the ID of the user. | writable |
| `verifyToken` | `string` | A secret token sent to the subscriber in notifications so that it can verify that the notification was generated by Google. | writable |

## Methods

[delete](https://developers.google.com/glass/v1/reference/subscriptions/delete)
:   Deletes a subscription.

[insert](https://developers.google.com/glass/v1/reference/subscriptions/insert)
:   Creates a new subscription.

[list](https://developers.google.com/glass/v1/reference/subscriptions/list)
:   Retrieves a list of subscriptions for the authenticated user and service.

[update](https://developers.google.com/glass/v1/reference/subscriptions/update)
:   Updates an existing subscription in place.