Depot mspsearch

Registers cross-client search on the control-plane 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/search

GETsearch:queryshared facehosteditmspremoteIdempotent

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

Source: [object Object]

Search

Parameters

Name	In	Type	Required	Description
clientId	query	string	No
includeArchived	query	string	No
kinds	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.
pinnedClientId	query	string	No
q	query	string	No
scope	query	string	No

Responses

Status	Body	Description
200	application/json, SearchResponse	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 search:query.
500	application/problem+json, ProblemDetails	Could not list clients.
503	application/problem+json, ProblemDetails	Cross-client search is not available on this server.

200 response body

Field	Type	Description
countsByKindrequired	object
degradedKindsrequired	array of string
itemsrequired	array of SearchHitView
items[].agentId	string
items[].badgerequired	string
items[].capabilities	array of string
items[].clientNamerequired	string
items[].clientPublicIdrequired	string
items[].connectedrequired	boolean
items[].idrequired	string
items[].kindrequired	string
items[].matchedOnrequired	string
items[].parentId	string
items[].restrictedrequired	boolean
items[].scorerequired	integer
items[].subtitlerequired	string
items[].titlerequired	string
pagerequired	integer
pageSizerequired	integer
skippedKindsrequired	array of string
tooShortrequired	boolean
tookMsrequired	integer	int64.
totalrequired	integer
truncatedrequired	boolean
unavailableClientsrequired	array of 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/search?clientId=<clientId>&includeArchived=<includeArchived>&kinds=<kinds>&page=0&pageSize=0&pinnedClientId=<pinnedClientId>' \
  -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/search?clientId=<clientId>&includeArchived=<includeArchived>&kinds=<kinds>&page=0&pageSize=0&pinnedClientId=<pinnedClientId>' `
    -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/search"
params = {
    "clientId": "<clientId>",
    "includeArchived": "<includeArchived>",
    "kinds": "<kinds>",
    "page": "0",
    "pageSize": "0",
    "pinnedClientId": "<pinnedClientId>",
}
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/search?clientId=<clientId>&includeArchived=<includeArchived>&kinds=<kinds>&page=0&pageSize=0&pinnedClientId=<pinnedClientId>", 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/search");
url.searchParams.set("clientId", "<clientId>");
url.searchParams.set("includeArchived", "<includeArchived>");
url.searchParams.set("kinds", "<kinds>");
url.searchParams.set("page", "0");
url.searchParams.set("pageSize", "0");
url.searchParams.set("pinnedClientId", "<pinnedClientId>");

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/search?clientId=<clientId>&includeArchived=<includeArchived>&kinds=<kinds>&page=0&pageSize=0&pinnedClientId=<pinnedClientId>");
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/search

POSTsearch:queryshared facehosteditmspremote

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

Source: [object Object]

logSearchCommit records a cross-client search into the CONTROL chain, and - when the operator opened a specific client’s record - a second row into that client’s own chain.

THE SECOND ROW IS THE POINT. An MSP operator reading a tenant’s data is invisible from inside that tenant: the request never touched their console, their audit chain, or anything they can see. A “search.result_opened” row in the client’s own chain, naming the kind and the id, is the ONLY way a tenant’s audit log can show that somebody outside looked at their record. Writing it only into the control chain would put the evidence exclusively in the hands of the party it is evidence about.

Both appends are best effort and the response is always 204. A failed audit append must not fail a click: the operator has already navigated.

Request body

Required, sent as application/json.

Field	Type	Description
kindsrequired	array of string
landedOnResultsPagerequired	boolean
opened	object or null
opened.clientPublicIdrequired	string
opened.idrequired	string
opened.kindrequired	string
resultCountrequired	integer
termrequired	string

Responses

Status	Body	Description
204	None	Success, with no body.
400	application/problem+json, ProblemDetails	The request body is not acceptable.
401	application/problem+json, ProblemDetails	No signed-in identity.
403	application/problem+json, ProblemDetails	The identity does not hold search:query.

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/search' \
  -H 'X-CSRF-Token: <csrf-token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -b 'outpost_console=<console-session>' \
  --data '{
  "kinds": [
    "string"
  ],
  "landedOnResultsPage": false,
  "opened": {
    "clientPublicId": "string",
    "id": "string",
    "kind": "string"
  },
  "resultCount": 0,
  "term": "string"
}'

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

$body = @'
{
  "kinds": [
    "string"
  ],
  "landedOnResultsPage": false,
  "opened": {
    "clientPublicId": "string",
    "id": "string",
    "kind": "string"
  },
  "resultCount": 0,
  "term": "string"
}
'@

$response = Invoke-RestMethod `
    -Method Post `
    -Uri 'https://depot.example.com/api/v1/search' `
    -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.

import requests

url = "https://depot.example.com/api/v1/search"
headers = {
    "X-CSRF-Token": "<csrf-token>",
    "Accept": "application/json",
    "Content-Type": "application/json",
}
cookies = {
    "outpost_console": "<console-session>",
}
payload = {
    "kinds": [
        "string",
    ],
    "landedOnResultsPage": False,
    "opened": {
        "clientPublicId": "string",
        "id": "string",
        "kind": "string",
    },
    "resultCount": 0,
    "term": "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.
package main

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

func main() {
  body := []byte(`{
  "kinds": [
    "string"
  ],
  "landedOnResultsPage": false,
  "opened": {
    "clientPublicId": "string",
    "id": "string",
    "kind": "string"
  },
  "resultCount": 0,
  "term": "string"
}`)

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

const url = "https://depot.example.com/api/v1/search";

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({
    "kinds": [
      "string"
    ],
    "landedOnResultsPage": false,
    "opened": {
      "clientPublicId": "string",
      "id": "string",
      "kind": "string"
    },
    "resultCount": 0,
    "term": "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.

using System;
using System.Net.Http;
using System.Text;

using var client = new HttpClient();

const string body = """
{
  "kinds": [
    "string"
  ],
  "landedOnResultsPage": false,
  "opened": {
    "clientPublicId": "string",
    "id": "string",
    "kind": "string"
  },
  "resultCount": 0,
  "term": "string"
}
""";

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