Depot endpoints

Registers the endpoint registry routes on mux.

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/endpoints

GETendpoint:readtenant facehosteditmspremoteIdempotent

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

Source: [object Object]

List endpoints

Parameters

Name	In	Type	Required	Description
cpu	query	string	No
deviceClass	query	string	No
dir	query	string, one of asc, desc	No	Sort direction.
hasAgent	query	string	No
ids	query	string	No
manufacturer	query	string	No
maxMemoryBytes	query	string	No
minMemoryBytes	query	string	No
model	query	string	No
os	query	string	No
osFamily	query	string	No
page	query	integer	No	One-based page number. Defaults to 1.
pageSize	query	integer	No	Rows per page, 1 to 200. Defaults to 50.
q	query	string	No
role	query	string	No
serial	query	string	No
site	query	string	No
software	query	string	No
sort	query	string, one of health, lastSeen, memory, model, name, os, user	No	Sort key.
status	query	string	No
user	query	string	No
virtualization	query	string	No

Responses

Status	Body	Description
200	application/json, PagedResultEndpointSummary	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 endpoint:read.
500	application/problem+json, ProblemDetails	No client store in request context.

200 response body

Field	Type	Description
itemsrequired	array of EndpointSummary
items[].agentIdrequired	string
items[].alias	string
items[].assetTag	string
items[].capabilitiesrequired	array of string
items[].connectedrequired	boolean
items[].deviceClassrequired	string, one of computer, mobile, tv
items[].hasAgentrequired	boolean
items[].healthScorerequired	integer
items[].hostnamerequired	string
items[].lastSeenAt	string (date-time) or null
items[].loggedInUserrequired	string
items[].manufacturerrequired	string
items[].mdmEnrollmentPublicId	string or null
items[].mdmHeld	boolean
items[].metered	boolean or null
items[].modelrequired	string
items[].osDisplayNamerequired	string
items[].osFamilyrequired	string
items[].osVersionrequired	string
items[].ownershiprequired	string
items[].retiredAt	string (date-time) or null
items[].serialNumberrequired	string
items[].serverRolesrequired	array of string
items[].siteId	string
items[].siteName	string
items[].statusrequired	string
items[].totalMemoryBytesrequired	integer	int64.
items[].virtualPlatform	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/endpoints?cpu=<cpu>&deviceClass=<deviceClass>&dir=asc&hasAgent=<hasAgent>&ids=<ids>&manufacturer=<manufacturer>' \
  -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/endpoints?cpu=<cpu>&deviceClass=<deviceClass>&dir=asc&hasAgent=<hasAgent>&ids=<ids>&manufacturer=<manufacturer>' `
    -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/endpoints"
params = {
    "cpu": "<cpu>",
    "deviceClass": "<deviceClass>",
    "dir": "asc",
    "hasAgent": "<hasAgent>",
    "ids": "<ids>",
    "manufacturer": "<manufacturer>",
}
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/endpoints?cpu=<cpu>&deviceClass=<deviceClass>&dir=asc&hasAgent=<hasAgent>&ids=<ids>&manufacturer=<manufacturer>", 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/endpoints");
url.searchParams.set("cpu", "<cpu>");
url.searchParams.set("deviceClass", "<deviceClass>");
url.searchParams.set("dir", "asc");
url.searchParams.set("hasAgent", "<hasAgent>");
url.searchParams.set("ids", "<ids>");
url.searchParams.set("manufacturer", "<manufacturer>");

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/endpoints?cpu=<cpu>&deviceClass=<deviceClass>&dir=asc&hasAgent=<hasAgent>&ids=<ids>&manufacturer=<manufacturer>");
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/endpoints/{agentID}

GETendpoint:readtenant facehosteditmspremoteIdempotent

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

Source: [object Object]

Get endpoint

Parameters

Name	In	Type	Required	Description
agentID	path	string	Yes

Responses

Status	Body	Description
200	application/json, EndpointDetail	Success.
401	application/problem+json, ProblemDetails	No signed-in identity.
403	application/problem+json, ProblemDetails	The identity does not hold endpoint:read.
404	application/problem+json, ProblemDetails	Endpoint not found.
500	application/problem+json, ProblemDetails	No client store in request context.

200 response body

Field	Type	Description
agentIdrequired	string
alias	string
appliedPolicyHashrequired	string
assetTag	string
capabilitiesrequired	array of string
checkInrequired	any	Arbitrary JSON.
connectedrequired	boolean
cpuModelrequired	string
deviceClassrequired	string, one of computer, mobile, tv
hasAgentrequired	boolean
healthScorerequired	integer
hostnamerequired	string
inventoryrequired	any	Arbitrary JSON.
inventoryUpdatedAt	string (date-time) or null
lastSeenAt	string (date-time) or null
loggedInUserrequired	string
manufacturerrequired	string
mdmEnrollmentPublicId	string or null
mdmHeld	boolean
metered	boolean or null
modelrequired	string
osDisplayNamerequired	string
osFamilyrequired	string
osVersionrequired	string
ownershiprequired	string
retiredAt	string (date-time) or null
roaming	array of RoamingNote
roaming[].agentIdsrequired	array of string
roaming[].clientIdrequired	string
roaming[].clientNamerequired	string
roaming[].kindsrequired	array of string
serialNumberrequired	string
serverRolesrequired	array of string
siteId	string
siteName	string
statusrequired	string
totalMemoryBytesrequired	integer	int64.
transfer	EndpointTransferState	endpointTransferState is the endpoint detail's transfer field: the open transfer, queued or in progress.
transfer.commandIdrequired	string
transfer.queuedAt	string (date-time) or null
transfer.staterequired	string
transfer.targetClientIdrequired	string
transfer.targetClientNamerequired	string
virtualPlatform	string
wake	WakeBlock	wakeBlock is whether Wake is offered for an endpoint and why not: the wake-status body and endpointDetail.wake.
wake.armed	boolean or null
wake.availablerequired	boolean
wake.fastStartup	boolean or null
wake.forceablerequired	boolean
wake.lastRequest	WakeRequestView	wakeRequestView is a WakeRequest as the wake block's lastRequest.
wake.lastRequest.createdAtrequired	string (date-time)
wake.lastRequest.originrequired	string
wake.lastRequest.reason	string or null
wake.lastRequest.resolvedAt	string (date-time) or null
wake.lastRequest.returnOutcome	string or null
wake.lastRequest.returnReason	string or null
wake.lastRequest.returnToSleeprequired	boolean
wake.lastRequest.staterequired	string
wake.lastRequest.wakeRequestIdrequired	string
wake.reason	string or null
wake.senderCountrequired	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/endpoints/<agentID>' \
  -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/endpoints/<agentID>' `
    -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/endpoints/<agentID>"
