Depot softwarerequests

Registers the approval 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/requests

GETsoftware:readtenant facehosteditmspremoteIdempotent

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

Source: [object Object]

List software requests

Parameters

Name	In	Type	Required	Description
agentId	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 package, requested, state	No	Sort key.
state	query	string	No

Responses

Status	Body	Description
200	application/json, PagedResultSoftwareRequestView	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 SoftwareRequestView
items[].agentIdrequired	string
items[].decidedAt	string (date-time) or null
items[].decidedBy	string
items[].decisionNote	string
items[].deploymentId	string
items[].hostnamerequired	string
items[].justificationrequired	string
items[].packageIdrequired	string
items[].packageNamerequired	string
items[].publicIdrequired	string
items[].requestedAtrequired	string (date-time)
items[].requesterrequired	SoftwareRequesterView
items[].requester.displayNamerequired	string
items[].requester.identifierrequired	string
items[].requester.sidrequired	string
items[].staterequired	string
items[].ticketId	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/requests?agentId=<agentId>&dir=asc&packageId=<packageId>&page=0&pageSize=0&q=<q>' \
  -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/requests?agentId=<agentId>&dir=asc&packageId=<packageId>&page=0&pageSize=0&q=<q>' `
    -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/requests"
params = {
    "agentId": "<agentId>",
    "dir": "asc",
    "packageId": "<packageId>",
    "page": "0",
    "pageSize": "0",
    "q": "<q>",
}
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/requests?agentId=<agentId>&dir=asc&packageId=<packageId>&page=0&pageSize=0&q=<q>", 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/requests");
url.searchParams.set("agentId", "<agentId>");
url.searchParams.set("dir", "asc");
url.searchParams.set("packageId", "<packageId>");
url.searchParams.set("page", "0");
url.searchParams.set("pageSize", "0");
url.searchParams.set("q", "<q>");

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/requests?agentId=<agentId>&dir=asc&packageId=<packageId>&page=0&pageSize=0&q=<q>");
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/software/requests/{requestID}

GETsoftware:readtenant facehosteditmspremoteIdempotent

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

Source: [object Object]

Get software request

Parameters

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

Responses

Status	Body	Description
200	application/json, SoftwareRequestView	Success.
401	application/problem+json, ProblemDetails	No signed-in identity.
403	application/problem+json, ProblemDetails	The identity does not hold software:read.
404	application/problem+json, ProblemDetails	No resource matches that id.
500	application/problem+json, ProblemDetails	No client store in request context.

200 response body

Field	Type	Description
agentIdrequired	string
decidedAt	string (date-time) or null
decidedBy	string
decisionNote	string
deploymentId	string
hostnamerequired	string
justificationrequired	string
packageIdrequired	string
packageNamerequired	string
publicIdrequired	string
requestedAtrequired	string (date-time)
requesterrequired	SoftwareRequesterView
requester.displayNamerequired	string
requester.identifierrequired	string
requester.sidrequired	string
staterequired	string
ticketId	string

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/requests/<requestID>' \
  -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/requests/<requestID>' `
    -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/requests/<requestID>"
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/software/requests/<requestID>", 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/software/requests/<requestID>";

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/requests/<requestID>");
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/requests/{requestID}/approve

POSTsoftware:approvetenant facehosteditmspremoteIdempotent

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

Source: [object Object]

decideSoftwareRequest serves both approve and deny.

ONE HANDLER, TWO MOUNTS, because the two differ in exactly two places - whether an install is provisioned and what the ticket message says - and everything else about them is identical: the same guard, the same idempotence, the same ticket transition. Two handlers would be two copies of the ordering rules, and the ordering is the part that matters.

IDEMPOTENT AND IT PRESERVES THE ORIGINAL DECIDER. A request that is already decided is answered with the stored row and NOTHING is re-run: no second install, no second ticket message, no rewriting of who made the call. A retried POST from a flaky phone must not turn one approval into two installs.

Parameters

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

Request body

Required, sent as application/json.

Field	Type	Description
noterequired	string

