Documentation

Documentation

YourOwn SetupYourOwn SDKYourOwn API
Sphere SetupSphere SDKSphere API
  • Resources

›Reference

Introduction

  • Copilot.cx Management API

Getting Started

  • Configuration
  • Hello copilot

Reference

  • Session Management
  • User
  • Thing
  • End User Authentication
  • Collect API
  • Collect payload

    • Thing events
    • Custom events
    • Misc. events

Appendix

  • Releases

Thing

Get Things - fetch the first page

Use the API GET /v2/api/management/copilot_connect/things to get your Things. The response will be paginated.

Url

GET https://<BASE_URL>/v2/api/management/copilot_connect/things

Headers

Authorization: <TOKEN_TYPE> <ACCESS_TOKEN>
Content-Type: application/json

Creating Authorization token - see Session Management

Query Parameters

order_by - (optional) if included,should be set to updatedAt

order_direction - (optional) if included, should be set to asc or desc. The default is desc.

In case the order_by and order_direction parameters are not provided, the Things will be ordered by their creation time, descending.

Response

Success

Response Model - GetThingsResponse
  • things - An array with the Things
  • next_page - The link for the next page. Concatenate the base URL to this link. In the last page it will return null.
Response Model - Thing
  • physical_id - (String) The ID of the Thing in the system; the Thing physical ID as set when associated to the User by the client application.
  • name - (String) Name given to a Thing.
  • model - (String) Thing model
  • firmware_version - (String) Last known firmware version of the thing.
  • last_seen - (String) Date the Thing was last seen by the system, set by either mobile application or management API.
  • created_at - (String) Date when the Thing was created.
  • updated_at - (String) Date when the Thing was updated.

Failures

When the authorization header is invalid or not provided:

HTTP: HTTP/1.1 401 Unauthorize

{
  "reason": "AUTH.UNAUTHORIZED",
  "error_message": ""
}

When the request is invalid, e.g order_by=color

HTTP: HTTP/1.1 400 Bad Request

{
  "reason": "COMMON.REQUEST_VALIDATION",
  "error_message": "Order by column 'color' is not supported"
}

Example

Request

curl -X GET \
 'https://api.iconnect.bycopilot.com/v2/api/management/copilot_connect/things?order_by=updatedAt' \
 -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwd2RfZXhwaXJlZCI6ZmFsc2UsInVzZXJfcm9sZSI6IlNFUlZJQ0VfQUNDT1VOVCIsImRldmljZV9pZCI6ImVtcHR5IiwidXNlcl9pZCI6IjVjNTA4MmNjZmFmZWYyNTM3M2JiMzc1MiIsImV4cGlyYXRpb25fdGltZSI6MTU1MjQ3NDUyNzE4Miwiand0VmVyc2lvbiI6Imp3dDEifQ.xeqdUjSduw6BO100F8LiCRAylZojO6jJDTQLyY0xX5s' \
 -H 'Content-Type: application/json

Response

{
  "things": [
    {
      "physical_id": "abcedfg-323-g",
      "name": "My smart thing",
      "model": "bmx86",
      "firmware_version": "xv8312",
      "last_seen": null,
      "created_at": "2019-03-13T11:55:42.858Z",
      "updated_at": "2019-03-13T11:55:55.768Z"
    },
    {
      "physical_id": "d6d3dc24-a8c2-4834-9b11-d3459ce03bc2",
      "name": "Different name",
      "model": "xv8311",
      "firmware_version": "2.0.0",
      "last_seen": "2019-02-26T16:31:57.001Z",
      "created_at": "2019-01-12T12:07:08.130Z",
      "updated_at": "2019-01-12T12:07:14.166Z"
    }
  ],
  "next_page": "/v2/api/management/copilot_connect/things?page=bGlkPTVjN2QzODJhNWYzNWFmMDAwZTVjY2ZmOQ=="
}

Get Things - fetch further pages

Url

GET https://<BASE_URL><next_page>