headers = {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
}
cookies = {
    "outpost_console": "<console-session>",
}

response = requests.get(url, 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/endpoints/<agentID>", 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 = "https://depot.example.com/api/v1/endpoints/<agentID>";

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/endpoints/<agentID>");
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());

DELETE /api/v1/endpoints/{agentID}

DELETEendpoint:writetenant facehosteditmspremoteIdempotent

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

Source: [object Object]

Retire endpoint

Parameters

Name	In	Type	Required	Description
agentID	path	string	Yes	A uuid.

Request body

Required, sent as application/json.

Field	Type	Description
reasonrequired	string

Responses

Status	Body	Description
204	None	Success, with no body.
400	application/problem+json, ProblemDetails	The request body is not valid JSON.
401	application/problem+json, ProblemDetails	No signed-in identity.
403	application/problem+json, ProblemDetails	The identity does not hold endpoint:write.
404	application/problem+json, ProblemDetails	No resource matches that id.
500	application/problem+json, ProblemDetails	No client context in request.

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 DELETE 'https://depot.example.com/api/v1/endpoints/<agentID>' \
  -H 'X-CSRF-Token: <csrf-token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -b 'outpost_console=<console-session>' \
  --data '{
  "reason": "string"
}'

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'
    'Content-Type' = 'application/json'
    'Cookie' = 'outpost_console=<console-session>'
}

$body = @'
{
  "reason": "string"
}
'@

