Fetch Customers via API

1

IDs and Credentials

export REPLICATED_API_TOKEN=...
export REPLICATED_APP_ID=2C0OQyxiiA4pc3blK0cKs5VQS3N # example

Get an API token by navigating to Account Settings and scrolling to the bottom to create a Personal API Token (PAT), or by creating a service account:

Get an App ID on the /settings page. NOTE - an ID is required to use the REST API - application slugs are not supported for most endpoints.

Screenshot 2023-05-26 at 7.37.20 AM
Screenshot 2023-05-26 at 7.37.20 AM1109×597 56.3 KB

Then, you can run the following cURL command to query customers.

curl -v -H "Authorization: $REPLICATED_API_TOKEN" "https://api.replicated.com/vendor/v3/app/$REPLICATED_APP_ID/customers?pageSize=50&sortDesc=true&currentPage=0"

{
  "customers": [
    {
      "id": "2JBxR7eNpTA5vl2rkkmUbVozdLd",
      "teamId": "Dq6-SEzp_hIUBfpMe5cv0OzaFIb8IDpv",
      "name": "The Airplane Company",
      "email": "dexter@replicated.com",
      "createdAt": "2022-12-20T19:41:06Z",
      "expiresAt": null,
      "isArchived": false,
      "type": "prod",
      "installationId": "2JBxRAHOAKqnA80g4hoEDNwteiP",
      "installationVersion": "79",
      "appType": "",
      "airgap": false,
      "isGitopsSupported": true,
      "isIdentityServiceSupported": false,
      "isGeoaxisSupported": false,
      "isSnapshotSupported": false,
      "isSupportBundleUploadEnabled": true,
      "installedReleaseSequence": 81,
      "installedReleaseLabel": "1.12.2",
      "channels": [
        {
          "id": "2C0OR5HUAAge0xo2ggEwGwOHSG4",
          "appId": "2C0OQyxiiA4pc3blK0cKs5VQS3N",
          "appSlug": "wordpress-enterprise",
          "appName": "wordpress-enterprise",
          "channelSlug": "stable",
          "name": "Stable",
          "description": "",
          "channelIcon": "",
          "isArchived": false,
          "isDefault": true,
          "created": "2022-07-16T01:47:03Z",
          "updated": "2022-07-16T01:47:03Z",
          "numReleases": 34,
          "buildAirgapAutomatically": true,
          "airgapDockerRegistryFormatEnabled": false,
          "semverRequired": true,
          "semverWarning": "",
          "targetKotsVersion": "",
          "enterprisePartnerChannelID": "",
          "channelSequence": 34,
          "currentVersion": "1.12.2",
          "extraLintRules": null,
          "gitHubRef": null,
          "releaseNotes": "\"\"",
          "releaseSequence": 79,
          "replicatedRegistryDomain": "",
          "adoptionRate": [],
          "customers": {
            "totalCustomers": 0,
            "activeCustomers": 0,
            "inactiveCustomers": 0
          },
          "releases": [],
          "chartReleases": null
        }
      ],
      "instances": [
        {
          "licenseId": "REDACTED",
          "instanceId": "2JK93avStGaNpwTfiHHUkc2iZ9p",
          "clusterId": "bhbwxvgqnoqtajhbxyqvblpidqhmfuts",
          "createdAt": "2022-12-23T17:15:09Z",
          "lastActive": "2023-05-26T12:39:00.663Z",
          "appStatus": "ready",
          "active": true,
          "versionHistory": [
            {
              "instanceId": "2JK93avStGaNpwTfiHHUkc2iZ9p",
              "clusterId": "bhbwxvgqnoqtajhbxyqvblpidqhmfuts",
              "versionLabel": "1.12.2",
              "downstreamChannelId": "2C0OR5HUAAge0xo2ggEwGwOHSG4",
              "downstreamReleaseSequence": 81,
              "intervalStart": "2023-05-22T00:38:02.562Z",
              "intervalLast": "2023-05-26T12:39:00.663Z",
              "replHelmCount": 0,
              "nativeHelmCount": 0
            }
          ],
          "kotsVersion": "1.92.1",
          "cloud": "gce",
          "isAirgap": false,
          "isKurl": false,
          "kurlNodeCountTotal": 0,
          "kurlNodeCountReady": 0,
          "k8sVersion": "v1.24.11-gke.1000",
          "client": "",
          "isDummyInstance": false
        }
   ]
}

API Reference Docs

2

Alternative Option with Instances API

NOTE the api.replicated.com/v1 API is currently in Alpha. The data should be treated a valid source of truth, but the structure of responses is subject to change.

curl -v -H "Authorization: $REPLICATED_API_TOKEN" "https://api.replicated.com/v1/instances?appSelector=$REPLICATED_APP_ID"

NOTE at time of writing - this endpoint does not support paging.

[
  {
    "id": "2Oxvzizx25s9Ze4LJrWy6K9VVtE",
    "firstCheckinAt": "2023-04-26T13:24:11.916Z",
    "lastCheckinAt": "2023-04-26T13:25:47.423Z",
    "firstReadyAt": "2023-04-26T13:25:47.423Z",
    "instanceTimeToInstallMinutes": 1,
    "licenseTimeToInstallMinutes": 21636,
    "licenseCreatedAt": "2023-04-11T12:49:18Z",
    "appStatus": "inactive",
    "versionLabel": "0.1.1",
    "numberVersionsBehind": 0,
    "currentVersionReleasedAt": "2023-04-11T18:45:38Z",
    "latestVersionReleasedAt": "2023-04-11T18:45:38Z",
    "isKurl": true,
    "kurlNodeCountReady": 1,
    "kurlNodeCountTotal": 1,
    "k8sVersion": "v1.25.5",
    "k8sDistribution": "kurl",
    "k8sVersionsBehind": 0,
    "cloudProvider": "",
    "cloudProviderRegion": "",
    "kotsInstanceId": "zlqihhwgppeoqrgyudhzvatzvlhapwpu",
    "kotsVersion": "v1.98.1",
    "client": "",
    "isAirgap": true,
    "_embedded": {
      "app": {
        "id": "2C0OQyxiiA4pc3blK0cKs5VQS3N",
        "name": "wordpress-enterprise",
        "slug": "wordpress-enterprise",
        "createdAt": "2022-07-16T01:47:04Z",
        "customHostnames": {},
        "resourceUrls": {
          "_self": {
            "href": "/v1/app/2C0OQyxiiA4pc3blK0cKs5VQS3N",
            "method": "GET",
            "documentation": "https://help.replicated.com/api/vendor-api/#get-v4-app-appid"
          },
          "channels": {
            "list": {
              "href": "/v1/channels?appSelector=wordpress-enterprise",
              "method": "GET",
              "documentation": "https://help.replicated.com/api/vendor-api/#get-v4-apps-appid-channels"
            }
          }
        }
      },
      "channel": {
        "id": "2C0OR1LRJTsRpPJJKIcQ9sAMlUt",
        "name": "Beta",
        "slug": "beta",
        "createdAt": "2022-07-16T01:47:03Z",
        "isDefault": false,
        "_embedded": {
          "app": {
            "id": "2C0OQyxiiA4pc3blK0cKs5VQS3N",
            "name": "wordpress-enterprise",
            "slug": "wordpress-enterprise",
            "createdAt": "2022-07-16T01:47:04Z",
            "customHostnames": {},
            "resourceUrls": {
              "_self": {
                "href": "/v1/app/2C0OQyxiiA4pc3blK0cKs5VQS3N",
                "method": "GET",
                "documentation": "https://help.replicated.com/api/vendor-api/#get-v4-app-appid"
              },
              "channels": {
                "list": {
                  "href": "/v1/channels?appSelector=wordpress-enterprise",
                  "method": "GET",
                  "documentation": "https://help.replicated.com/api/vendor-api/#get-v4-apps-appid-channels"
                }
              }
            }
          }
        },
        "_resources": {
          "_self": {
            "href": "/v1/channel/2C0OR1LRJTsRpPJJKIcQ9sAMlUt",
            "method": "GET",
            "documentation": "https://help.replicated.com/api/vendor-api/#get-v4-channel-channelid"
          },
          "releases": {
            "list": {
              "href": "/v1/releases?channelSelector=beta",
              "method": "GET",
              "documentation": "https://help.replicated.com/api/vendor-api/#get-v4-channels-channelid-releases"
            }
          }
        }
      },
      "license": {
        "id": "REDACTED",
        "createdAt": "2023-04-11T12:49:18Z",
        "updatedAt": "2023-04-11T16:54:01Z",
        "timeToInstallMinutes": 6,
        "type": "paid",
        "replicatedEntitlements": [
          "gitops",
          "allow_snapshots"
        ],
        "_embedded": {
          "app": {
            "id": "2C0OQyxiiA4pc3blK0cKs5VQS3N",
            "name": "wordpress-enterprise",
            "slug": "wordpress-enterprise",
            "createdAt": "2022-07-16T01:47:04Z",
            "customHostnames": {},
            "resourceUrls": {
              "_self": {
                "href": "/v1/app/2C0OQyxiiA4pc3blK0cKs5VQS3N",
                "method": "GET",
                "documentation": "https://help.replicated.com/api/vendor-api/#get-v4-app-appid"
              },
              "channels": {
                "list": {
                  "href": "/v1/channels?appSelector=wordpress-enterprise",
                  "method": "GET",
                  "documentation": "https://help.replicated.com/api/vendor-api/#get-v4-apps-appid-channels"
                }
              }
            }
          },
          "channel": {
            "id": "2C0OR1LRJTsRpPJJKIcQ9sAMlUt",
            "name": "Beta",
            "slug": "beta",
            "createdAt": "2022-07-16T01:47:03Z",
            "isDefault": false,
            "_embedded": {
              "app": {
                "id": "2C0OQyxiiA4pc3blK0cKs5VQS3N",
                "name": "wordpress-enterprise",
                "slug": "wordpress-enterprise",
                "createdAt": "2022-07-16T01:47:04Z",
                "customHostnames": {},
                "resourceUrls": {
                  "_self": {
                    "href": "/v1/app/2C0OQyxiiA4pc3blK0cKs5VQS3N",
                    "method": "GET",
                    "documentation": "https://help.replicated.com/api/vendor-api/#get-v4-app-appid"
                  },
                  "channels": {
                    "list": {
                      "href": "/v1/channels?appSelector=wordpress-enterprise",
                      "method": "GET",
                      "documentation": "https://help.replicated.com/api/vendor-api/#get-v4-apps-appid-channels"
                    }
                  }
                }
              }
            },
            "_resources": {
              "_self": {
                "href": "/v1/channel/2C0OR1LRJTsRpPJJKIcQ9sAMlUt",
                "method": "GET",
                "documentation": "https://help.replicated.com/api/vendor-api/#get-v4-channel-channelid"
              },
              "releases": {
                "list": {
                  "href": "/v1/releases?channelSelector=beta",
                  "method": "GET",
                  "documentation": "https://help.replicated.com/api/vendor-api/#get-v4-channels-channelid-releases"
                }
              }
            }
          },
          "customer": {
            "id": "REDACTED",
            "createdAt": "2023-04-11T12:49:18Z",
            "name": "Omozan Industries",
            "email": "fake@fake.com",
            "isArchived": false,
            "resourceUrls": {
              "_self": {
                "href": "/v1/customer/REDACTED",
                "method": "GET",
                "documentation": "https://replicated-vendor-api.readme.io/v4/reference/getcustomer"
              },
              "licenses": {
                "create": {
                  "href": "/v1/customer/REDACTED/license",
                  "method": "POST",
                  "documentation": "https://replicated-vendor-api.readme.io/v4/reference/createcustomer"
                },
                "licenses": {
                  "href": "/v1/customer/REDACTED/licenses",
                  "method": "GET",
                  "documentation": "https://replicated-vendor-api.readme.io/v4/reference/listcustomerlicenses"
                }
              }
            }
          }
        },
        "_resources": {
          "_self": {
            "href": "/v1/license/2OHVBW4m0evkIzqqgifhm9SkuGl",
            "method": "GET",
            "documentation": "https://replicated-vendor-api.readme.io/v4/reference/getlicense"
          },
          "download": {
            "href": "/v1/license/REDACTED/download",
            "method": "GET",
            "documentation": "https://replicated-vendor-api.readme.io/v4/reference/downloadlicense"
          }
        }
      }
    },
    "_resources": {
      "_self": {
        "href": "/v1/instance/2Oxvzizx25s9Ze4LJrWy6K9VVtE",
        "method": "GET",
        "documentation": "https://replicated-vendor-api.readme.io/v4/reference/getinstance"
      },
      "events": {
        "href": "/v1/instance/2Oxvzizx25s9Ze4LJrWy6K9VVtE/events",
        "method": "GET",
        "documentation": "https://replicated-vendor-api.readme.io/v4/reference/listinstanceevents"
      }
    }
  }
]
3

Option 3 - Fetch Customers, then iterate instances using customerSelector

NOTE the api.replicated.com/v1 API is currently in Alpha. The data should be treated a valid source of truth, but the structure of responses is subject to change.

A call to /customers

curl -v -H "Authorization: $REPLICATED_API_TOKEN" "https://api.replicated.com/v1/customers?appSelector=$REPLICATED_APP_ID"

will return a list of customer objects

[
  {
    "id": "2OKpqrfcG7tnoID3KZuYOkprP1K",
    "createdAt": "2023-04-12T17:08:42Z",
    "name": "Founder's Club",
    "email": "dexter@replicated.com",
    "isArchived": false,
    "resourceUrls": {
      "_self": {
        "href": "/v1/customer/2OKpqrfcG7tnoID3KZuYOkprP1K",
        "method": "GET",
        "documentation": "https://replicated-vendor-api.readme.io/v4/reference/getcustomer"
      },
      "licenses": {
        "create": {
          "href": "/v1/customer/2OKpqrfcG7tnoID3KZuYOkprP1K/license",
          "method": "POST",
          "documentation": "https://replicated-vendor-api.readme.io/v4/reference/createcustomer"
        },
        "licenses": {
          "href": "/v1/customer/2OKpqrfcG7tnoID3KZuYOkprP1K/licenses",
          "method": "GET",
          "documentation": "https://replicated-vendor-api.readme.io/v4/reference/listcustomerlicenses"
        }
      }
    }
  }
]

You can marry that up with a call to /instances?appSelector=... (documented above) or you can iterate those customers and, for each customer, call /instances?customerSelector=... using the id from the /customers call.

 curl -v -H "Authorization: $REPLICATED_API_TOKEN" "https://api.replicated.com/v1/instances?customerSelector=..."