Responses

Status	Body	Description
200	application/json, SoftwareRequestView	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 software:approve.
404	application/problem+json, ProblemDetails	No resource matches that id.
409	application/problem+json, ProblemDetails	That package has been retired from the catalog, so this request can no longer be approved. Deny it instead.
422	application/problem+json, ProblemDetails	The request was refused.
500	application/problem+json, ProblemDetails	No client context in request.

200 response body

Field	Type	Description
agentIdrequired	string
decidedAt	string (date-time) or null
decidedBy	string
decisionNote	string
deploymentId	string
hostnamerequired	string
justificationrequired	string
packageIdrequired	string
packageNamerequired	string
publicIdrequired	string
requestedAtrequired	string (date-time)
requesterrequired	SoftwareRequesterView
requester.displayNamerequired	string
requester.identifierrequired	string
requester.sidrequired	string
staterequired	string
ticketId	string

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/requests/<requestID>/approve' \
  -H 'X-CSRF-Token: <csrf-token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -b 'outpost_console=<console-session>' \
  --data '{
  "note": "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 = @'
{
  "note": "string"
}
'@

$response = Invoke-RestMethod `
    -Method Post `
    -Uri 'https://depot.example.com/api/v1/software/requests/<requestID>/approve' `
    -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/requests/<requestID>/approve"
headers = {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
    "Content-Type": "application/json",
}
cookies = {
    "outpost_console": "<console-session>",
}
payload = {
    "note": "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(`{
  "note": "string"
}`)

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

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({
    "note": "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 = """
{
  "note": "string"
}
""";

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

POST /api/v1/software/requests/{requestID}/deny

POSTsoftware:approvetenant facehosteditmspremoteIdempotent

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

Source: [object Object]

decideSoftwareRequest serves both approve and deny.

ONE HANDLER, TWO MOUNTS, because the two differ in exactly two places - whether an install is provisioned and what the ticket message says - and everything else about them is identical: the same guard, the same idempotence, the same ticket transition. Two handlers would be two copies of the ordering rules, and the ordering is the part that matters.

IDEMPOTENT AND IT PRESERVES THE ORIGINAL DECIDER. A request that is already decided is answered with the stored row and NOTHING is re-run: no second install, no second ticket message, no rewriting of who made the call. A retried POST from a flaky phone must not turn one approval into two installs.

Parameters

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

Request body

Required, sent as application/json.

Field	Type	Description
noterequired	string

Responses

Status	Body	Description
200	application/json, SoftwareRequestView	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 software:approve.
404	application/problem+json, ProblemDetails	No resource matches that id.
409	application/problem+json, ProblemDetails	That package has been retired from the catalog, so this request can no longer be approved. Deny it instead.
422	application/problem+json, ProblemDetails	The request was refused.
500	application/problem+json, ProblemDetails	No client context in request.

200 response body

Field	Type	Description
agentIdrequired	string
decidedAt	string (date-time) or null
decidedBy	string
decisionNote	string
deploymentId	string
hostnamerequired	string
justificationrequired	string
packageIdrequired	string
packageNamerequired	string
publicIdrequired	string
requestedAtrequired	string (date-time)
requesterrequired	SoftwareRequesterView
requester.displayNamerequired	string
requester.identifierrequired	string
requester.sidrequired	string
staterequired	string
ticketId	string

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/requests/<requestID>/deny' \
  -H 'X-CSRF-Token: <csrf-token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -b 'outpost_console=<console-session>' \
  --data '{
  "note": "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 = @'
{
  "note": "string"
}
'@

$response = Invoke-RestMethod `
    -Method Post `
    -Uri 'https://depot.example.com/api/v1/software/requests/<requestID>/deny' `
    -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/requests/<requestID>/deny"
headers = {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
    "Content-Type": "application/json",
}
cookies = {
    "outpost_console": "<console-session>",
}
payload = {
    "note": "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(`{
  "note": "string"
}`)

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

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({
    "note": "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 = """
{
  "note": "string"
}
""";

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