Depot scriptruns

Registers the bulk-run and batch 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/script-batches

GETscript:readtenant facehosteditmspremoteIdempotent

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

Source: [object Object]

List script batches

Parameters

Name	In	Type	Required	Description
dir	query	string, one of asc, desc	No	Sort direction.
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.
scriptId	query	string	No
sort	query	string, one of created, endpoints, expires, script	No	Sort key.
state	query	string	No

Responses

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

200 response body

Field	Type	Description
itemsrequired	array of ScriptBatchView
items[].cancelledAt	string (date-time) or null
items[].createdAtrequired	string (date-time)
items[].createdByrequired	string
items[].expiresAtrequired	string (date-time)
items[].publicIdrequired	string
items[].runAsrequired	string
items[].scriptNamerequired	string
items[].scriptPublicIdrequired	string
items[].scriptVersionrequired	integer
items[].targetKindrequired	string
items[].timeoutSecondsrequired	integer
items[].totalEndpointsrequired	integer
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/script-batches?dir=asc&page=0&pageSize=0&q=<q>&scriptId=<scriptId>&sort=created' \
  -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/script-batches?dir=asc&page=0&pageSize=0&q=<q>&scriptId=<scriptId>&sort=created' `
    -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/script-batches"
params = {
    "dir": "asc",
    "page": "0",
    "pageSize": "0",
    "q": "<q>",
    "scriptId": "<scriptId>",
    "sort": "created",
}
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/script-batches?dir=asc&page=0&pageSize=0&q=<q>&scriptId=<scriptId>&sort=created", 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/script-batches");
url.searchParams.set("dir", "asc");
url.searchParams.set("page", "0");
url.searchParams.set("pageSize", "0");
url.searchParams.set("q", "<q>");
url.searchParams.set("scriptId", "<scriptId>");
url.searchParams.set("sort", "created");

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/script-batches?dir=asc&page=0&pageSize=0&q=<q>&scriptId=<scriptId>&sort=created");
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/script-batches/{batchId}

GETscript:readtenant facehosteditmspremoteIdempotent

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

Source: [object Object]

Get script batch

Parameters

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

Responses

Status	Body	Description
200	application/json, ScriptBatchDetailView	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 script: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
batchrequired	ScriptBatchView
batch.cancelledAt	string (date-time) or null
batch.createdAtrequired	string (date-time)
batch.createdByrequired	string
batch.expiresAtrequired	string (date-time)
batch.publicIdrequired	string
batch.runAsrequired	string
batch.scriptNamerequired	string
batch.scriptPublicIdrequired	string
batch.scriptVersionrequired	integer
batch.targetKindrequired	string
batch.timeoutSecondsrequired	integer
batch.totalEndpointsrequired	integer
countsrequired	object
rowsrequired	PagedResultScriptBatchRowView	PagedResult is the generic envelope for paginated list responses.
rows.itemsrequired	array of ScriptBatchRowView
rows.items[].agentIdrequired	string
rows.items[].commandIdrequired	string
rows.items[].completedAt	string (date-time) or null
rows.items[].exitCode	integer or null
rows.items[].hostnamerequired	string
rows.items[].startedAt	string (date-time) or null
rows.items[].staterequired	string
rows.pagerequired	integer
rows.pageSizerequired	integer
rows.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/script-batches/<batchId>?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/script-batches/<batchId>?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/script-batches/<batchId>"
params = {
    "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/script-batches/<batchId>?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/script-batches/<batchId>");
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/script-batches/<batchId>?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/script-batches/{batchId}/cancel

POSTcommand:executetenant facehosteditmspremote

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

Source: [object Object]

Cancel script batch

Parameters

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

Responses

Status	Body	Description
200	application/json, ScriptBatchCancelled	Success.
401	application/problem+json, ProblemDetails	No signed-in identity.
403	application/problem+json, ProblemDetails	The identity does not hold command:execute.
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
cancelledrequired	integer	int64.

Request samples

curl

# Sign in first. outpost_console is a session cookie, so send it with every request.
curl -X POST 'https://depot.example.com/api/v1/script-batches/<batchId>/cancel' \
  -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.

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

$response = Invoke-RestMethod `
    -Method Post `
    -Uri 'https://depot.example.com/api/v1/script-batches/<batchId>/cancel' `
    -Headers $headers

$response | ConvertTo-Json -Depth 10

Python

# Sign in first. outpost_console is a session cookie, so send it with every request.