To fetch the next page, concatenate the next_page from the pervious page response, with your base URL. For example, if your base URL is https://api.iconnect.bycopilot.com and the next_page is /v2/api/management/copilot_connect/things?page=bGlkPTVjNTA0MTI4N2Y1NDY1MDAwZGEwYjQwYw==

the URL will be: https://api.iconnect.bycopilot.com/v2/api/management/copilot_connect/things?page=bGlkPTVjNTA0MTI4N2Y1NDY1MDAwZGEwYjQwYw==

💡 Remember - verify that next_page is not null before trying to fetch the next page. Next Page will be null on the last page.

Headers

Authorization: <TOKEN_TYPE> <ACCESS_TOKEN>
Content-Type: application/json

In the same way as when fetching the first page.

Query Parameters

Do not add any queryParameter manually to the call after building the URL according to the guideline above.

In any case, the page parameter is included as part of the next_page link.

Response

Success

See Response models in Fetch Things above.

Failures

When the Authorization header is invalid or not provided:

HTTP: HTTP/1.1 401 Unauthorize

{
  "reason": "AUTH.UNAUTHORIZED",
  "error_message": ""
}

When the request is invalid, e.g page=NotValidPage or both page and order_by parameters were specified

HTTP: HTTP/1.1 400 Bad Request

{
    "reason":"COMMON.REQUEST_VALIDATION",
    "error_message":"Page parameter is not valid. Try to remove the 'page' parameter and start from the first page."
}

HTTP: HTTP/1.1 400 Bad Request

{
    "reason":"COMMON.REQUEST_VALIDATION",
    "error_message":"In case that the parameter page is provided, order_by and order_direction must not be specified"
}

Example

In case the first page is

{
  "things": [
    {
      "physical_id": "abcedfg-323-g",
      "name": "My smart thing",
      "model": "bmx86",
      "firmware_version": "xv8312",
      "last_seen": null,
      "created_at": "2019-03-13T11:55:42.858Z",
      "updated_at": "2019-03-13T11:55:55.768Z"
    },
    {
      "physical_id": "d6d3dc24-a8c2-4834-9b11-d3459ce03bc2",
      "name": "Different name",
      "model": "xv8311",
      "firmware_version": "2.0.0",
      "last_seen": "2019-02-26T16:31:57.001Z",
      "created_at": "2019-01-12T12:07:08.130Z",
      "updated_at": "2019-01-12T12:07:14.166Z"
    }
  ],
  "next_page": "/v2/api/management/copilot_connect/things?page=bGlkPTVjN2QzODJhNWYzNWFmMDAwZTVjY2ZmOQ=="
}

Request

The request will be:

curl -X GET \
 'https://api.iconnect.bycopilot.com/v2/api/management/copilot_connect/things?page=bGlkPTVjN2QzODJhNWYzNWFmMDAwZTVjY2ZmOQ==' \
 -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwd2RfZXhwaXJlZCI6ZmFsc2UsInVzZXJfcm9sZSI6IlNFUlZJQ0VfQUNDT1VOVCIsImRldmljZV9pZCI6ImVtcHR5IiwidXNlcl9pZCI6IjVjNTA4MmNjZmFmZWYyNTM3M2JiMzc1MiIsImV4cGlyYXRpb25fdGltZSI6MTU1MjQ3NDUyNzE4Miwiand0VmVyc2lvbiI6Imp3dDEifQ.xeqdUjSduw6BO100F8LiCRAylZojO6jJDTQLyY0xX5s' \
 -H 'Content-Type: application/json

Response

The response will be similar to the response of the first page.

Get Single Thing

Url

GET https://<BASE_URL>/v2/api/management/copilot_connect/things/{thing_physical_id}

Headers

Authorization: <TOKEN_TYPE> <ACCESS_TOKEN>
Content-Type: application/json

Creating the Authorization token - see Session Management

Query Parameters

None

Response

Success

Http code 200 with SingleThing in the body.

