Depot mdmosupdates

Registers the OS update routes.

This page is generated from the Depot route table. Every operation carries the permission it needs and the anchor an agent can link to.

GET /api/v1/mdm/os-releases

GETmdm:readtenant facehosteditmspremoteIdempotent

From an MSP console, prefix the path with /api/v1/clients/{clientID} to reach one client.

Source: [object Object]

listMdmOsReleases lists the OS releases OS update targets are chosen from, newest first.

?platform= narrows to one platform.

Parameters

Name	In	Type	Required	Description
page	query	integer	No	One-based page number. Defaults to 1.
pageSize	query	integer	No	Rows per page, 1 to 200. Defaults to 50.
platform	query	string	No

Responses

Status	Body	Description
200	application/json, PagedResultOsReleaseView	Success.
400	application/problem+json, ProblemDetails	One or more validation errors occurred.
401	application/problem+json, ProblemDetails	No signed-in identity.
403	application/problem+json, ProblemDetails	The identity does not hold mdm:read.
500	application/problem+json, ProblemDetails	The request failed.
503	application/problem+json, ProblemDetails	The OS release list is not available on this server.

200 response body

Field	Type	Description
itemsrequired	array of OsReleaseView
items[].buildrequired	string
items[].expiresAt	string (date-time) or null
items[].fetchedAtrequired	string (date-time)
items[].platformrequired	string
items[].releasedAt	string (date-time) or null
items[].sourcerequired	string
items[].supportedDevicesrequired	array of string
items[].versionrequired	string
pagerequired	integer
pageSizerequired	integer
totalrequired	integer

Request samples

curl

# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.
curl -X GET 'https://depot.example.com/api/v1/mdm/os-releases?page=0&pageSize=0&platform=<platform>' \
  -H 'X-CSRF-Token: <csrf-token>' \
  -H 'Accept: application/json' \
  -b 'outpost_console=<console-session>'

PowerShell

# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.

$headers = @{
    'X-CSRF-Token' = '<csrf-token>'
    'Accept' = 'application/json'
    'Cookie' = 'outpost_console=<console-session>'
}

$response = Invoke-RestMethod `
    -Method Get `
    -Uri 'https://depot.example.com/api/v1/mdm/os-releases?page=0&pageSize=0&platform=<platform>' `
    -Headers $headers

$response | ConvertTo-Json -Depth 10

Python

# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.

import requests

url = "https://depot.example.com/api/v1/mdm/os-releases"
params = {
    "page": "0",
    "pageSize": "0",
    "platform": "<platform>",
}
headers = {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
}
cookies = {
    "outpost_console": "<console-session>",
}

response = requests.get(url, params=params, headers=headers, cookies=cookies, timeout=30)
response.raise_for_status()
print(response.json())

Go

// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.
package main

import (
  "fmt"
  "io"
  "log"
  "net/http"
)

func main() {
  req, err := http.NewRequest(http.MethodGet, "https://depot.example.com/api/v1/mdm/os-releases?page=0&pageSize=0&platform=<platform>", nil)
  if err != nil {
    log.Fatal(err)
  }

  req.Header.Set("X-CSRF-Token", "<csrf-token>")
  req.Header.Set("Accept", "application/json")
  req.AddCookie(&http.Cookie{Name: "outpost_console", Value: "<console-session>"})

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()

  out, err := io.ReadAll(resp.Body)
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(resp.Status, string(out))
}

TypeScript

// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.
// The session cookie is set by signing in. A script cannot set it itself.

const url = new URL("https://depot.example.com/api/v1/mdm/os-releases");
url.searchParams.set("page", "0");
url.searchParams.set("pageSize", "0");
url.searchParams.set("platform", "<platform>");

const response = await fetch(url, {
  method: "GET",
  headers: {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
  },
  credentials: "include",
});

if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);

C#

// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.

using System;
using System.Net.Http;

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://depot.example.com/api/v1/mdm/os-releases?page=0&pageSize=0&platform=<platform>");
request.Headers.TryAddWithoutValidation("X-CSRF-Token", "<csrf-token>");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("Cookie", "outpost_console=<console-session>");

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());

GET /api/v1/mdm/os-updates/report

GETmdm:readtenant facehosteditmspremoteIdempotent

From an MSP console, prefix the path with /api/v1/clients/{clientID} to reach one client.

Source: [object Object]

getMdmOsUpdateReport reports how many devices per platform are on their OS update target, pending (with deadlines) or unable to reach it (with reasons).

?state= and ?platform= (comma-separated) filter the device list; the totals always cover every device.

Parameters

Name	In	Type	Required	Description
page	query	integer	No	One-based page number. Defaults to 1.
pageSize	query	integer	No	Rows per page, 1 to 200. Defaults to 50.
platform	query	string, one of android, darwin, ios, tvos, windows	No	Comma-separated set. An unrecognised value is refused.
state	query	string, one of cannot_reach, not_applicable, on_target, pending	No	Comma-separated set. An unrecognised value is refused.

Responses

Status	Body	Description
200	application/json, OsUpdateReportView	Success.
400	application/problem+json, ProblemDetails	One or more validation errors occurred.
401	application/problem+json, ProblemDetails	No signed-in identity.
403	application/problem+json, ProblemDetails	The identity does not hold mdm:read.
500	application/problem+json, ProblemDetails	No client context in request.

200 response body

Field	Type	Description
itemsrequired	array of OsUpdateDeviceView
items[].agentIdrequired	string
items[].currentVersion	string or null
items[].deadlineAt	string (date-time) or null
items[].evaluatedAtrequired	string (date-time)
items[].hostnamerequired	string
items[].overduerequired	boolean
items[].platformrequired	string
items[].reason	MdmReasonView	mdmReasonView is the wire Reason (contract 7.3).
items[].reason.fixrequired	string
items[].reason.keyrequired	string
items[].reason.plainrequired	string
items[].reason.retryablerequired	boolean
items[].reasonCode	string or null
items[].staterequired	string
items[].targetVersion	string or null
pagerequired	integer
pageSizerequired	integer
platformsrequired	array of OsUpdatePlatformView
platforms[].cannotReachrequired	integer
platforms[].notApplicablerequired	integer
platforms[].onTargetrequired	integer
platforms[].overduerequired	integer
platforms[].pendingrequired	integer
platforms[].platformrequired	string
platforms[].reasonsrequired	array of OsUpdateReasonCount
platforms[].reasons[].countrequired	integer
platforms[].reasons[].reason	MdmReasonView	mdmReasonView is the wire Reason (contract 7.3).
platforms[].reasons[].reason.fixrequired	string
platforms[].reasons[].reason.keyrequired	string
platforms[].reasons[].reason.plainrequired	string
platforms[].reasons[].reason.retryablerequired	boolean
platforms[].reasons[].reasonCoderequired	string
totalrequired	integer

Request samples

curl

# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.
curl -X GET 'https://depot.example.com/api/v1/mdm/os-updates/report?page=0&pageSize=0&platform=android&state=cannot_reach' \
  -H 'X-CSRF-Token: <csrf-token>' \
  -H 'Accept: application/json' \
  -b 'outpost_console=<console-session>'

PowerShell

# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.

$headers = @{
    'X-CSRF-Token' = '<csrf-token>'
    'Accept' = 'application/json'
    'Cookie' = 'outpost_console=<console-session>'
}

$response = Invoke-RestMethod `
    -Method Get `
    -Uri 'https://depot.example.com/api/v1/mdm/os-updates/report?page=0&pageSize=0&platform=android&state=cannot_reach' `
    -Headers $headers