import requests

url = "https://depot.example.com/api/v1/script-batches/<batchId>/cancel"
headers = {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
}
cookies = {
    "outpost_console": "<console-session>",
}

response = requests.post(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.
package main

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

func main() {
  req, err := http.NewRequest(http.MethodPost, "https://depot.example.com/api/v1/script-batches/<batchId>/cancel", 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.
// The session cookie is set by signing in. A script cannot set it itself.

const url = "https://depot.example.com/api/v1/script-batches/<batchId>/cancel";

const response = await fetch(url, {
  method: "POST",
  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.

using System;
using System.Net.Http;

using var client = new HttpClient();

var request = new HttpRequestMessage(HttpMethod.Post, "https://depot.example.com/api/v1/script-batches/<batchId>/cancel");
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/scripts/{scriptId}/runs

POSTcommand:executetenant facehosteditmspremoteIdempotent

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

Source: [object Object]

runScriptBatch resolves the script through the two-library ladder rather than the control store, so a client’s OWN script is runnable across that client’s fleet.

Reading only the shared library here would leave every client-scoped script un-runnable in bulk, behind a 404 naming nothing.

Parameters

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

Request body

Required, sent as application/json.

Field	Type	Description
expectedBodySha256required	string
paramValuesrequired	object
runAsrequired	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
timeoutSecondsrequired	integer
ttlHoursrequired	integer

Responses

Status	Body	Description
202	application/json, ScriptRunAccepted	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 command:execute.
404	application/problem+json, ProblemDetails	No resource matches that id.
409	application/problem+json, ProblemDetails	The script changed after it was shown for approval. Review it again before running it.
422	application/problem+json, ProblemDetails	The request was refused.
500	application/problem+json, ProblemDetails	No client context in request.
503	application/problem+json, ProblemDetails	The script library is not available on this Depot.

202 response body

Field	Type	Description
batchIdrequired	string
dispatchedrequired	integer
pendingrequired	integer
skippedrequired	array of Skipped
skipped[].agentIdrequired	string
skipped[].hostnamerequired	string
skipped[].reasonrequired	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 POST 'https://depot.example.com/api/v1/scripts/<scriptId>/runs' \
  -H 'X-CSRF-Token: <csrf-token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -b 'outpost_console=<console-session>' \
  --data '{
  "expectedBodySha256": "string",
  "paramValues": {
    "key": "string"
  },
  "runAs": "string",
  "target": {
    "agentIds": [
      "string"
    ],
    "groupIds": [
      "string"
    ],
    "includeChildSites": false,
    "kind": "string",
    "siteIds": [
      "string"
    ]
  },
  "timeoutSeconds": 0,
  "ttlHours": 0
}'

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 = @'
{
  "expectedBodySha256": "string",
  "paramValues": {
    "key": "string"
  },
  "runAs": "string",
  "target": {
    "agentIds": [
      "string"
    ],
    "groupIds": [
      "string"
    ],
    "includeChildSites": false,
    "kind": "string",
    "siteIds": [
      "string"
    ]
  },
  "timeoutSeconds": 0,
  "ttlHours": 0
}
'@

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

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(`{
  "expectedBodySha256": "string",
  "paramValues": {
    "key": "string"
  },
  "runAs": "string",
  "target": {
    "agentIds": [
      "string"
    ],
    "groupIds": [
      "string"
    ],
    "includeChildSites": false,
    "kind": "string",
    "siteIds": [
      "string"
    ]
  },
  "timeoutSeconds": 0,
  "ttlHours": 0
}`)

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

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({
    "expectedBodySha256": "string",
    "paramValues": {
      "key": "string"
    },
    "runAs": "string",
    "target": {
      "agentIds": [
        "string"
      ],
      "groupIds": [
        "string"
      ],
      "includeChildSites": false,
      "kind": "string",
      "siteIds": [
        "string"
      ]
    },
    "timeoutSeconds": 0,
    "ttlHours": 0
  }),
});

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 = """
{
  "expectedBodySha256": "string",
  "paramValues": {
    "key": "string"
  },
  "runAs": "string",
  "target": {
    "agentIds": [
      "string"
    ],
    "groupIds": [
      "string"
    ],
    "includeChildSites": false,
    "kind": "string",
    "siteIds": [
      "string"
    ]
  },
  "timeoutSeconds": 0,
  "ttlHours": 0
}
""";

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