Response Model - SingleThing
  • physical_id - (String) The ID of the Thing in the system; see Thing physical_id.
  • name - (String) Name given to a Thing.
  • model - (String) The model of the thing.
  • firmware_version - (String) Last known Thing firmware version.
  • last_seen - (String) Date the Thing was last seen by the system, set by either mobile application or management API.
  • statuses - List of ThingStatus object.
  • custom_settings - custom_settings object stored specifically for this Thing.
  • associated_users - AssociatedUser object.
  • created_at - (String) Date the Thing was created.
  • updated_at - (String) Date the Thing was updated.

Response Model - ThingStatus

  • name - Status key (name).
  • status_value - (String) Status value.
  • date - Date the status was updated.

Response Model - CustomSettings

Custom Setting is a Map where the keys are Strings and the values might be any object. They are used on the client side as a simple key-value pairs and support the following data types:

  • Primitive data types: Boolean, String, Integer, Float, Double.
  • Array of primitive or custom objects.
  • Dictionary of primitive or custom objects.

See the example Thing below - illustrating complex custom settings:

Response Model - AssociatedUser

Represents Users that are associated with the Thing. Only the user ID and the association date are represented.

  • id - (String) The associated User ID.
  • association_data - An object with the property associated_at that represent the association date.

Failures

HTTP/1.1 401 Unauthorize
{
  "reason": "AUTH.UNAUTHORIZED",
  "error_message": ""
}

When the requesting a thing that does not exist:

HTTP/1.1 404 Not Found
{
    "reason":"COMMON.ENTITY_NOT_FOUND",
    "error_message":"User 5c750c9ab85520000f70243e was not found"
}

Example

Request

curl -X GET \
 'https://api.iconnect.bycopilot.com/v2/api/management/copilot_connect/things/abcedfg-323-g' \
 -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwd2RfZXhwaXJlZCI6ZmFsc2UsInVzZXJfcm9sZSI6IlNFUlZJQ0VfQUNDT1VOVCIsImRldmljZV9pZCI6ImVtcHR5IiwidXNlcl9pZCI6IjVjNTA4MmNjZmFmZWYyNTM3M2JiMzc1MiIsImV4cGlyYXRpb25fdGltZSI6MTU1MjQ3NDUyNzE4Miwiand0VmVyc2lvbiI6Imp3dDEifQ.xeqdUjSduw6BO100F8LiCRAylZojO6jJDTQLyY0xX5s' \
 -H 'Content-Type: application/json'

Response

{
  "physical_id": "abcedfg-323-g",
  "name": "My smart thing",
  "model": "bmx86",
  "firmware_version": "xv8312",
  "last_seen": null,
  "statuses": [
    {
      "name": "battery",
      "status_value": "82",
      "date": "2019-03-10T00:00:16.643Z"
    }
  ],
  "custom_settings": null,
  "associated_users": [
    {
      "id": "5c88d59a00f138000e9233bc",
      "association_data": {
        "associated_at": "2019-01-02T12:52:00.817Z"
      }
    }
  ],
  "created_at": "2019-03-13T11:55:42.858Z",
  "updated_at": "2019-03-13T11:55:55.768Z"
}

Update thing

Use the API PATCH /v2/api/management/copilot_connect/things/{thing_physical_id} to update your Thing.

Url

PATCH https://<BASE_URL>/v2/api/management/copilot_connect/things/{thing_physical_id}

Headers

Authorization: <TOKEN_TYPE> <ACCESS_TOKEN>
Content-Type: application/json

Creating Authorization token - see Session Management

Body

The body should contain an object with one or more the following keys. Only the specified keys will be updated. All keys are optional.

  • name - (Optional, String) The name given to the Thing - if specified and not null, the current name will be replaced by the provided one.
  • firmware_version - (Optional, String) Thing firmware version - if specified and not null, the current firmware value will be replaced by the provided one.
  • last_seen - (Optional, String) on format: yyyy-MM-dd'T'HH:mm:ss.SSS'Z) if specified and not null, the current last_seen value will be replaced by the provided one.
  • statuses - (Optional, List of ThingStatus object).
  • custom_settings - (Optional, Map from String to Object).

Status update behavior:

The statuses object is a list of statuses of the device.

