Add a device to a cohort with the API

This short tutorial walks through an example flow for adding a device to a cohort with the API. The flow suits a continuous integration setup.

Prerequisites

• Set up authentication first. See Authentication for details on using an organization auth token with bearer authentication.
• A project must already exist.

Check that the device exists

First, check whether the device exists. If the query does not succeed, create the device before continuing.

Reference: https://api-docs.memfault.com/?version=latest#eee1c8ba-0bf5-42c9-8071-814ece0f6505

Example:

curl -X GET \
  https://api.memfault.com/api/v0/organizations/memfault/projects/demo/devices/ABCD1234 \
  -H "Authorization: Bearer $ORGANIZATION_AUTH_TOKEN"

# Response - HTTP 200
{
  "data": {
    "cohort": {
      "count_devices": 3,
      "id": 2,
      "name": "default",
      "slug": "default"
    },
    "created_date": "2019-04-29T23:01:18.280949+00:00",
    "device_serial": "ABCD1234",
    "hardware_version": "hwrev1",
    "id": 16,
    "last_seen": null,
    "last_seen_release": null,
    "latest_install": null,
    "latest_trace": null,
    "owner_ref": "",
    "updated_date": "2019-04-29T23:01:18.280973+00:00"
  }
}

Create the device

Call the API to create the device.

Reference: https://api-docs.memfault.com/?version=latest#f2acc282-23f9-409b-a99b-41da759b82f9

Example:

curl -X POST \
  https://api.memfault.com/api/v0/organizations/memfault/projects/demo/devices \
  -H "Authorization: Bearer $ORGANIZATION_AUTH_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "device_serial": "ABCD1234",
    "hardware_version": "proto"
  }'

# Response - HTTP 200
{
    "data": {
        "cohort": {
            "count_devices": 1,
            "id": 20,
            "name": "default",
            "slug": "default"
        },
        "created_date": "2019-05-21T14:53:32.810978+00:00",
        "device_serial": "ABCD1234",
        "hardware_version": "proto",
        "id": 415,
        "last_seen": null,
        "last_seen_release": null,
        "latest_install": null,
        "latest_trace": null,
        "owner_ref": "",
        "updated_date": "2019-05-21T14:53:32.810984+00:00"
    }
}

You can also call the create-device endpoint every time and check for either a 200 - OK or a 409 - CONFLICT response.

Check that the cohort exists

Reference: https://api-docs.memfault.com/?version=latest#982c7b0f-b668-41cd-8bf1-fa4758beb278

Example:

curl -X POST \
  https://api.memfault.com/api/v0/organizations/memfault/projects/demo/cohorts \
  -H "Authorization: Bearer $ORGANIZATION_AUTH_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Beta",
    "slug": "f8e70b92"
  }'

# Response - HTTP 200
{
    "data": {
        "count_devices": 0,
        "created_date": "2019-05-21T14:59:07.733062+00:00",
        "id": 22,
        "last_deployment": null,
        "name": "Beta",
        "slug": "f8e70b92",
        "updated_date": "2019-05-21T14:59:07.733070+00:00"
    }
}

To ensure the cohort always exists, call create cohort each time and check for either a 200 - OK or a 409 - CONFLICT response.

Add the device to the cohort

Next, update the device to belong to the correct cohort.

Reference: https://api-docs.memfault.com/?version=latest#f4e2584a-36f2-4184-82ec-3b9d0108588c

Example:

curl -X PATCH \
  https://api.memfault.com/api/v0/organizations/memfault/projects/demo/devices/ABCD1234 \
  -H "Authorization: Bearer $ORGANIZATION_AUTH_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{
    "cohort": "f8e70b92"
  }'

# Response - HTTP 200
{
  "data": {
    "cohort": {
      "count_devices": 3,
      "id": 3,
      "name": "Beta",
      "slug": "f8e70b92"
    },
    "created_date": "2019-04-29T23:01:18.280949+00:00",
    "device_serial": "ABCD1234",
    "hardware_version": "hwrev1",
    "id": 16,
    "last_seen": null,
    "last_seen_release": null,
    "latest_install": null,
    "latest_trace": null,
    "owner_ref": "",
    "updated_date": "2019-05-21T00:41:54.926599+00:00"
  }
}

The cohort for the device is now "Beta".