$response | ConvertTo-Json -Depth 10

Python

# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation is idempotent. Repeating it does not repeat its effect.

import requests

url = "https://depot.example.com/api/v1/mdm/os-updates/report"
params = {
    "page": "0",
    "pageSize": "0",
    "platform": "android",
    "state": "cannot_reach",
}
headers = {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
}
cookies = {
    "outpost_console": "<console-session>",
}

response = requests.get(url, params=params, headers=headers, cookies=cookies, timeout=30)
response.raise_for_status()
print(response.json())

Go

// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.
package main

import (
  "fmt"
  "io"
  "log"
  "net/http"
)

func main() {
  req, err := http.NewRequest(http.MethodGet, "https://depot.example.com/api/v1/mdm/os-updates/report?page=0&pageSize=0&platform=android&state=cannot_reach", nil)
  if err != nil {
    log.Fatal(err)
  }

  req.Header.Set("X-CSRF-Token", "<csrf-token>")
  req.Header.Set("Accept", "application/json")
  req.AddCookie(&http.Cookie{Name: "outpost_console", Value: "<console-session>"})

  resp, err := http.DefaultClient.Do(req)
  if err != nil {
    log.Fatal(err)
  }
  defer resp.Body.Close()

  out, err := io.ReadAll(resp.Body)
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(resp.Status, string(out))
}

TypeScript

// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.
// The session cookie is set by signing in. A script cannot set it itself.

const url = new URL("https://depot.example.com/api/v1/mdm/os-updates/report");
url.searchParams.set("page", "0");
url.searchParams.set("pageSize", "0");
url.searchParams.set("platform", "android");
url.searchParams.set("state", "cannot_reach");

const response = await fetch(url, {
  method: "GET",
  headers: {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
  },
  credentials: "include",
});

if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);

C#

// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation is idempotent. Repeating it does not repeat its effect.

using System;
using System.Net.Http;

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Get, "https://depot.example.com/api/v1/mdm/os-updates/report?page=0&pageSize=0&platform=android&state=cannot_reach");
request.Headers.TryAddWithoutValidation("X-CSRF-Token", "<csrf-token>");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("Cookie", "outpost_console=<console-session>");

var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine(await response.Content.ReadAsStringAsync());