Depot softwaredeploy

Registers the deployment routes on the TENANT 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/software/deployments

GETsoftware:readtenant facehosteditmspremoteIdempotent

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

Source: [object Object]

List software deployments

Parameters

Name	In	Type	Required	Description
agentId	query	string	No
batchId	query	string	No
dir	query	string, one of asc, desc	No	Sort direction.
packageId	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	Free-text search term.
sort	query	string, one of completed, created, package, state	No	Sort key.
state	query	string	No

Responses

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

200 response body

Field	Type	Description
itemsrequired	array of SoftwareDeploymentView
items[].actionrequired	string
items[].agentIdrequired	string
items[].batchId	string
items[].commandIdrequired	string
items[].completedAt	string (date-time) or null
items[].createdAtrequired	string (date-time)
items[].detectionPassed	boolean or null
items[].errorDetail	string
items[].exitCode	integer or null
items[].hostnamerequired	string
items[].installedVersion	string
items[].originrequired	string
items[].packageIdrequired	string
items[].packageNamerequired	string
items[].packageVersionrequired	string
items[].publicIdrequired	string
items[].staterequired	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/software/deployments?agentId=<agentId>&batchId=<batchId>&dir=asc&packageId=<packageId>&page=0&pageSize=0' \
  -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/software/deployments?agentId=<agentId>&batchId=<batchId>&dir=asc&packageId=<packageId>&page=0&pageSize=0' `
    -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/software/deployments"
params = {
    "agentId": "<agentId>",
    "batchId": "<batchId>",
    "dir": "asc",
    "packageId": "<packageId>",
    "page": "0",
    "pageSize": "0",
}
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/software/deployments?agentId=<agentId>&batchId=<batchId>&dir=asc&packageId=<packageId>&page=0&pageSize=0", 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/software/deployments");
url.searchParams.set("agentId", "<agentId>");
url.searchParams.set("batchId", "<batchId>");
url.searchParams.set("dir", "asc");
url.searchParams.set("packageId", "<packageId>");
url.searchParams.set("page", "0");
url.searchParams.set("pageSize", "0");

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/software/deployments?agentId=<agentId>&batchId=<batchId>&dir=asc&packageId=<packageId>&page=0&pageSize=0");
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());

POST /api/v1/software/deployments

POSTsoftware:deploytenant facehosteditmspremoteIdempotent

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

Source: [object Object]

Deploy software

Request body

Required, sent as application/json.

Field	Type	Description
actionrequired	string
packageIdrequired	string
targetrequired	Target	Target is a run's endpoint selection, exactly as the console submitted it.
target.agentIds	array of string
target.groupIds	array of string
target.includeChildSites	boolean
target.kindrequired	string
target.siteIds	array of string
ttlHoursrequired	integer
versionIdrequired	string

Responses

Status	Body	Description
202	application/json, SoftwareDeployAccepted	Accepted.
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 software:deploy.
404	application/problem+json, ProblemDetails	Package not found.
409	application/problem+json, ProblemDetails	The request conflicts with the current state.
422	application/problem+json, ProblemDetails	This catalog entry records an approval decision for an installed title and has nothing to deploy.
500	application/problem+json, ProblemDetails	No client context in request.

202 response body

Field	Type	Description
batchIdrequired	string
dispatchedrequired	integer
pendingrequired	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 POST 'https://depot.example.com/api/v1/software/deployments' \
  -H 'X-CSRF-Token: <csrf-token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -b 'outpost_console=<console-session>' \
  --data '{
  "action": "string",
  "packageId": "string",
  "target": {
    "agentIds": [
      "string"
    ],
    "groupIds": [
      "string"
    ],
    "includeChildSites": false,
    "kind": "string",
    "siteIds": [
      "string"
    ]
  },
  "ttlHours": 0,
  "versionId": "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 = @'
{
  "action": "string",
  "packageId": "string",
  "target": {
    "agentIds": [
      "string"
    ],
    "groupIds": [
      "string"
    ],
    "includeChildSites": false,
    "kind": "string",
    "siteIds": [
      "string"
    ]
  },
  "ttlHours": 0,
  "versionId": "string"
}
'@

$response = Invoke-RestMethod `
    -Method Post `
    -Uri 'https://depot.example.com/api/v1/software/deployments' `
    -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/software/deployments"
headers = {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
    "Content-Type": "application/json",
}
cookies = {
    "outpost_console": "<console-session>",
}
payload = {
    "action": "string",
    "packageId": "string",
    "target": {
        "agentIds": [
            "string",
        ],
        "groupIds": [
            "string",
        ],
        "includeChildSites": False,
        "kind": "string",
        "siteIds": [
            "string",
        ],
    },
    "ttlHours": 0,
    "versionId": "string",
}

response = requests.post(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(`{
  "action": "string",
  "packageId": "string",
  "target": {
    "agentIds": [
      "string"
    ],
    "groupIds": [
      "string"
    ],
    "includeChildSites": false,
    "kind": "string",
    "siteIds": [
      "string"
    ]
  },
  "ttlHours": 0,
  "versionId": "string"
}`)

  req, err := http.NewRequest(http.MethodPost, "https://depot.example.com/api/v1/software/deployments", 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/software/deployments";

const response = await fetch(url, {
  method: "POST",
  headers: {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
    "Content-Type": "application/json",
  },
  credentials: "include",
  body: JSON.stringify({
    "action": "string",
    "packageId": "string",
    "target": {
      "agentIds": [
        "string"
      ],
      "groupIds": [
        "string"
      ],
      "includeChildSites": false,
      "kind": "string",
      "siteIds": [
        "string"
      ]
    },
    "ttlHours": 0,
    "versionId": "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 = """
{
  "action": "string",
  "packageId": "string",
  "target": {
    "agentIds": [
      "string"
    ],
    "groupIds": [
      "string"
    ],
    "includeChildSites": false,
    "kind": "string",
    "siteIds": [
      "string"
    ]
  },
  "ttlHours": 0,
  "versionId": "string"
}
""";

var request = new HttpRequestMessage(HttpMethod.Post, "https://depot.example.com/api/v1/software/deployments");
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());