#%RAML 0.8 title: Device API baseUri: https://api.us1.covisint.com/device/v3 protocols: - HTTPS schemas: - resourceReference: | { "id" : "http://api.covisint.com/schema/resourceReference", "$schema" : "http://json-schema.org/draft-04/schema", "description" : "Schema representing links", "type" : "object", "properties" : { "id" : { "type" : "string", "description" : "The unique identifier for the resource.", "required": true }, "type" : { "type" : "string", "description" : "The type of the resource." }, "realm" : { "type" : "string", "description" : "The realm of the resource." } } } - namedResourceReference: "{\n \"id\" : \"http://api.covisint.com/schema/namedScopedResource\",\n \ \"$schema\" : \"http://json-schema.org/draft-04/schema\",\n \"type\" : \"object\",\n \ \"description\" : \"Expands on the basic resource reference and adds internationalized name and description.\",\n \"extends\" : {\n \"$ref\" : \"http://api.covisint.com/schema/resourceReference#\"\n \ },\n \"properties\" : {\n \"name\" : { \n \"description\": \"Internationalized resource name.\",\n \"$ref\" : \"http://api.covisint.com/idm/schema/internationalString#\"\n \ },\n \"description\" : { \n \"description\": \"Internationalized resource description.\",\n \"$ref\" : \"http://api.covisint.com/idm/schema/internationalString#\"\n \ }\n }\n}\n" - resource: | { "id" : "http://api.covisint.com/schema/resource", "$schema" : "http://json-schema.org/draft-04/schema", "description" : "Core schema", "definitions" : { "resource" : { "id" : "resource", "type" : "object", "description" : "A basic resource.", "properties" : { "id" : { "type" : "string", "maxLength" : 64, "description" : "The unique identifier for this resource.", "required": true }, "version": { "type" : "number", "minimum" : 0, "maximum" : 9223372036854775807, "description" : "The current version for this resource. Exists once the resource has been saved. This is mandatory for PUT requests, but should not be supplied for POST requests.", "required": false }, "creator" : { "type" : "string", "maxLength" : 64, "description" : "The creator of this resource. This read-only field is ignored by the server, and is overlayed with the value supplied in the x-requestor header.", "required": true, "readonly": true }, "creatorAppId" : { "type" : "string", "maxLength" : 64, "description" : "The id of the application used to create this resource. This read-only field is ignored by the server, and is overlayed with the value supplied in the x-requestor-app header.", "required": true, "readonly": true }, "creation" : { "type" : "number", "minimum" : 0, "maximum" : 9223372036854775807, "description" : "This read only property is ignored by the server and the system will overlay with the time, in milliseconds since the epoch, when this resource was created.", "required": true, "readonly": true } } } } } - resourceV2: "{\n \"id\" : \"http://api.covisint.com/schema/resourceV2\",\n \"$schema\" : \"http://json-schema.org/draft-04/schema\",\n \"description\" : \"Core schema\",\n \ \"definitions\" : {\n \"resource\" : {\n \"id\" : \"resourceV2\",\n \ \"type\" : \"object\",\n \"description\" : \"A basic resource (version V2).\",\n \"properties\" : {\n \"id\" : {\n \"type\" : \"string\",\n \ \"maxLength\" : 64,\n \"description\" : \"The unique identifier for this resource.\",\n \"required\": true\n },\n \"version\": {\n \"type\" : \"string\",\n \"description\" : \"The current version for this resource. Exists once the resource has been saved. This is mandatory for PUT requests, but should not be supplied for POST requests.\",\n \"required\": false\n },\n \"creator\" : {\n \"type\" : \"string\",\n \ \"maxLength\" : 64,\n \"description\" : \"The creator of this resource. This read-only field is ignored by the server, and is overlayed with the value supplied in the x-requestor header.\",\n \"required\": true,\n \ \"readonly\": true\n },\n \"creatorAppId\" : {\n \"type\" : \"string\",\n \"maxLength\" : 64,\n \"description\" : \"The id of the application used to create this resource. This read-only field is ignored by the server, and is overlayed with the value supplied in the x-requestor-app header.\",\n \"required\": true,\n \"readonly\": true\n },\n \ \"creation\" : {\n \"type\" : \"number\",\n \"minimum\" : 0,\n \"maximum\" : 9223372036854775807,\n \"description\" : \"This read only property is ignored by the server and the system will overlay with the time, in milliseconds since the epoch, when this resource was created.\",\n \ \"required\": true,\n \"readonly\": true\n }\n }\n \ }\n } \n}\n" - realmScopedResource: "{\n \"id\" : \"http://api.covisint.com/schema/realmScopedResource\",\n \ \"$schema\" : \"http://json-schema.org/draft-04/schema\",\n \"type\" : \"object\",\n \ \"description\" : \"Expands on the base resource and adds a realm attribute.\",\n \ \"extends\" : {\n \"$ref\" : \"http://api.covisint.com/schema/resource#\"\n \ },\n \"properties\" : {\n \"realm\" : {\n \"type\" : \"string\",\n \ \"maxLength\" : 25,\n \"pattern\" : \"^[A-Za-z0-9]{2,25}$\",\n \"description\" : \"The realm in which this resource is being created. This read-only field is ignored by the server, and is overlayed with the value supplied in the x-realm header.\",\n \"required\": true,\n \"readonly\": true \n \ }\n }\n}\n" - realmScopedResourceV2: "{\n \"id\" : \"http://api.covisint.com/schema/realmScopedResourceV2\",\n \ \"$schema\" : \"http://json-schema.org/draft-04/schema\",\n \"type\" : \"object\",\n \ \"description\" : \"A realm scoped resource (version V2). Expands on the base resource (version V2) and adds a realm attribute.\",\n \"extends\" : {\n \"$ref\" : \"http://api.covisint.com/schema/resourceV2#\"\n },\n \"properties\" : {\n \ \"realm\" : {\n \"type\" : \"string\",\n \"maxLength\" : 25,\n \"pattern\" : \"^[A-Za-z0-9]{2,25}$\",\n \"description\" : \"The realm in which this resource is being created. This read-only field is ignored by the server, and is overlayed with the value supplied in the x-realm header.\",\n \"required\": true,\n \"readonly\": true \n }\n }\n} \n" - errorResponseSchema: "{\n \"id\" : \"http://api.covisint.com/schema/errorResponseSchema\",\n \ \"$schema\" : \"http://json-schema.org/draft-04/schema\",\n \"type\" : \"object\",\n \ \"description\" : \"Representation of an HTTP 4xx/5xx error response.\",\n \"properties\" : {\n \"status\" : { \n \"type\" : \"number\",\n \"minimum\" : 400,\n \ \"maximum\" : 599,\n \"description\" : \"The HTTP status code.\",\n \ \"required\": true\n },\n \"apiMessage\" : { \n \"type\" : \"string\",\n \ \"description\" : \"A helpful, human-readable description of the error, useful for basic diagnostics.\" \n },\n \"apiStatusCode\" : {\n \"type\" : \"string\",\n \"description\" : \"The API-specific status code.\"\n }\n \ }\n}\n" - serviceCode: "{\n \"id\" : \"http://api.covisint.com/schema/serviceCodes\",\n \"$schema\" : \"http://json-schema.org/draft-04/schema\",\n \"type\": \"object\",\n \"description\": \"The site/service/location codes granted along with a service.\",\n \"properties\": {\n \"code\": { \"type\": \"string\", \"required\": true, \"maxLength\": 200, \"description\": \"The code value.\" },\n \"codeKind\": { \"type\": \"string\", \"required\": true, \"maxLength\": 36, \"description\": \"The associated business unit.\" }\n }\n} \n" - serviceCodes: | { "type" : "array", "description" : "The site/service/location codes granted along with the service, if any.", "items" : { "$ref" : "http://api.covisint.com/schema/serviceCode#"}, "required": false } - address: | { "id" : "http://api.covisint.com/idm/schema/address", "$schema" : "http://json-schema.org/draft-04/schema", "type" : "object", "description" : "A container for the subject's address elements.", "properties" : { "type" : "string", "streets" : { "type" : "array", "description" : "An array of address streets (i.e. address line 1, 2, 3).", "minItems" : 0, "items" : { "type": "string", "maxLength" : 255 } }, "city" : { "type" : "string", "maxLength" : 60, "description" : "The city name." }, "state" : { "type" : "string", "maxLength" : 60, "description" : "The state/province name or code." }, "postal" : { "type" : "string", "maxLength" : 10, "description" : "The postal or zip code." }, "country" : { "type" : "string", "minLength" : 2, "maxLength" : 3, "description" : "The ISO country code. http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2"} } } - phone: "{\n \"id\" : \"http://api.covisint.com/idm/schema/phone\",\n \"$schema\" : \"http://json-schema.org/draft-04/schema\",\n \"type\" : \"object\",\n \"description\" : \"A container for phone number details.\",\n \"properties\" : {\n \"number\" : { \"type\" : \"string\",\"maxLength\" : 100, \"description\" : \"The phone number.\" },\n \"type\" : { \"enum\" : [ \"main\", \"mobile\", \"fax\" ], \"description\" : \"The phone number type.\" }\n },\n \"required\" : [ \"type\" ]\n} \n" - internationalString: | { "id": "http://api.covisint.com/idm/schema/internationalString", "$schema": "http://json-schema.org/draft-04/schema", "type": "array", "description" : "An internationalized string value, supporting one or more language translations.", "minItems": 1, "items": { "type": "object", "properties": { "lang": { "type": "string", "maxLength": 10, "description": "The language or locale in which the text is written." }, "text": { "type": "string", "maxLength": 2000, "description": "The internationalized text value." } } } } - tags: | { "id": "http://api.covisint.com/idm/schema/tag", "$schema": "http://json-schema.org/draft-04/schema", "type": "array", "description" : "The tags associated with a resource. This array is read-only, and may be modified on the resource endpoint with the appropriate tagging APIs.", "minItems": 1, "items": { "type": "object", "properties": { "tagName": { "type": "string", "description": "The tag associated with a resource." } } } } - baseDefinitionResource: "{\n \"id\" : \"http://api.covisint.com/schema/baseDefinitionResource\",\n \ \"$schema\" : \"http://json-schema.org/draft-04/schema\",\n \"type\" : \"object\",\n \ \"description\" : \"A base rule definition(version V1). Expands on the base resource (version V2) and adds a realm attribute.\",\n \"extends\": {\n \"$ref\" : \"http://api.covisint.com/schema/realmScopedResourceV2#\"\n },\n \"properties\": {\n \"name\": {\n \"description\": \"The application name (internationalized).\",\n \ \"required\": true,\n \"$ref\": \"http://api.covisint.com/schema/internationalString#\"\n \ },\n \"description\": {\n \"required\": false,\n \"description\": \"The application description (internationalized).\",\n \"$ref\" : \"http://api.covisint.com/idm/schema/internationalString#\"\n \ }, \n \"properties\":{\n \"type\":\"array\",\n \"description\":\"Properties used by the implementation.\",\n \"required\":false,\n \"minItems\":0,\n \ \"items\":[ \n { \n \"anyOf\": [\n {\n \ \"type\": \"string\",\n \"description\": \"The name of the property.\",\n \"required\": true\n },\n \ {\n \"type\": \"string\",\n \"description\": \"The value of the property.\",\n \"required\": true\n }\n \ ]\n }\n ]\n }\n }\n}\n" - baseActionDefinitionResource: | { "id" : "http://api.covisint.com/schema/baseActionDefinitionResource", "$schema" : "http://json-schema.org/draft-04/schema", "type" : "object", "description" : "A base action action definition. Expands on the base definition resource ", "extends": { "$ref" : "http://api.covisint.com/schema/baseDefinitionResource#" }, "properties": { "type": { "description": "Type of action definition.", "enum": [ "SEND_APPLICATION_NOTIFICATION", "SEND_COMMAND", "SEND_NOTIFICATION" ], "required": true } } } - baseTriggerDefinitionResource: | { "id" : "http://api.covisint.com/schema/baseTriggerDefinitionResource", "$schema" : "http://json-schema.org/draft-04/schema", "type" : "object", "description" : "A base action trigger definition. Expands on the base definition resource ", "extends": { "$ref" : "http://api.covisint.com/schema/baseDefinitionResource#" }, "properties": { "type": { "description": "Type of trigger definition.", "enum": [ "DEVICE_SEND_EVENT", "DEVICE_LIFECYCLE_STATE_CHANGE", "DEVICE_OPERATIONAL_STATE_CHANGE" ], "required": true } } } - devices: | { "id": "http://api.covisint.com/schema/devices", "$schema": "http://json-schema.org/draft-04/schema", "description": "Collection of devices.", "type": "array", "items": { "$ref": "http://api.covisint.com/schema/device#" } } - device: "{\n\"id\": \"http://api.covisint.com/schema/device\",\n\"$schema\": \"http://json-schema.org/draft-04/schema\",\n\"type\": \"object\",\n\"description\": \"Schema representing a device type.\",\n\"extends\": {\n \"$ref\": \"http://api.covisint.com/schema/realmScopedResourceV2#\"\n},\n\"properties\": {\n \"name\": {\n \"description\": \"Name of the device.\",\n \"required\": true,\n \"$ref\": \"http://api.covisint.com/idm/schema/internationalString#\"\n \ },\n \"description\": {\n \"description\": \"Description of the device.\",\n \ \"required\": false,\n \"$ref\": \"http://api.covisint.com/idm/schema/internationalString#\"\n \ },\n \"attributes\": {\n \"type\": \"object\",\n \"description\": \"The list of attributes associated to the device.\",\n \"required\": false,\n \"properties\": {\n \"standard\": {\n \"type\": \"array\",\n \"description\": \"The list of standard attributeTypes associated to the device that are refered from the Device Template used.These attributes only once during device registration.\",\n \ \"items\": {\n \"oneOf\": [\n {\n \"attributeTypeId\": {\n \"type\": \"string\",\n \"description\": \"The attributeType id.\",\n \"required\": true\n }\n },\n \ { \n \"attributeType\": {\n \"description\": \"The full attribute type definition.\",\n \"$ref\": \"http://api.covisint.com/schema/attributeType#\" \n }\n }\n ],\n \"value\": {\n \"type\": \"any\",\n \"description\": \"The attribute value.\",\n \"required\": false\n }\n }\n },\n \"extended\": {\n \"type\": \"array\",\n \"description\": \"The list of attributes associated directly to the device,not available with the device template used.These attribute value can be change mutiple time during device lifetime.\",\n \"items\": {\n \ \"oneOf\": [\n {\n \"attributeTypeId\": {\n \ \"type\": \"string\",\n \"description\": \"The attributeType id.\",\n \"required\": true\n }\n },\n \ { \n \"attributeType\": {\n \"description\": \"The full attribute type definition.\",\n \"$ref\": \"http://api.covisint.com/schema/attributeType#\" \n }\n }\n ],\n \"value\": {\n \"type\": \"any\",\n \"description\": \"The attribute value.\",\n \"required\": false\n }\n }\n }\n }\n },\n \"observableEvents\": {\n \ \"type\": \"array\",\n \"description\": \"The list of event ids that can be observed or generated by the device.\",\n \"required\": false,\n \"minItems\": 1,\n \"items\": {\n \"type\": \"string\",\n \"description\": \"The id of the device generated event that can be observed in IOT Core Platform.\"\n \ }\n },\n \"supportedCommands\": {\n \"type\": \"array\",\n \"description\": \"The list of commands ids supported by the device.\",\n \"required\": false,\n \ \"minItems\": 1,\n \"items\": {\n \"type\": \"string\",\n \"description\": \"The id of the command supported by the device.\"\n }\n },\n \"parentDeviceTemplateId\": {\n \"type\": \"string\",\n \"required\": true,\n \"description\": \"The id of the device template used or being refered to create the device.\"\n },\n \ \"state\": {\n \"type\": \"object\",\n \"description\": \"The lifecycle and operational state of the device.\",\n \"required\": true,\n \"properties\": {\n \"lifecycleState\": {\n \"description\": \"Valid lifecycle states of device.\",\n \"enum\": [\n \"CREATED\",\n \"PENDING_ACTIVATION\",\n \ \"ACTIVE\",\n \"LOCKED\",\n \"SUSPENDED\",\n \"DELETED\"\n \ ],\n \"required\": true,\n \"readOnly\": true\n },\n \ \"operationalState\": {\n \"description\": \"Valid operational states of the device.\",\n \"enum\": [\n \"STANDBY\",\n \"ONLINE\",\n \ \"OFFLINE\"\n ],\n \"required\": true,\n \"readOnly\": true\n }\n }\n },\n \"isActive\": {\n \"type\": \"boolean\",\n \"description\": \"Whether or not device is active.\",\n \"required\": true,\n \"default\": false,\n \"readOnly\": true\n },\n \"tags\": {\n \"description\": \"The list of tags associated to the device.\",\n \"required\": false,\n \"$ref\": \"http://api.covisint.com/idm/schema/tags#\",\n \"readOnly\": true\n }\n }\n}\n" - deviceHistory: "{\n \"$schema\": \"http://json-schema.org/draft-04/schema#\",\n \ \"id\": \"http://api.covisint.com/schema/deviceHistory\",\n \"type\": \"array\",\n \ \"items\": {\n \"id\": \"http://api.covisint.com/schema/deviceHistory/0\",\n \ \"type\": \"object\",\n \"properties\": {\n \"deviceId\": {\n \"type\": \"string\",\n \"maxLength\": 64,\n \"required\": true,\n \"description\": \"The unique identifier for this device.\"\n },\n \"timestamp\": {\n \ \"type\": \"number\",\n \"minimum\": 0,\n \"maximum\": 9223372036854775807,\n \ \"required\": true,\n \"description\": \"The time of event.\"\n \ },\n \"stateType\": {\n \"type\": \"string\",\n \"maxLength\": 64,\n \"required\": false,\n \"description\": \"The type of device state.\"\n },\n \"fromState\": {\n \"type\": \"string\",\n \"maxLength\": 64,\n \"required\": false,\n \"description\": \"The old device state.\"\n \ },\n \"toState\": {\n \"type\": \"string\",\n \"maxLength\": 64,\n \"required\": false,\n \"description\": \"The new device state.\"\n \ },\n \"requestorId\": {\n \"type\": \"string\",\n \"maxLength\": 64,\n \"required\": true,\n \"description\": \"The requestor of this record.\"\n },\n \"fromDeviceTemplateId\": {\n \"type\": \"string\",\n \"maxLength\": 64,\n \"required\": false,\n \"description\": \"The device template id before device template migration.\"\n },\n \"toDeviceTemplateId\": {\n \"type\": \"string\",\n \"maxLength\": 64,\n \"required\": false,\n \"description\": \"The device template id after device template migration.\"\n },\n \"fromStandardAttributes\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"required\": false,\n \"description\": \"The device standard attributes before device template migration.\",\n \"items\": {\n \"type\": \"string\",\n \"description\": \"The id of the device standard attribute.\"\n }\n },\n \"toStandardAttributes\": {\n \"type\": \"array\",\n \"minItems\": 1,\n \"required\": false,\n \"description\": \"The device standard attributes after device template migration.\",\n \"items\": {\n \"type\": \"string\",\n \ \"description\": \"The id of the device standard attribute.\"\n }\n \ }\n }\n }\n} \n\t \n" traits: - secured: usage: Apply this to any method that needs to be secured. Requests with this trait require authentication using a bearer token. headers: Authorization: description: Access token that is obtained from the /token endpoint of the oauth API. pattern: "^Bearer .*$" example: Bearer ZCtYUGpYRXpET0JvVE1rZzlWV3I1Yk required: true responses: 401: &6 description: Unauthenticated request. This is returned if the access token is missing, invalid, or expired. Access tokens are obtained through the /token endpoint of the Oauth API. body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema 403: &7 description: Unauthorized request. The requestor is not authorized to perform the requested operation. body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema - unsecured: usage: Apply this to any method that needs to be unsecured. Requests with this trait does not require any authentication. headers: SolutionInstanceId: description: The solution instance id. example: ZCtYUGpYRXpET0JvVE1rZzlWV3I1Yk required: true responses: 400: description: Bad request. Please provide the valid solution instance id. body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema - getResponse: responses: 404: &3 description: | The URI requested is invalid or the resource requested does not exist. ___ Substatus codes and error messages are mentioned below: + (If a resource id is a URI parameter) framework:resource:missing - A resource with the following ID was not found: {resourceId} + No message for an invalid URI body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema 406: &1 description: | Unable to produce content of specified 'Accept' media type ___ Substatus codes and error messages are mentioned below: + framework:request:unsupported:mediatype - The server is unable to produce content of type {acceptMediaType} body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema 500: &2 description: | An unknown server error occurred ___ Substatus codes and error messages are mentioned below: + framework:unknown body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema - getSearchResponse: responses: 406: *1 500: *2 - postResponse: responses: 406: *1 415: &4 description: | Unable to consume content of specified 'Content-Type' media type ___ Substatus codes and error messages are mentioned below: + framework:request:unsupported:mediatype - The server is unable to consume content of type {contentMediaType} body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema 500: *2 - deleteResponse: responses: 500: *2 - putResponse: responses: 404: *3 406: *1 409: &5 description: | There is a conflict in identifying the resource being acted on. There are two categories. (1) The unique identifier in the URL and in the body are different. (2) The current version of the resource being updated and the version sent in the body of the request. This may be an indication that the resource has changed since the client loaded it. The conflict should be resolved and the update resubmitted with the current version of the resource. + framework:resource:conflict + framework:resource:conflict:id - The ID of the resource in the request, {requestedId}, does not match the ID of the given resource, {resourceId} + framework:resource:conflict:version - The version of the provided resource, {requestVersion}, does not match the current version of the resource, {latestVersion} body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema 415: *4 500: *2 - putResponseV2: responses: 404: *3 406: *1 409: description: | There is a conflict in identifying the resource being acted on. The unique identifier in the URL and body are different. + framework:resource:conflict + framework:resource:conflict:id - The ID of the resource in the request, {requestedId}, does not match the ID of the given resource, {resourceId} body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema 415: *4 500: *2 - putCreateResponse: responses: 406: *1 409: *5 415: *4 500: *2 - taskResponse: responses: 401: *6 403: *7 500: *2 - pagableRequest: queryParameters: page: description: Which page to return in the paginated results. The first page is page 1. type: integer required: false minimum: 1 default: 1 pageSize: description: How many items per page in the paginated results. type: integer required: false minimum: 1 default: 50 maximum: 200 - taggable: queryParameters: tag: description: Get the resource based on specified tag. Multiple parameters are allowed and the search results will be a union. type: string required: false - sortable: queryParameters: sortBy: description: Sort the results based on some criteria. example: +creation, -name (These will sort by creation ascending, name descending. If "+/-" prefix is omitted, then an ascending sort is assumed). type: string required: false - searchable: description: Search resources based on the given filter parameters. Search is case-insensitive. <> <> "/devices": description: Collection endpoint for devices. get: is: - searchable: since: '' entitlement: "[Entitlement:device-search-devices]" - pagableRequest - sortable - taggable - getSearchResponse - secured description: Search devices in the realm based on the specified query parameters. headers: Accept: description: The media type for v1 devices. Specify parameter fetchattributetypes with a value of true to return the full attribute type information nested within the device resource, opposed to just the attribute type id being returned. Specify parameter fetcheventtemplates with a value of true to return the full event template information nested within the device resource, opposed to just the event template id being returned. Specify parameter fetchcommandtemplates with a value of true to return the full command template information nested within the device resource, opposed to just the command template id being returned. example: application/vnd.com.covisint.platform.device.v2+json;fetchattributetypes=true;fetcheventtemplates=true;fetchcommandtemplates=true type: string required: true queryParameters: id: description: Retrieve devices with the specified id. Multiple parameters are allowed and the search results will be a union. type: string required: false parentDeviceTemplateId: description: Retrieve devices based on the specified device template. Search results will be a union when multiple parameters are provided. type: string required: false name: description: Retrieve devices with the specified name. Multiple parameters are allowed and the search results will be a union. type: string required: false description: description: Retrieve devices with the specified description. Multiple parameters are allowed and the search results will be a union. type: string required: false state.lifecycleState: description: Retrieve devices in the specified lifecycle state. Multiple parameters are allowed and the search results will be a union. type: string required: false state.operationalState: description: Retrieve devices in the specified operational state. Multiple parameters are allowed and the search results will be a union. type: string required: false active: description: Retrieve devices that are either active or inactive. type: boolean required: false tag: description: Retrieve devices with the given tag value. Multiple parameters are allowed and the search results will be a union. type: boolean required: false default: true standardAttributes.attributeType.id: description: Retrieve devices referencing a standard attribute type of the given attribute type id. Multiple parameters are allowed and the search results will be a union. type: string required: false extendedAttributes.attributeType.id: description: Retrieve devices referencing a extended attribute type of the given attribute type id. Multiple parameters are allowed and the search results will be a union. type: string required: false observableEvents.id: description: Retrieve devices referencing an event of the given event id. Multiple parameters are allowed and the search results will be a union. type: string required: false supportedCommands.id: description: Retrieve devices referencing a command of the given command id. Multiple parameters are allowed and the search results will be a union. type: string required: false sortBy: description: Sort the search results. type: string required: false enum: - "+creation" - "-creation" - "+state" - "-state" responses: 200: description: All devices that satisfy the query parameters were successfully retrieved (response collection may be empty). body: application/vnd.com.covisint.platform.device.v2+json: schema: devices 400: description: "There was a problem with the client's request\n___ \nSubstatus codes and error messages are mentioned below:\n + framework:request:io:read - There was an error while reading the request body.\n + framework:request:io:read:parsing - Invalid input. There was a error while parsing the request body.\n + framework:request:header:missing - Missing request header: {headerName}\n \ + framework:request:param:missing - Missing query parameters: {paramName}\n \ + framework:request:data:missing - The following information was missing from the resource: {resourceFieldName(s)}\n + framework:request:invalid:header:value - Invalid x-requester header value. Valid values are [person, application] \ \n" body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema 500: description: | An unhandled server-side error occurred. body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema "/count": description: Endpoint to return the count of devices that match the given query criteria. get: is: - taggable - getSearchResponse - secured description: Retrieve count of devices based on the specified query parameters. headers: Accept: description: Media type. example: text/plain type: string required: true queryParameters: id: description: Retrieve count of devices with the specified id. Multiple parameters are allowed and the search results will be a union. type: string required: false parentDeviceTemplateId: description: Retrieve devices based on the specified device template. Search results will be a union when multiple parameters are provided. type: string required: false name: description: Retrieve count of devices with the specified name. Multiple parameters are allowed and the search results will be a union. type: string required: false description: description: Retrieve count of devices with the specified description. Multiple parameters are allowed and the search results will be a union. type: string required: false state.lifecycleState: description: Retrieve count of devices in the specified lifecycle state. Multiple parameters are allowed and the search results will be a union. type: string required: false state.operationalState: description: Retrieve count of devices in the specified operational state. Multiple parameters are allowed and the search results will be a union. type: string required: false active: description: Retrieve devices that are either active or inactive. type: boolean required: false tag: description: Retrieve count of devices with the given tag value. Multiple parameters are allowed and the search results will be a union. type: boolean required: false default: true standardAttributes.attributeType.id: description: Retrieve count of devices referencing a standard attribute type of the given attribute type id. Multiple parameters are allowed and the search results will be a union. type: string required: false extendedAttributes.attributeType.id: description: Retrieve count of devices referencing a extended attribute type of the given attribute type id. Multiple parameters are allowed and the search results will be a union. type: string required: false observableEvents.id: description: Retrieve count of devices referencing an event of the given event id. Multiple parameters are allowed and the search results will be a union. type: string required: false supportedCommands.id: description: Retrieve count of devices referencing a command of the given command id. Multiple parameters are allowed and the search results will be a union. type: string required: false responses: 200: description: The number of matching devices were returned. body: plain/text: 400: description: "There was a problem with the client's request.\n ___ \nSubstatus codes and error messages are mentioned below:\n+ framework:request\n+ framework:request:header:missing - Missing request header: {headerName} \ \n+ framework:request:data:missing - The following information was missing from the resource: {resourceFieldName(s)}\n+ framework:request:invalid:header:value - Invalid x-requestor header value. Valid values are [person, application] \ \n" body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema "/history": description: Endpoint for an individual device history. get: is: - searchable: since: '' entitlement: "[Entitlement:device-get-history]" - pagableRequest description: Retrieve device state change history for a specific device headers: Accept: description: The media type for v1 device history. example: application/vnd.com.covisint.platform.device.history.v1+json type: string required: true queryParameters: id: description: Retrieve device history for the specified device. id. type: string required: true facet: description: Retrieve device history for the specified facet. Can be any of - "all", "lifecycle", "operational" or "deviceTemplateMigration" type: string required: true fromTime: description: Retrieve device history for the specified from time in milliseconds since the epoch. type: number required: false toTime: description: Retrieve device history for the specified to time in milliseconds since the epoch. type: number required: false fromState: description: Retrieve device history for the specified from state. type: string required: false toState: description: Retrieve device history for the specified to state. type: string required: false fromTemplate: description: Retrieve device history for the specified from template. type: string required: false toTemplate: description: Retrieve device history for the specified to template. type: string required: false responses: 200: description: All of the device's history that satisfy the query parameters were successfully retrieved (response collection may be empty). body: application/vnd.com.covisint.platform.device.history.v1+json: schema: deviceHistory 400: description: "There was a problem with the client's request\n___ \nSubstatus codes and error messages are mentioned below:\n + framework:request:io:read - There was an error while reading the request body.\n + framework:request:io:read:parsing - Invalid input. There was a error while parsing the request body.\n \ + framework:request:header:missing - Missing request header: {headerName}\n \ + framework:request:param:missing - Missing query parameters: {paramName}\n \ + framework:request:data:missing - The following information was missing from the resource: {resourceFieldName(s)}\n + framework:request:invalid:header:value - Invalid x-requester header value. Valid values are [person, application] \ \n" body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema 500: description: | An unhandled server-side error occurred. body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema. "/{deviceId}": description: Endpoint for an individual device. uriParameters: deviceId: description: id of the device. type: string get: description: Retrieve the specified device based on its unique id. headers: Accept: description: The media type for v1 devices. Specify parameter fetchattributetypes with a value of true to return the full attribute type information nested within the device resource, opposed to just the attribute type id being returned. Specify parameter fetcheventtemplates with a value of true to return the full event template information nested within the device resource, opposed to just the event template id being returned. Specify parameter fetchcommandtemplates with a value of true to return the full command template information nested within the device resource, opposed to just the command template id being returned. example: application/vnd.com.covisint.platform.device.v2+json;fetchattributetypes=true;fetcheventtemplates=true;fetchcommandtemplates=true type: string required: true is: - getResponse - secured responses: 200: description: Successfully retrieved the requested device. body: application/vnd.com.covisint.platform.device.v2+json: schema: device 400: description: "There was a problem with the client's request.\n___ \nSubstatus codes and error messages are mentioned below:\n + framework:request:io:read - There was an error while reading the request body.\n + framework:request:io:read:parsing - Invalid input. There was a error while parsing the request body.\n \ + framework:request:header:missing - Missing request header: {headerName}.\n \ + framework:request:data:missing - The following information was missing from the resource: {resourceFieldName(s)}\n + framework:request:invalid:header:value - Invalid x-requester header value. Valid values are [person, application] \ \n" body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema 500: description: | An unhandled server-side error occurred. body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema put: description: Updates the requested device. Throws an error if the device doesn't already exist. headers: Accept: description: Media type example: application/vnd.com.covisint.platform.device.v2+json type: string required: true Content-Type: description: The content type example: application/vnd.com.covisint.platform.device.v2+json type: string required: true is: - putResponseV2 - secured body: application/vnd.com.covisint.platform.device.v2+json: schema: device responses: 200: description: Successfully updated the device. body: application/vnd.com.covisint.platform.device.v2+json: schema: device 400: description: "There was a problem with the client's request\n___ \nSubstatus codes and error messages are mentioned below:\n+ framework:request:io:read - There was an error while reading the request body.\n+ framework:request:io:read:parsing - Invalid input. There was a error while parsing the request body.\n+ framework:request:header:missing - Missing request header: {headerName}\n+ framework:request:data:missing - The following information was missing from the resource: {resourceFieldName(s)}\n+ framework:request:invalid:header:value - Invalid x-requester header value. Valid values are [person, application] \ \n" body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema 500: description: | An unhandled server-side error occurred. body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema "/tags/{tag}": description: Device tags endpoint. uriParameters: tag: description: The tag value. minLength: 1 maxLength: 2000 required: true type: string put: description: Tags the specified device. is: - secured responses: 204: description: The tag was successfully added. 404: description: The device did not exist. body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema 400: description: "There was a problem with the client's request.\n___ \nSubstatus codes and error messages are mentioned below:\n+ framework:request:io:read - There was an error while reading the request body.\n+ framework:request:io:read:parsing - Invalid input. There was a error while parsing the request body.\n+ framework:request:header:missing - Missing request header: {headerName}\n+ framework:request:data:missing - The following information was missing from the resource: {resourceFieldName(s)}\n+ framework:request:invalid:header:value - Invalid x-requester header value. Valid values are [person, application] \ \n" 500: description: An unhandled error occurred on the server. body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema delete: description: Removes a tag from the device. is: - secured responses: 204: description: The tag was successfully removed. 400: description: "There was a problem with the client's request.\n___ \nSubstatus codes and error messages are mentioned below:\n+ framework:request:io:read - There was an error while reading the request body.\n+ framework:request:io:read:parsing - Invalid input. There was a error while parsing the request body.\n+ framework:request:header:missing - Missing request header: {headerName}\n+ framework:request:data:missing - The following information was missing from the resource: {resourceFieldName(s)}\n+ framework:request:invalid:header:value - Invalid x-requester header value. Valid values are [person, application] \ \n" 404: description: The specified tag was not associated to the device, or the device did not exist. body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema 500: description: An unhandled error occurred on the server. body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema "/tasks/activate": post: description: Activates the device. headers: is: - secured responses: 204: description: Device sucessfully activated. 400: description: "There was a problem with the client's request\n ___ \n \ Substatus codes and error messages are mentioned below:\n+ framework:request:io:read - There was an error while reading the request body.\n+ framework:request:io:read:parsing - Invalid input. There was a error while parsing the request body.\n+ framework:request:header:missing - Missing request header: {headerName}\n+ framework:request:data:missing - The following information was missing from the resource: {resourceFieldName(s)}\n+ framework:request:invalid:header:value - Invalid x-requester header value. Valid values are [person, application]\n" body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema 500: description: | An unhandled server-side error occurred. body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema "/tasks/deactivate": post: description: Deactivates the device. headers: is: - secured responses: 204: description: Device sucessfully deactivated. 400: description: "There was a problem with the client's request.\n ___ \n \ Substatus codes and error messages are mentioned below:\n+ framework:request:io:read - There was an error while reading the request body.\n+ framework:request:io:read:parsing - Invalid input. There was a error while parsing the request body.\n+ framework:request:header:missing - Missing request header: {headerName}\n+ framework:request:data:missing - The following information was missing from the resource: {resourceFieldName(s)}\n+ framework:request:invalid:header:value - Invalid x-requester header value. Valid values are [person, application]\n" body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema 500: description: | An unhandled server-side error occurred. body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema "/tasks/register": post: description: Register the device and set the lifecycle state to Active. Returns security token. headers: is: - secured responses: 200: description: The device has been registered. Response JSON will contain a single string property named 'token' that return the JWT token. body: application/json: 400: description: "There was a problem with the client's request\n ___ \n \ Substatus codes and error messages are mentioned below:\n+ framework:request:io:read - There was an error while reading the request body.\n+ framework:request:io:read:parsing - Invalid input. There was a error while parsing the request body.\n+ framework:request:header:missing - Missing request header: {headerName}\n+ framework:request:data:missing - The following information was missing from the resource: {resourceFieldName(s)}\n+ framework:request:invalid:header:value - Invalid x-requester header value. Valid values are [person, application]\n" body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema 500: description: | An unhandled server-side error occurred. body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema "/tasks/suspend": post: description: Suspend device operation. headers: is: - secured queryParameters: reason: description: Reason to suspend the device. responses: 204: description: Device sucessfully suspended. 400: description: "There was a problem with the client's request\n ___ \n \ Substatus codes and error messages are mentioned below:\n+ framework:request:io:read - There was an error while reading the request body.\n+ framework:request:io:read:parsing - Invalid input. There was a error while parsing the request body.\n+ framework:request:header:missing - Missing request header: {headerName}\n+ framework:request:data:missing - The following information was missing from the resource: {resourceFieldName(s)}\n+ framework:request:invalid:header:value - Invalid x-requester header value. Valid values are [person, application]\n" body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema 500: description: | An unhandled server-side error occurred. body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema "/tasks/unsuspend": post: description: Unsuspend device and resume operation. headers: is: - secured queryParameters: reason: description: Reason to unsuspend the device. responses: 204: description: Device sucessfully unsuspended. 400: description: "There was a problem with the client's request\n ___ \n \ Substatus codes and error messages are mentioned below:\n+ framework:request:io:read - There was an error while reading the request body.\n+ framework:request:io:read:parsing - Invalid input. There was a error while parsing the request body.\n+ framework:request:header:missing - Missing request header: {headerName}\n+ framework:request:data:missing - The following information was missing from the resource: {resourceFieldName(s)}\n+ framework:request:invalid:header:value - Invalid x-requester header value. Valid values are [person, application]\n" body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema 500: description: | An unhandled server-side error occurred. body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema "/tasks/unlock": post: description: unlocks the device. headers: is: - secured queryParameters: reason: description: Reason to unlock the device. responses: 204: description: Device sucessfully unlocked. 400: description: "There was a problem with the client's request\n ___ \n \ Substatus codes and error messages are mentioned below:\n+ framework:request:io:read - There was an error while reading the request body.\n+ framework:request:io:read:parsing - Invalid input. There was a error while parsing the request body.\n+ framework:request:header:missing - Missing request header: {headerName}\n+ framework:request:data:missing - The following information was missing from the resource: {resourceFieldName(s)}\n+ framework:request:invalid:header:value - Invalid x-requester header value. Valid values are [person, application]\n" body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema 500: description: | An unhandled server-side error occurred. body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema "/tasks/delete": post: description: Set the device lifecycle state to deleted. headers: is: - secured queryParameters: reason: description: Reason to delete a device. responses: 204: description: Device sucessfully deleted. 400: description: "There was a problem with the client's request\n ___ \n \ Substatus codes and error messages are mentioned below:\n+ framework:request:io:read - There was an error while reading the request body.\n+ framework:request:io:read:parsing - Invalid input. There was a error while parsing the request body.\n+ framework:request:header:missing - Missing request header: {headerName}\n+ framework:request:data:missing - The following information was missing from the resource: {resourceFieldName(s)}\n+ framework:request:invalid:header:value - Invalid x-requester header value. Valid values are [person, application]\n" body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema 500: description: | An unhandled server-side error occurred. body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema "/tasks/reset": post: description: Reset the device and set the lifecycle state to Pending Activation. headers: is: - secured responses: 204: description: Device sucessfully reset. 400: description: "There was a problem with the client's request\n ___ \n \ Substatus codes and error messages are mentioned below:\n+ framework:request:io:read - There was an error while reading the request body.\n+ framework:request:io:read:parsing - Invalid input. There was a error while parsing the request body.\n+ framework:request:header:missing - Missing request header: {headerName}\n+ framework:request:data:missing - The following information was missing from the resource: {resourceFieldName(s)}\n+ framework:request:invalid:header:value - Invalid x-requester header value. Valid values are [person, application]\n" body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema 500: description: | An unhandled server-side error occurred. body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema "/tasks/createDeviceFromTemplate": post: description: Create a new device based on the given deviceTemplateId. headers: Accept: description: Media type. example: application/vnd.com.covisint.platform.device.v2+json type: string required: true is: - postResponse - secured queryParameters: deviceTemplateId: description: The id of the device template on which to model the device. responses: 201: description: Successfully created a new device, which is returned in the response entity body. body: application/vnd.com.covisint.platform.device.v2+json: schema: device 400: description: "There was a problem with the client's request.\n___ \nSubstatus codes and error messages are mentioned below:\n+ framework:request:io:read - There was an error while reading the request body.\n+ framework:request:io:read:parsing - Invalid input. There was a error while parsing the request body.\n+ framework:request:header:missing - Missing request header: {headerName}\n+ framework:request:data:missing - The following information was missing from the resource: {resourceFieldName(s)}\n+ framework:request:invalid:header:value - Invalid x-requester header value. Valid values are [person, application]\n" body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema 500: description: | An unhandled server-side error occurred. body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema "/tasks/migrateDeviceToNewTemplate": post: description: Upgrade the device with the latest version of its device template. This syncs the standard attributes, events and commands of device with current device template version. headers: Accept: description: Media type. example: application/vnd.com.covisint.platform.device.v2+json type: string required: true is: - postResponse - secured queryParameters: deviceTemplateId: description: The id of the new parent device template. deviceId: description: The device ids to upgrade. responses: 201: description: Sucessfully updated the specified device(s) to the requested parent template and the new device is returned in the body. body: application/vnd.com.covisint.platform.device.v2+json: schema: device 400: description: "There was a problem with the client's request\n ___ \n \ Substatus codes and error messages are mentioned below:\n+ framework:request:io:read - There was an error while reading the request body.\n+ framework:request:io:read:parsing - Invalid input. There was a error while parsing the request body.\n+ framework:request:header:missing - Missing request header: {headerName}\n+ framework:request:data:missing - The following information was missing from the resource: {resourceFieldName(s)}\n+ framework:request:invalid:header:value - Invalid x-requester header value. Valid values are [person, application]\n" body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema 500: description: | An unhandled server-side error occurred. body: application/vnd.com.covisint.error.v1+json: schema: errorResponseSchema