If the specified status exists: The value and the date of the status will be overridden by the provided value and date.

If the specified status does not exist: The status will be added with the value provided.

For example - Custom settings behavior:

The custom_settings object is a map between a string to any object.

If the specified key exists: the value of this key will be overridden.

If the specified key does not exist: The new key will be added, and its value set to the value provided.

Response

Http code 200 with the updated SingleThing in the body.

See SingleThing response model here.

Example 1 - Update Thing name

Thing before:

{
  "physical_id": "abcedfg-323-g",
  "name": "My smart thing",
  "model": "bmx86",
  "firmware_version": "xv8312",
  "last_seen": null,
  "statuses": [],
  "custom_settings": null,
  "associated_users": [
    {
      "id": "5c88d59a00f138000e9233bc",
      "association_data": {
        "associated_at": "2019-01-02T12:52:00.817Z"
      }
    }
  ],
  "created_at": "2019-03-13T11:55:42.858Z",
  "updated_at": "2019-03-13T11:55:55.768Z"
}

Request:

curl -X PATCH \
'https://api.iconnect.bycopilot.com/v2/api/management/copilot_connect/things/abcedfg-323-g' \
-d "{\"name\" : \"myNewName\"}" \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwd2RfZXhwaXJlZCI6ZmFsc2UsInVzZXJfcm9sZSI6IlNFUlZJQ0VfQUNDT1VOVCIsImRldmljZV9pZCI6ImVtcHR5IiwidXNlcl9pZCI6IjVjNTA4MmNjZmFmZWYyNTM3M2JiMzc1MiIsImV4cGlyYXRpb25fdGltZSI6MTU1MjQ3NDUyNzE4Miwiand0VmVyc2lvbiI6Imp3dDEifQ.xeqdUjSduw6BO100F8LiCRAylZojO6jJDTQLyY0xX5s' \
-H 'Content-Type: application/json' 

Response:

{
  "physical_id": "abcedfg-323-g",
  "name": "myNewName",
  "model": "bmx86",
  "firmware_version": "xv8312",
  "last_seen": null,
  "statuses": [],
  "custom_settings": null,
  "associated_users": [
    {
      "id": "5c88d59a00f138000e9233bc",
      "association_data": {
        "associated_at": "2019-01-02T12:52:00.817Z"
      }
    }
  ],
  "created_at": "2019-03-13T11:55:42.858Z",
  "updated_at": "2019-03-13T11:55:55.768Z"
}

Example 2 - Add a status

Thing before:

See the response in the example above.

Request:

curl -X PATCH \
'https://api.iconnect.bycopilot.com/v2/api/management/copilot_connect/things/abcedfg-323-g' \
-d "{\"statuses\" : [{\"name\":\"addedStatusKey\",\"status_value\":\"addedStatusValue\",\"date\":\"2019-03-14T00:00:16.643Z\"}]}" \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwd2RfZXhwaXJlZCI6ZmFsc2UsInVzZXJfcm9sZSI6IlNFUlZJQ0VfQUNDT1VOVCIsImRldmljZV9pZCI6ImVtcHR5IiwidXNlcl9pZCI6IjVjNTA4MmNjZmFmZWYyNTM3M2JiMzc1MiIsImV4cGlyYXRpb25fdGltZSI6MTU1MjQ3NDUyNzE4Miwiand0VmVyc2lvbiI6Imp3dDEifQ.xeqdUjSduw6BO100F8LiCRAylZojO6jJDTQLyY0xX5s' \
-H 'Content-Type: application/json'

Response:

{
  "physical_id": "abcedfg-323-g",
  "name": "myNewName",
  "model": "bmx86",
  "firmware_version": "xv8312",
  "last_seen": null,
  "statuses": [
    {
      "name": "addedStatusKey",
      "status_value": "addedStatusValue",
      "date": "2019-03-14T00:00:16.643Z"
    }
  ],
  "custom_settings": null,
  "associated_users": [
    {
      "id": "5c88d59a00f138000e9233bc",
      "association_data": {
        "associated_at": "2019-01-02T12:52:00.817Z"
      }
    }
  ],
  "created_at": "2019-03-13T11:55:42.858Z",
  "updated_at": "2019-03-13T11:55:55.768Z"
}