$response = Invoke-RestMethod `
    -Method Delete `
    -Uri 'https://depot.example.com/api/v1/endpoints/<agentID>' `
    -Headers $headers `
    -ContentType 'application/json' `
    -Body $body

$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/endpoints/<agentID>"
headers = {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
    "Content-Type": "application/json",
}
cookies = {
    "outpost_console": "<console-session>",
}
payload = {
    "reason": "string",
}

response = requests.delete(url, headers=headers, cookies=cookies, json=payload, 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 (
  "bytes"
  "fmt"
  "io"
  "log"
  "net/http"
)

func main() {
  body := []byte(`{
  "reason": "string"
}`)

  req, err := http.NewRequest(http.MethodDelete, "https://depot.example.com/api/v1/endpoints/<agentID>", bytes.NewReader(body))
  if err != nil {
    log.Fatal(err)
  }

  req.Header.Set("X-CSRF-Token", "<csrf-token>")
  req.Header.Set("Accept", "application/json")
  req.Header.Set("Content-Type", "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 = "https://depot.example.com/api/v1/endpoints/<agentID>";

const response = await fetch(url, {
  method: "DELETE",
  headers: {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
    "Content-Type": "application/json",
  },
  credentials: "include",
  body: JSON.stringify({
    "reason": "string"
  }),
});

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 System.Text;

using var client = new HttpClient();

const string body = """
{
  "reason": "string"
}
""";

var request = new HttpRequestMessage(HttpMethod.Delete, "https://depot.example.com/api/v1/endpoints/<agentID>");
request.Headers.TryAddWithoutValidation("X-CSRF-Token", "<csrf-token>");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("Cookie", "outpost_console=<console-session>");
request.Content = new StringContent(body, Encoding.UTF8, "application/json");

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

PUT /api/v1/endpoints/{agentID}/alias

PUTendpoint:writetenant facehosteditmspremoteIdempotent

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

Source: [object Object]

setEndpointAlias writes the operator’s own name for a machine.

AUDITED, because this is the one field on an endpoint that no agent can account for. Everything else on the row can be traced back to what a machine reported; an alias only ever exists because a person typed it, so “who called it that, and what did they call it before” has no other source. Best-effort on the append for the reason every write in this package is: the change is already committed by the time the audit runs, and failing the response over the trail would tell the operator their save did not happen when it did.

Parameters

Name	In	Type	Required	Description
agentID	path	string	Yes

Request body

Required, sent as application/json.

Field	Type	Description
aliasrequired	string

Responses

Status	Body	Description
200	application/json, EndpointDetail	Success.
400	application/problem+json, ProblemDetails	The request body is not valid JSON.
401	application/problem+json, ProblemDetails	No signed-in identity.
403	application/problem+json, ProblemDetails	The identity does not hold endpoint:write.
404	application/problem+json, ProblemDetails	No such endpoint.
500	application/problem+json, ProblemDetails	No client store in request context.

200 response body

Field	Type	Description
agentIdrequired	string
alias	string
appliedPolicyHashrequired	string
assetTag	string
capabilitiesrequired	array of string
checkInrequired	any	Arbitrary JSON.
connectedrequired	boolean
cpuModelrequired	string
deviceClassrequired	string, one of computer, mobile, tv
hasAgentrequired	boolean
healthScorerequired	integer
hostnamerequired	string
inventoryrequired	any	Arbitrary JSON.
inventoryUpdatedAt	string (date-time) or null
lastSeenAt	string (date-time) or null
loggedInUserrequired	string
manufacturerrequired	string
mdmEnrollmentPublicId	string or null
mdmHeld	boolean
metered	boolean or null
modelrequired	string
osDisplayNamerequired	string
osFamilyrequired	string
osVersionrequired	string
ownershiprequired	string
retiredAt	string (date-time) or null
roaming	array of RoamingNote
roaming[].agentIdsrequired	array of string
roaming[].clientIdrequired	string
roaming[].clientNamerequired	string
roaming[].kindsrequired	array of string
serialNumberrequired	string
serverRolesrequired	array of string
siteId	string
siteName	string
statusrequired	string
totalMemoryBytesrequired	integer	int64.
transfer	EndpointTransferState	endpointTransferState is the endpoint detail's transfer field: the open transfer, queued or in progress.
transfer.commandIdrequired	string
transfer.queuedAt	string (date-time) or null
transfer.staterequired	string
transfer.targetClientIdrequired	string
transfer.targetClientNamerequired	string
virtualPlatform	string
wake	WakeBlock	wakeBlock is whether Wake is offered for an endpoint and why not: the wake-status body and endpointDetail.wake.
wake.armed	boolean or null
wake.availablerequired	boolean
wake.fastStartup	boolean or null
wake.forceablerequired	boolean
wake.lastRequest	WakeRequestView	wakeRequestView is a WakeRequest as the wake block's lastRequest.
wake.lastRequest.createdAtrequired	string (date-time)
wake.lastRequest.originrequired	string
wake.lastRequest.reason	string or null
wake.lastRequest.resolvedAt	string (date-time) or null
wake.lastRequest.returnOutcome	string or null
wake.lastRequest.returnReason	string or null
wake.lastRequest.returnToSleeprequired	boolean
wake.lastRequest.staterequired	string
wake.lastRequest.wakeRequestIdrequired	string
wake.reason	string or null
wake.senderCountrequired	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 PUT 'https://depot.example.com/api/v1/endpoints/<agentID>/alias' \
  -H 'X-CSRF-Token: <csrf-token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -b 'outpost_console=<console-session>' \
  --data '{
  "alias": "string"
}'

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'
    'Content-Type' = 'application/json'
    'Cookie' = 'outpost_console=<console-session>'
}

$body = @'
{
  "alias": "string"
}
'@

$response = Invoke-RestMethod `
    -Method Put `
    -Uri 'https://depot.example.com/api/v1/endpoints/<agentID>/alias' `
    -Headers $headers `
    -ContentType 'application/json' `
    -Body $body

