{
  "basePath": "",
  "baseUrl": "https://homegraph.googleapis.com/",
  "batchPath": "batch",
  "canonicalName": "Home Graph Service",
  "description": "",
  "discoveryVersion": "v1",
  "documentationLink": "https://developers.google.com/actions/smarthome/create-app#request-sync",
  "fullyEncodeReservedExpansion": true,
  "icons": {
    "x16": "http://www.google.com/images/icons/product/search-16.gif",
    "x32": "http://www.google.com/images/icons/product/search-32.gif"
  },
  "id": "homegraph:v1",
  "kind": "discovery#restDescription",
  "name": "homegraph",
  "ownerDomain": "google.com",
  "ownerName": "Google",
  "parameters": {
    "$.xgafv": {
      "description": "V1 error format.",
      "enum": [
        "1",
        "2"
      ],
      "enumDescriptions": [
        "v1 error format",
        "v2 error format"
      ],
      "location": "query",
      "type": "string"
    },
    "access_token": {
      "description": "OAuth access token.",
      "location": "query",
      "type": "string"
    },
    "alt": {
      "default": "json",
      "description": "Data format for response.",
      "enum": [
        "json",
        "media",
        "proto"
      ],
      "enumDescriptions": [
        "Responses with Content-Type of application/json",
        "Media download with context-dependent Content-Type",
        "Responses with Content-Type of application/x-protobuf"
      ],
      "location": "query",
      "type": "string"
    },
    "callback": {
      "description": "JSONP",
      "location": "query",
      "type": "string"
    },
    "fields": {
      "description": "Selector specifying which fields to include in a partial response.",
      "location": "query",
      "type": "string"
    },
    "key": {
      "description": "API key. Your API key identifies your project and provides you with API access, quota, and reports. Required unless you provide an OAuth 2.0 token.",
      "location": "query",
      "type": "string"
    },
    "oauth_token": {
      "description": "OAuth 2.0 token for the current user.",
      "location": "query",
      "type": "string"
    },
    "prettyPrint": {
      "default": "true",
      "description": "Returns response with indentations and line breaks.",
      "location": "query",
      "type": "boolean"
    },
    "quotaUser": {
      "description": "Available to use for quota purposes for server-side applications. Can be any arbitrary string assigned to a user, but should not exceed 40 characters.",
      "location": "query",
      "type": "string"
    },
    "uploadType": {
      "description": "Legacy upload protocol for media (e.g. \"media\", \"multipart\").",
      "location": "query",
      "type": "string"
    },
    "upload_protocol": {
      "description": "Upload protocol for media (e.g. \"raw\", \"multipart\").",
      "location": "query",
      "type": "string"
    }
  },
  "protocol": "rest",
  "resources": {
    "agentUsers": {
      "methods": {
        "delete": {
          "description": "Unlinks an agent user from Google. As a result, all data related to this\nuser will be deleted.\n\nHere is how the agent user is created in Google:\n\n1.  When a user opens their Google Home App, they can begin linking a 3p\n    partner.\n2.  User is guided through the OAuth process.\n3.  After entering the 3p credentials, Google gets the 3p OAuth token and\n    uses it to make a Sync call to the 3p partner and gets back all of the\n    user's data, including `agent_user_id` and devices.\n4.  Google creates the agent user and stores a mapping from the\n    `agent_user_id` -\u003e Google ID mapping. Google also\n    stores all of the user's devices under that Google ID.\n\nThe mapping from `agent_user_id` to Google ID is many to many, since one\nGoogle user can have multiple 3p accounts, and multiple Google users can\nmap to one `agent_user_id` (e.g., a husband and wife share one Nest account\nusername/password).\n\nThe third-party user's identity is passed in as `agent_user_id`.\nThe agent is identified by the JWT signed by the partner's service account.\n\nNote: Special characters (except \"/\") in `agent_user_id` must be\nURL-encoded.",
          "flatPath": "v1/agentUsers/{agentUsersId}",
          "httpMethod": "DELETE",
          "id": "homegraph.agentUsers.delete",
          "parameterOrder": [
            "agentUserId"
          ],
          "parameters": {
            "agentUserId": {
              "description": "Required. Third-party user ID.",
              "location": "path",
              "pattern": "^agentUsers/.+$",
              "required": true,
              "type": "string"
            },
            "requestId": {
              "description": "Request ID used for debugging.",
              "location": "query",
              "type": "string"
            }
          },
          "path": "v1/{+agentUserId}",
          "response": {
            "$ref": "Empty"
          }
        }
      }
    },
    "devices": {
      "methods": {
        "query": {
          "description": "Gets the device states for the devices in QueryRequest.\nThe third-party user's identity is passed in as `agent_user_id`. The agent\nis identified by the JWT signed by the third-party partner's service\naccount.",
          "flatPath": "v1/devices:query",
          "httpMethod": "POST",
          "id": "homegraph.devices.query",
          "parameterOrder": [],
          "parameters": {},
          "path": "v1/devices:query",
          "request": {
            "$ref": "QueryRequest"
          },
          "response": {
            "$ref": "QueryResponse"
          }
        },
        "reportStateAndNotification": {
          "description": "Reports device state and optionally sends device notifications. Called by\nan agent when the device state of a third-party changes or the agent wants\nto send a notification about the device. See\n[Implement Report State](/actions/smarthome/report-state) for more\ninformation.\nThis method updates a predefined set of states for a device, which all\ndevices have according to their prescribed traits (for example, a light\nwill have the [OnOff](/actions/smarthome/traits/onoff) trait that reports\nthe state `on` as a boolean value).\nA new state may not be created and an INVALID_ARGUMENT code will be thrown\nif so. It also optionally takes in a list of Notifications that may be\ncreated, which are associated to this state change.\n\nThe third-party user's identity is passed in as `agent_user_id`.\nThe agent is identified by the JWT signed by the partner's service account.",
          "flatPath": "v1/devices:reportStateAndNotification",
          "httpMethod": "POST",
          "id": "homegraph.devices.reportStateAndNotification",
          "parameterOrder": [],
          "parameters": {},
          "path": "v1/devices:reportStateAndNotification",
          "request": {
            "$ref": "ReportStateAndNotificationRequest"
          },
          "response": {
            "$ref": "ReportStateAndNotificationResponse"
          }
        },
        "requestSync": {
          "description": "Requests a `SYNC` call from Google to a 3p partner's home control agent for\na user.\n\n\nThe third-party user's identity is passed in as `agent_user_id`\n(see RequestSyncDevicesRequest) and forwarded back to the agent.\nThe agent is identified by the API key or JWT signed by the partner's\nservice account.",
          "flatPath": "v1/devices:requestSync",
          "httpMethod": "POST",
          "id": "homegraph.devices.requestSync",
          "parameterOrder": [],
          "parameters": {},
          "path": "v1/devices:requestSync",
          "request": {
            "$ref": "RequestSyncDevicesRequest"
          },
          "response": {
            "$ref": "RequestSyncDevicesResponse"
          }
        },
        "sync": {
          "description": "Gets all the devices associated with the given third-party user.\nThe third-party user's identity is passed in as `agent_user_id`. The agent\nis identified by the JWT signed by the third-party partner's service\naccount.",
          "flatPath": "v1/devices:sync",
          "httpMethod": "POST",
          "id": "homegraph.devices.sync",
          "parameterOrder": [],
          "parameters": {},
          "path": "v1/devices:sync",
          "request": {
            "$ref": "SyncRequest"
          },
          "response": {
            "$ref": "SyncResponse"
          }
        }
      }
    }
  },
  "revision": "20191106",
  "rootUrl": "https://homegraph.googleapis.com/",
  "schemas": {
    "AgentDeviceId": {
      "description": "Third-party partner's device ID for one device.",
      "id": "AgentDeviceId",
      "properties": {
        "id": {
          "description": "Third-party partner's device ID.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "AgentOtherDeviceId": {
      "description": "Identifies a device in the third party or first party system.",
      "id": "AgentOtherDeviceId",
      "properties": {
        "agentId": {
          "description": "The agent's ID. Generally it is the agent's AoG project id.",
          "type": "string"
        },
        "deviceId": {
          "description": "Device ID defined by the agent. The device_id must be unique.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "Device": {
      "description": "Third-party partner's device definition.",
      "id": "Device",
      "properties": {
        "attributes": {
          "additionalProperties": {
            "description": "Properties of the object.",
            "type": "any"
          },
          "description": "Attributes for the traits supported by the device.",
          "type": "object"
        },
        "customData": {
          "description": "Custom JSON data provided by the manufacturer and attached to QUERY and\nEXECUTE requests in AoG.",
          "type": "string"
        },
        "deviceInfo": {
          "$ref": "DeviceInfo",
          "description": "Device manufacturer, model, hardware version, and software version."
        },
        "id": {
          "description": "Third-party partner's device ID.",
          "type": "string"
        },
        "name": {
          "$ref": "DeviceNames",
          "description": "Name of the device given by the third party. This includes names given to\nthe device via third party device manufacturer's app, model names for the\ndevice, etc."
        },
        "notificationSupportedByAgent": {
          "description": "Indicates whether the device is capable of sending notifications. This\nfield will be set by the agent (partner) on an incoming SYNC. If a device\nis not capable of generating notifications, the partner should set this\nflag to false. If a partner is not capable of calling\nReportStateAndNotification to send notifications to Google, the partner\nshould set this flag to false. If there is a user setting in the partner\napp to enable notifications and it is turned off, the partner should set\nthis flag to false.",
          "type": "boolean"
        },
        "otherDeviceIds": {
          "description": "IDs of other devices associated with this device. This is used to\nrepresent a device group (e.g. bonded zone) or \"facets\" synced\nthrough different flows (e.g. Google Nest Hub Max with a Nest Camera).\n\nThis may also be used to pass in alternate IDs used to identify a cloud\nsynced device for local execution (i.e. local verification). If used for\nlocal verification, this field is synced from the cloud.",
          "items": {
            "$ref": "AgentOtherDeviceId"
          },
          "type": "array"
        },
        "roomHint": {
          "description": "If the third-party partner's cloud configuration includes placing devices\nin rooms, the name of the room can be provided here.",
          "type": "string"
        },
        "structureHint": {
          "description": "As in roomHint, for structures that users set up in the partner's system.",
          "type": "string"
        },
        "traits": {
          "description": "Traits supported by the device.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "type": {
          "description": "Hardware type of the device (e.g. light, outlet, etc).",
          "type": "string"
        },
        "willReportState": {
          "description": "Indicates whether the state of this device is being reported to Google\nthrough ReportStateAndNotification call.",
          "type": "boolean"
        }
      },
      "type": "object"
    },
    "DeviceInfo": {
      "description": "Device information.",
      "id": "DeviceInfo",
      "properties": {
        "hwVersion": {
          "description": "Device hardware version.",
          "type": "string"
        },
        "manufacturer": {
          "description": "Device manufacturer.",
          "type": "string"
        },
        "model": {
          "description": "Device model.",
          "type": "string"
        },
        "swVersion": {
          "description": "Device software version.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "DeviceNames": {
      "description": "Different names for the device.",
      "id": "DeviceNames",
      "properties": {
        "defaultNames": {
          "description": "List of names provided by the partner rather than the user, often\nmanufacturer names, SKUs, etc.",
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        "name": {
          "description": "Primary name of the device, generally provided by the user.",
          "type": "string"
        },
        "nicknames": {
          "description": "Additional names provided by the user for the device.",
          "items": {
            "type": "string"
          },
          "type": "array"
        }
      },
      "type": "object"
    },
    "Empty": {
      "description": "A generic empty message that you can re-use to avoid defining duplicated\nempty messages in your APIs. A typical example is to use it as the request\nor the response type of an API method. For instance:\n\n    service Foo {\n      rpc Bar(google.protobuf.Empty) returns (google.protobuf.Empty);\n    }\n\nThe JSON representation for `Empty` is empty JSON object `{}`.",
      "id": "Empty",
      "properties": {},
      "type": "object"
    },
    "QueryRequest": {
      "description": "Request type for the\n[`Query`](#google.home.graph.v1.HomeGraphApiService.Query) call. This should\nbe the same format as the Actions on Google `action.devices.QUERY`\n[request](/actions/smarthome/create-app#actiondevicesquery) with the\nexception of the extra `agent_user_id` and no `intent` and `customData`\nfields.",
      "id": "QueryRequest",
      "properties": {
        "agentUserId": {
          "description": "Required. Third-party user ID.",
          "type": "string"
        },
        "inputs": {
          "description": "Required. Inputs containing third-party partner's device IDs for which to\nget the device states.",
          "items": {
            "$ref": "QueryRequestInput"
          },
          "type": "array"
        },
        "requestId": {
          "description": "Request ID used for debugging.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "QueryRequestInput": {
      "description": "Device ID inputs to QueryRequest.",
      "id": "QueryRequestInput",
      "properties": {
        "payload": {
          "$ref": "QueryRequestPayload",
          "description": "Payload containing third-party partner's device IDs."
        }
      },
      "type": "object"
    },
    "QueryRequestPayload": {
      "description": "Payload containing device IDs.",
      "id": "QueryRequestPayload",
      "properties": {
        "devices": {
          "description": "Third-party partner's device IDs for which to get the device states.",
          "items": {
            "$ref": "AgentDeviceId"
          },
          "type": "array"
        }
      },
      "type": "object"
    },
    "QueryResponse": {
      "description": "Response type for the\n[`Query`](#google.home.graph.v1.HomeGraphApiService.Query) call. This should\nfollow the same format as the Actions on Google `action.devices.QUERY`\n[response](/actions/smarthome/create-app#actiondevicesquery).\n# Example\n\n```json\n{\n  \"requestId\": \"ff36a3cc-ec34-11e6-b1a0-64510650abcf\",\n  \"payload\": {\n    \"devices\": {\n      \"123\": {\n        \"on\": true,\n        \"online\": true\n      },\n      \"456\": {\n        \"on\": true,\n        \"online\": true,\n        \"brightness\": 80,\n        \"color\": {\n          \"name\": \"cerulean\",\n          \"spectrumRGB\": 31655\n        }\n      }\n    }\n  }\n}\n```",
      "id": "QueryResponse",
      "properties": {
        "payload": {
          "$ref": "QueryResponsePayload",
          "description": "Device states for the devices given in the request."
        },
        "requestId": {
          "description": "Request ID used for debugging. Copied from the request.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "QueryResponsePayload": {
      "description": "Payload containing device states information.",
      "id": "QueryResponsePayload",
      "properties": {
        "devices": {
          "additionalProperties": {
            "additionalProperties": {
              "description": "Properties of the object.",
              "type": "any"
            },
            "type": "object"
          },
          "description": "States of the devices. Map of third-party device ID to struct of device\nstates.",
          "type": "object"
        }
      },
      "type": "object"
    },
    "ReportStateAndNotificationDevice": {
      "description": "The states and notifications specific to a device.",
      "id": "ReportStateAndNotificationDevice",
      "properties": {
        "notifications": {
          "additionalProperties": {
            "description": "Properties of the object.",
            "type": "any"
          },
          "description": "Notifications metadata for devices.",
          "type": "object"
        },
        "states": {
          "additionalProperties": {
            "description": "Properties of the object.",
            "type": "any"
          },
          "description": "States of devices to update.",
          "type": "object"
        }
      },
      "type": "object"
    },
    "ReportStateAndNotificationRequest": {
      "description": "Request type for the\n[`ReportStateAndNotification`](#google.home.graph.v1.HomeGraphApiService.ReportStateAndNotification)\ncall. It may include States, Notifications, or both. This request uses\nglobally unique flattened state names instead of namespaces based on traits\nto align with the existing QUERY and EXECUTE APIs implemented by 90+ Smart\nHome partners. States and notifications are defined per `device_id` (for example, \"123\"\nand \"456\" in the following example). # Example\n```json\n{\n  \"requestId\": \"ff36a3cc-ec34-11e6-b1a0-64510650abcf\",\n  \"agentUserId\": \"1234\",\n  \"payload\": {\n    \"devices\": {\n      \"states\": {\n        \"123\": {\n          \"on\": true\n        },\n        \"456\": {\n          \"on\": true,\n          \"brightness\": 10\n        }\n      },\n    }\n  }\n}\n```",
      "id": "ReportStateAndNotificationRequest",
      "properties": {
        "agentUserId": {
          "description": "Required. Third-party user ID.",
          "type": "string"
        },
        "eventId": {
          "description": "Unique identifier per event (for example, a doorbell press).",
          "type": "string"
        },
        "followUpToken": {
          "description": "Token to maintain state in the follow up notification response.",
          "type": "string"
        },
        "payload": {
          "$ref": "StateAndNotificationPayload",
          "description": "State of devices to update and notification metadata for devices. For\nexample, if a user turns a light on manually, a state update should be\nsent so that the information is always the current status of the device.\nNotifications are independent from the state and its piece of the payload\nshould contain everything necessary to notify the user. Although it may be\nrelated to a state change, it does not need to be. For example, if a\ndevice can turn on/off and change temperature, the states reported would\ninclude both \"on\" and \"70 degrees\" but the 3p may choose not to send any\nnotification for that, or to only say that the \"the room is heating up\",\nkeeping state and notification independent."
        },
        "requestId": {
          "description": "Request ID used for debugging.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "ReportStateAndNotificationResponse": {
      "description": "Response type for the\n[`ReportStateAndNotification`](#google.home.graph.v1.HomeGraphApiService.ReportStateAndNotification)\ncall.",
      "id": "ReportStateAndNotificationResponse",
      "properties": {
        "requestId": {
          "description": "Request ID copied from ReportStateAndNotificationRequest.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "RequestSyncDevicesRequest": {
      "description": "Request type for the\n[`RequestSyncDevices`](#google.home.graph.v1.HomeGraphApiService.RequestSyncDevices)\ncall.",
      "id": "RequestSyncDevicesRequest",
      "properties": {
        "agentUserId": {
          "description": "Required. Third-party user ID issued by agent's third-party identity\nprovider.",
          "type": "string"
        },
        "async": {
          "description": "Optional. If set, the request will be added to a queue and a response will\nbe returned immediately. The queue allows for de-duplication of\nsimultaneous requests.",
          "type": "boolean"
        }
      },
      "type": "object"
    },
    "RequestSyncDevicesResponse": {
      "description": "Response type for the\n[`RequestSyncDevices`](#google.home.graph.v1.HomeGraphApiService.RequestSyncDevices)\ncall. Intentionally empty upon success. An HTTP response code is returned\nwith more details upon failure.",
      "id": "RequestSyncDevicesResponse",
      "properties": {},
      "type": "object"
    },
    "StateAndNotificationPayload": {
      "description": "Payload containing the state and notification information for devices.",
      "id": "StateAndNotificationPayload",
      "properties": {
        "devices": {
          "$ref": "ReportStateAndNotificationDevice",
          "description": "The devices for updating state and sending notifications."
        }
      },
      "type": "object"
    },
    "SyncRequest": {
      "description": "Request type for the [`Sync`](#google.home.graph.v1.HomeGraphApiService.Sync)\ncall. This should follow the same format as the Actions on Google\n`action.devices.SYNC`\n[request](/actions/smarthome/create-app#actiondevicessync) with the exception\nof the extra `agent_user_id` and no `intent` field.",
      "id": "SyncRequest",
      "properties": {
        "agentUserId": {
          "description": "Required. Third-party user ID.",
          "type": "string"
        },
        "requestId": {
          "description": "Request ID used for debugging.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "SyncResponse": {
      "description": "Response type for the\n[`Sync`](#google.home.graph.v1.HomeGraphApiService.Sync) call. This should\nfollow the same format as the Actions on Google `action.devices.SYNC`\n[response](/actions/smarthome/create-app#actiondevicessync).\n# Example\n\n```json\n{\n  \"requestId\": \"ff36a3cc-ec34-11e6-b1a0-64510650abcf\",\n  \"payload\": {\n    \"agentUserId\": \"1836.15267389\",\n    \"devices\": [{\n      \"id\": \"123\",\n      \"type\": \"action.devices.types.OUTLET\",\n      \"traits\": [\n        \"action.devices.traits.OnOff\"\n      ],\n      \"name\": {\n        \"defaultNames\": [\"My Outlet 1234\"],\n        \"name\": \"Night light\",\n        \"nicknames\": [\"wall plug\"]\n      },\n      \"willReportState\": false,\n      \"deviceInfo\": {\n        \"manufacturer\": \"lights-out-inc\",\n        \"model\": \"hs1234\",\n        \"hwVersion\": \"3.2\",\n        \"swVersion\": \"11.4\"\n      },\n      \"customData\": {\n        \"fooValue\": 74,\n        \"barValue\": true,\n        \"bazValue\": \"foo\"\n      }\n    }]\n  }\n}\n```",
      "id": "SyncResponse",
      "properties": {
        "payload": {
          "$ref": "SyncResponsePayload",
          "description": "Devices associated with the third-party user."
        },
        "requestId": {
          "description": "Request ID used for debugging. Copied from the request.",
          "type": "string"
        }
      },
      "type": "object"
    },
    "SyncResponsePayload": {
      "description": "Payload containing device information.",
      "id": "SyncResponsePayload",
      "properties": {
        "agentUserId": {
          "description": "Third-party user ID",
          "type": "string"
        },
        "devices": {
          "description": "Devices associated with the third-party user.",
          "items": {
            "$ref": "Device"
          },
          "type": "array"
        }
      },
      "type": "object"
    }
  },
  "servicePath": "",
  "title": "HomeGraph API",
  "version": "v1",
  "version_module": true
}