Example 3 - Update existing status

Thing before:

See the response in the example above.

Request:

curl -X PATCH \
'https://api.iconnect.bycopilot.com/v2/api/management/copilot_connect/things/abcedfg-323-g' \
-d "{\"statuses\" : [{\"name\":\"addedStatusKey\",\"status_value\":\"afterUpdateStatusValue\",\"date\":\"2019-03-14T00:00:16.643Z\"}]}" \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwd2RfZXhwaXJlZCI6ZmFsc2UsInVzZXJfcm9sZSI6IlNFUlZJQ0VfQUNDT1VOVCIsImRldmljZV9pZCI6ImVtcHR5IiwidXNlcl9pZCI6IjVjNTA4MmNjZmFmZWYyNTM3M2JiMzc1MiIsImV4cGlyYXRpb25fdGltZSI6MTU1MjQ3NDUyNzE4Miwiand0VmVyc2lvbiI6Imp3dDEifQ.xeqdUjSduw6BO100F8LiCRAylZojO6jJDTQLyY0xX5s' \
-H 'Content-Type: application/json'

Response:

{
  "physical_id": "abcedfg-323-g",
  "name": "myNewName",
  "model": "bmx86",
  "firmware_version": "xv8312",
  "last_seen": null,
  "statuses": [
    {
      "name": "addedStatusKey",
      "status_value": "afterUpdateStatusValue",
      "date": "2019-03-14T00:00:16.643Z"
    }
  ],
  "custom_settings": null,
  "associated_users": [
    {
      "id": "5c88d59a00f138000e9233bc",
      "association_data": {
        "associated_at": "2019-01-02T12:52:00.817Z"
      }
    }
  ],
  "created_at": "2019-03-13T11:55:42.858Z",
  "updated_at": "2019-03-13T11:55:55.768Z"
}

Example 4 - Add the first key to custom setting

Thing before:

See the response in the example above.

Request:

curl -X PATCH \
'https://api.iconnect.bycopilot.com/v2/api/management/copilot_connect/things/abcedfg-323-g' \
-d "{\"custom_settings\" : {\"color\":\"blue\"}}" \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwd2RfZXhwaXJlZCI6ZmFsc2UsInVzZXJfcm9sZSI6IlNFUlZJQ0VfQUNDT1VOVCIsImRldmljZV9pZCI6ImVtcHR5IiwidXNlcl9pZCI6IjVjNTA4MmNjZmFmZWYyNTM3M2JiMzc1MiIsImV4cGlyYXRpb25fdGltZSI6MTU1MjQ3NDUyNzE4Miwiand0VmVyc2lvbiI6Imp3dDEifQ.xeqdUjSduw6BO100F8LiCRAylZojO6jJDTQLyY0xX5s' \
-H 'Content-Type: application/json'

Response:

{
  "physical_id": "abcedfg-323-g",
  "name": "myNewName",
  "model": "bmx86",
  "firmware_version": "xv8312",
  "last_seen": null,
  "statuses": [
    {
      "name": "addedStatusKey",
      "status_value": "afterUpdateStatusValue",
      "date": "2019-03-14T00:00:16.643Z"
    }
  ],
  "custom_settings": {
    "color": "blue"
  },
  "associated_users": [
    {
      "id": "5c88d59a00f138000e9233bc",
      "association_data": {
        "associated_at": "2019-01-02T12:52:00.817Z"
      }
    }
  ],
  "created_at": "2019-03-13T11:55:42.858Z",
  "updated_at": "2019-03-13T11:55:55.768Z"
}

Example 5 - Add additional key to custom setting

In this example, the custom settings object already exists. The call to add a key to the custom settings is identical to the call that added the first custom settings in the example above.

Thing before:

See the response in the example above.

Request:

curl -X PATCH \
'https://api.iconnect.bycopilot.com/v2/api/management/copilot_connect/things/abcedfg-323-g' \
-d "{\"custom_settings\" : {\"lastResults\":[8,3,5]}}" \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwd2RfZXhwaXJlZCI6ZmFsc2UsInVzZXJfcm9sZSI6IlNFUlZJQ0VfQUNDT1VOVCIsImRldmljZV9pZCI6ImVtcHR5IiwidXNlcl9pZCI6IjVjNTA4MmNjZmFmZWYyNTM3M2JiMzc1MiIsImV4cGlyYXRpb25fdGltZSI6MTU1MjQ3NDUyNzE4Miwiand0VmVyc2lvbiI6Imp3dDEifQ.xeqdUjSduw6BO100F8LiCRAylZojO6jJDTQLyY0xX5s' \
-H 'Content-Type: application/json'

Response:

{
  "physical_id": "abcedfg-323-g",
  "name": "myNewName",
  "model": "bmx86",
  "firmware_version": "xv8312",
  "last_seen": null,
  "statuses": [
    {
      "name": "addedStatusKey",
      "status_value": "afterUpdateStatusValue",
      "date": "2019-03-14T00:00:16.643Z"
    }
  ],
  "custom_settings": {
    "color": "blue",
    "lastResults": [
      8,
      3,
      5
    ]
  },
  "associated_users": [
    {
      "id": "5c88d59a00f138000e9233bc",
      "association_data": {
        "associated_at": "2019-01-02T12:52:00.817Z"
      }
    }
  ],
  "created_at": "2019-03-13T11:55:42.858Z",
  "updated_at": "2019-03-13T11:55:55.768Z"
}

Example 6 - Remove custom settings key

Thing before:

See the response in the example above.

Request:

curl -X PATCH \
'https://api.iconnect.bycopilot.com/v2/api/management/copilot_connect/things/abcedfg-323-g' \
-d "{\"custom_settings\" : {\"color\": \"\$CopilotUnset\$\"}}" \
-H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwd2RfZXhwaXJlZCI6ZmFsc2UsInVzZXJfcm9sZSI6IlNFUlZJQ0VfQUNDT1VOVCIsImRldmljZV9pZCI6ImVtcHR5IiwidXNlcl9pZCI6IjVjNTA4MmNjZmFmZWYyNTM3M2JiMzc1MiIsImV4cGlyYXRpb25fdGltZSI6MTU1MjQ3NDUyNzE4Miwiand0VmVyc2lvbiI6Imp3dDEifQ.xeqdUjSduw6BO100F8LiCRAylZojO6jJDTQLyY0xX5s' \
-H 'Content-Type: application/json'

Response:

{
  "physical_id": "abcedfg-323-g",
  "name": "myNewName",
  "model": "bmx86",
  "firmware_version": "xv8312",
  "last_seen": null,
  "statuses": [
    {
      "name": "addedStatusKey",
      "status_value": "afterUpdateStatusValue",
      "date": "2019-03-14T00:00:16.643Z"
    }
  ],
  "custom_settings": {
    "lastResults": [
      8,
      3,
      5
    ]
  },
  "associated_users": [
    {
      "id": "5c88d59a00f138000e9233bc",
      "association_data": {
        "associated_at": "2019-01-02T12:52:00.817Z"
      }
    }
  ],
  "created_at": "2019-03-13T11:55:42.858Z",
  "updated_at": "2019-03-13T11:55:55.768Z"
}

Associate Thing

Use this API to associate a User and his Thing, if the association is done remotly instead of from the App SDK.

Url

POST  https://<BASE_URL>/v2/api/management/copilot_connect/users/{user_id}/associated_things

Headers

Authorization: <TOKEN_TYPE> <ACCESS_TOKEN>
Content-Type: application/json

Creating Authorization token - see Session Management

Body

The body must contain all of the following fields

  • physical_id - (String) The ID of the Thing in the system; must be the same as the Thing physical ID as set when associated to the User by the client application.
  • model - (String) Thing model
  • firmware_version - (String) Last known firmware version of the thing.

Response

Success

Http code 200 / 201 ( If a new device was created ) with SingleThing in the body.