$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/endpoints/<agentID>/alias"
headers = {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
    "Content-Type": "application/json",
}
cookies = {
    "outpost_console": "<console-session>",
}
payload = {
    "alias": "string",
}

response = requests.put(url, headers=headers, cookies=cookies, json=payload, 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 (
  "bytes"
  "fmt"
  "io"
  "log"
  "net/http"
)

func main() {
  body := []byte(`{
  "alias": "string"
}`)

  req, err := http.NewRequest(http.MethodPut, "https://depot.example.com/api/v1/endpoints/<agentID>/alias", bytes.NewReader(body))
  if err != nil {
    log.Fatal(err)
  }

  req.Header.Set("X-CSRF-Token", "<csrf-token>")
  req.Header.Set("Accept", "application/json")
  req.Header.Set("Content-Type", "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 = "https://depot.example.com/api/v1/endpoints/<agentID>/alias";

const response = await fetch(url, {
  method: "PUT",
  headers: {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
    "Content-Type": "application/json",
  },
  credentials: "include",
  body: JSON.stringify({
    "alias": "string"
  }),
});

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 System.Text;

using var client = new HttpClient();

const string body = """
{
  "alias": "string"
}
""";

var request = new HttpRequestMessage(HttpMethod.Put, "https://depot.example.com/api/v1/endpoints/<agentID>/alias");
request.Headers.TryAddWithoutValidation("X-CSRF-Token", "<csrf-token>");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("Cookie", "outpost_console=<console-session>");
request.Content = new StringContent(body, Encoding.UTF8, "application/json");

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

PATCH /api/v1/endpoints/{agentID}/site

PATCHendpoint:writetenant facehosteditmspremoteIdempotent

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

Source: [object Object]

setEndpointSite moves an endpoint to a site of this client, or clears its site.

Audited as endpoint.site_set with the before and after site. An unchanged site answers 200 with nothing written and nothing audited.

Parameters

Name	In	Type	Required	Description
agentID	path	string	Yes	A uuid.

Request body

Required, sent as application/json.

Field	Type	Description
siteId	string or null

Responses

Status	Body	Description
200	application/json, EndpointDetail	Success.
400	application/problem+json, ProblemDetails	The request body is not valid JSON.
401	application/problem+json, ProblemDetails	No signed-in identity.
403	application/problem+json, ProblemDetails	The identity does not hold endpoint:write.
404	application/problem+json, ProblemDetails	No resource matches that id.
409	application/problem+json, ProblemDetails	A retired endpoint cannot be moved to a site.
500	application/problem+json, ProblemDetails	No client store in request context.

200 response body

Field	Type	Description
agentIdrequired	string
alias	string
appliedPolicyHashrequired	string
assetTag	string
capabilitiesrequired	array of string
checkInrequired	any	Arbitrary JSON.
connectedrequired	boolean
cpuModelrequired	string
deviceClassrequired	string, one of computer, mobile, tv
hasAgentrequired	boolean
healthScorerequired	integer
hostnamerequired	string
inventoryrequired	any	Arbitrary JSON.
inventoryUpdatedAt	string (date-time) or null
lastSeenAt	string (date-time) or null
loggedInUserrequired	string
manufacturerrequired	string
mdmEnrollmentPublicId	string or null
mdmHeld	boolean
metered	boolean or null
modelrequired	string
osDisplayNamerequired	string
osFamilyrequired	string
osVersionrequired	string
ownershiprequired	string
retiredAt	string (date-time) or null
roaming	array of RoamingNote
roaming[].agentIdsrequired	array of string
roaming[].clientIdrequired	string
roaming[].clientNamerequired	string
roaming[].kindsrequired	array of string
serialNumberrequired	string
serverRolesrequired	array of string
siteId	string
siteName	string
statusrequired	string
totalMemoryBytesrequired	integer	int64.
transfer	EndpointTransferState	endpointTransferState is the endpoint detail's transfer field: the open transfer, queued or in progress.
transfer.commandIdrequired	string
transfer.queuedAt	string (date-time) or null
transfer.staterequired	string
transfer.targetClientIdrequired	string
transfer.targetClientNamerequired	string
virtualPlatform	string
wake	WakeBlock	wakeBlock is whether Wake is offered for an endpoint and why not: the wake-status body and endpointDetail.wake.
wake.armed	boolean or null
wake.availablerequired	boolean
wake.fastStartup	boolean or null
wake.forceablerequired	boolean
wake.lastRequest	WakeRequestView	wakeRequestView is a WakeRequest as the wake block's lastRequest.
wake.lastRequest.createdAtrequired	string (date-time)
wake.lastRequest.originrequired	string
wake.lastRequest.reason	string or null
wake.lastRequest.resolvedAt	string (date-time) or null
wake.lastRequest.returnOutcome	string or null
wake.lastRequest.returnReason	string or null
wake.lastRequest.returnToSleeprequired	boolean
wake.lastRequest.staterequired	string
wake.lastRequest.wakeRequestIdrequired	string
wake.reason	string or null
wake.senderCountrequired	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 PATCH 'https://depot.example.com/api/v1/endpoints/<agentID>/site' \
  -H 'X-CSRF-Token: <csrf-token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -b 'outpost_console=<console-session>' \
  --data '{
  "siteId": "string"
}'

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'
    'Content-Type' = 'application/json'
    'Cookie' = 'outpost_console=<console-session>'
}

$body = @'
{
  "siteId": "string"
}
'@

$response = Invoke-RestMethod `
    -Method Patch `
    -Uri 'https://depot.example.com/api/v1/endpoints/<agentID>/site' `
    -Headers $headers `
    -ContentType 'application/json' `
    -Body $body

$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/endpoints/<agentID>/site"
headers = {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
    "Content-Type": "application/json",
}
cookies = {
    "outpost_console": "<console-session>",
}
payload = {
    "siteId": "string",
}

response = requests.patch(url, headers=headers, cookies=cookies, json=payload, 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 (
  "bytes"
  "fmt"
  "io"
  "log"
  "net/http"
)

func main() {
  body := []byte(`{
  "siteId": "string"
}`)

  req, err := http.NewRequest(http.MethodPatch, "https://depot.example.com/api/v1/endpoints/<agentID>/site", bytes.NewReader(body))
  if err != nil {
    log.Fatal(err)
  }

  req.Header.Set("X-CSRF-Token", "<csrf-token>")
  req.Header.Set("Accept", "application/json")
  req.Header.Set("Content-Type", "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 = "https://depot.example.com/api/v1/endpoints/<agentID>/site";

const response = await fetch(url, {
  method: "PATCH",
  headers: {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
    "Content-Type": "application/json",
  },
  credentials: "include",
  body: JSON.stringify({
    "siteId": "string"
  }),
});

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 System.Text;

using var client = new HttpClient();

const string body = """
{
  "siteId": "string"
}
""";

var request = new HttpRequestMessage(HttpMethod.Patch, "https://depot.example.com/api/v1/endpoints/<agentID>/site");
request.Headers.TryAddWithoutValidation("X-CSRF-Token", "<csrf-token>");
request.Headers.TryAddWithoutValidation("Accept", "application/json");
request.Headers.TryAddWithoutValidation("Cookie", "outpost_console=<console-session>");
request.Content = new StringContent(body, Encoding.UTF8, "application/json");

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

GET /api/v1/endpoints/filter-options

GETendpoint:readtenant facehosteditmspremoteIdempotent

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

Source: [object Object]

Endpoint facets

Responses

Status	Body	Description
200	application/json, EndpointFacetsResponse	Success.
401	application/problem+json, ProblemDetails	No signed-in identity.
403	application/problem+json, ProblemDetails	The identity does not hold endpoint:read.
500	application/problem+json, ProblemDetails	No client store in request context.

200 response body

Field	Type	Description
customFields	array of EndpointCustomFieldFacet
customFields[].keyrequired	string
customFields[].kindrequired	string
customFields[].labelrequired	string
customFields[].valuesrequired	array of string
loggedInUsersrequired	array of string
manufacturersrequired	array of string
modelsrequired	array of string
osDisplayNamesrequired	array of string
serverRolesrequired	array of string
softwarerequired	array of string
tagLabelsrequired	object

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/endpoints/filter-options' \
  -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/endpoints/filter-options' `
    -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/endpoints/filter-options"
headers = {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
}
cookies = {
    "outpost_console": "<console-session>",
}

response = requests.get(url, 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/endpoints/filter-options", 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 = "https://depot.example.com/api/v1/endpoints/filter-options";

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/endpoints/filter-options");
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());