Example

Request

curl -X POST \
 'https://api.iconnect.bycopilot.com/v2/api/management/copilot_connect/users/5c88d59a00f138000e9233bc/associated_things' \
 -d "{\"physical_id\" : \"abcedfg-323-g\", \"model\" : \"bmx86\", \"firmware_version\" : \"xv8312\"}" \
 -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwd2RfZXhwaXJlZCI6ZmFsc2UsInVzZXJfcm9sZSI6IlNFUlZJQ0VfQUNDT1VOVCIsImRldmljZV9pZCI6ImVtcHR5IiwidXNlcl9pZCI6IjVjNTA4MmNjZmFmZWYyNTM3M2JiMzc1MiIsImV4cGlyYXRpb25fdGltZSI6MTU1MjQ3NDUyNzE4Miwiand0VmVyc2lvbiI6Imp3dDEifQ.xeqdUjSduw6BO100F8LiCRAylZojO6jJDTQLyY0xX5s' \
 -H 'Content-Type: application/json'

Response

{
  "physical_id": "abcedfg-323-g",
  "name": "My smart thing",
  "model": "bmx86",
  "firmware_version": "xv8312",
  "last_seen": null,
  "statuses": [
    {
      "name": "battery",
      "status_value": "82",
      "date": "2019-03-10T00:00:16.643Z"
    }
  ],
  "custom_settings": null,
  "associated_users": [
    {
      "id": "5c88d59a00f138000e9233bc",
      "association_data": {
        "associated_at": "2019-01-02T12:52:00.817Z"
      }
    }
  ],
  "created_at": "2019-03-13T11:55:42.858Z",
  "updated_at": "2019-03-13T11:55:55.768Z"
}

Disassociate Thing

Use this API to disassociate a User and his Thing, if the disassociation is done remotly instead of from the App SDK.

Url

DELETE  https://<BASE_URL>/v2/api/management/copilot_connect/users/{user_id}/associated_things/{physical_id}

Headers

Authorization: <TOKEN_TYPE> <ACCESS_TOKEN>
Content-Type: application/json

Creating Authorization token - see Session Management

Body

None

Response

Http code 200 on successfull disassociation

Example

Request

curl -X DELETE \
 'https://api.iconnect.bycopilot.com/v2/api/management/copilot_connect/users/5c88d59a00f138000e9233bc/associated_things/abcedfg-323-g' \
 -H 'Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJwd2RfZXhwaXJlZCI6ZmFsc2UsInVzZXJfcm9sZSI6IlNFUlZJQ0VfQUNDT1VOVCIsImRldmljZV9pZCI6ImVtcHR5IiwidXNlcl9pZCI6IjVjNTA4MmNjZmFmZWYyNTM3M2JiMzc1MiIsImV4cGlyYXRpb25fdGltZSI6MTU1MjQ3NDUyNzE4Miwiand0VmVyc2lvbiI6Imp3dDEifQ.xeqdUjSduw6BO100F8LiCRAylZojO6jJDTQLyY0xX5s' \
 -H 'Content-Type: application/json'

Response

Empty - Status code 200

← UserEnd User Authentication →
  • Get Things - fetch the first page
    • Url
    • Headers
    • Query Parameters
    • Response
    • Example
  • Get Things - fetch further pages
    • Url
    • Headers
    • Query Parameters
    • Response
    • Example
  • Get Single Thing
    • Url
    • Headers
    • Query Parameters
    • Response
    • Example
  • Update thing
    • Url
    • Headers
    • Body
    • Response
    • Example 1 - Update Thing name
    • Example 2 - Add a status
    • Example 3 - Update existing status
    • Example 4 - Add the first key to custom setting
    • Example 5 - Add additional key to custom setting
    • Example 6 - Remove custom settings key
  • Associate Thing
    • Url
    • Headers
    • Body
    • Response
    • Example
  • Disassociate Thing
    • Url
    • Headers
    • Body
    • Response
    • Example
Copilot
Mail: hello@copilot.cx
Call: (212).398.0001
© Copilot.cx 2025