Minimal widgets

View as Markdown Open in ChatGPT Open in Claude

Widgets, the example resource.

This page is generated from the Minimal route table. Every operation carries the permission it needs and the anchor an agent can link to.

GET `/api/v1/widgets`

GETwidget:readtenant facemspitremotehostedNot fully resolved

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

What this page does not know

The sort parameter is validated in a helper the extractor does not follow, so its accepted values are not listed here.

These are parts of the route the extractor could not read from the source. Everything else on this page came straight from it.

Source: internal/api/widgets.go:mountWidgets handleWidgetList

List widgets

Returns one page of widgets. Results are ordered newest first.

Parameters

Name	In	Type	Required	Description
`page`	query	integer	No	One based page number.
`pageSize`	query	integer	No	Rows per page, up to 200.
`state`	query	string, one of active, retired	No	Only widgets in this state.

Responses

Status	Body	Description
`200`	`application/json`, PagedResultWidget	One page of widgets.
`400`	`application/problem+json`, Problem	The request was refused. The body says why.
`403`	`application/problem+json`, Problem	The request was refused. The body says why.

200 response body

Field	Type	Description
`items`required	`array of Widget`	This page of widgets.
`items[].id`required	`string (uuid)`	The widget identifier. read only.
`items[].name`required	`string`	What the widget is called. at most 200 characters.
`items[].state`required	`string, one of active, retired`	Whether the widget is in use.
`items[].labels`	`array of string`	Free form labels.
`items[].owner`	`WidgetOwner`	Who is responsible for the widget.
`items[].owner.userId`required	`string (uuid)`	The owning user.
`items[].owner.email`	`string (email)`	Where to reach the owner.
`items[].owner.notify`	`boolean`	Whether the owner is told about changes. default true.
`items[].retiredAt`	`string (date-time) or null`	When the widget was retired, or null while it is active.
`items[].createdAt`required	`string (date-time)`	When the widget was created. read only.
`page`required	`integer`	The page that was returned.
`pageSize`required	`integer`	How many rows were asked for.
`total`required	`integer`	How many widgets match in total.

Request samples

# Sign in first. outpost_console is a session cookie, so send it with every request.
curl -X GET 'https://depot.example.com/api/v1/widgets?page=1&pageSize=50&state=active' \
  -H 'Accept: application/json' \
  -b 'outpost_console=<console-session>'

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

$headers = @{
    'Accept' = 'application/json'
    'Cookie' = 'outpost_console=<console-session>'
}

$response = Invoke-RestMethod `
    -Method Get `
    -Uri 'https://depot.example.com/api/v1/widgets?page=1&pageSize=50&state=active' `
    -Headers $headers

$response | ConvertTo-Json -Depth 10

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

import requests

url = "https://depot.example.com/api/v1/widgets"
params = {
    "page": "1",
    "pageSize": "50",
    "state": "active",
}
headers = {
    "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())

// 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.MethodGet, "https://depot.example.com/api/v1/widgets?page=1&pageSize=50&state=active", nil)
  if err != nil {
    log.Fatal(err)
  }

  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))
}

// 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 = new URL("https://depot.example.com/api/v1/widgets");
url.searchParams.set("page", "1");
url.searchParams.set("pageSize", "50");
url.searchParams.set("state", "active");

const response = await fetch(url, {
  method: "GET",
  headers: {
    "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);

// 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.Get, "https://depot.example.com/api/v1/widgets?page=1&pageSize=50&state=active");
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/widgets`

POSTwidget:createmsp facemspitIdempotent

Source: internal/api/widgets.go:mountWidgets handleWidgetCreate

Create a widget

Creates a widget. Sending the same idempotency key twice creates one widget and returns it twice.

Request body

Required, sent as application/json.

Field	Type	Description
`name`required	`string`	What the widget is called. at most 200 characters.
`state`	`string, one of active, retired`	The state to create it in. default "active".
`labels`	`array of string`	Free form labels.
`owner`	`WidgetOwner`	Who is responsible for the widget.
`owner.userId`required	`string (uuid)`	The owning user.
`owner.email`	`string (email)`	Where to reach the owner.
`owner.notify`	`boolean`	Whether the owner is told about changes. default true.

Responses

Status	Body	Description
`201`	`application/json`, Widget	The widget that was created.
`400`	`application/problem+json`, Problem	The request was refused. The body says why.
`409`	`application/problem+json`, Problem	The request was refused. The body says why.

201 response body

Field	Type	Description
`id`required	`string (uuid)`	The widget identifier. read only.
`name`required	`string`	What the widget is called. at most 200 characters.
`state`required	`string, one of active, retired`	Whether the widget is in use.
`labels`	`array of string`	Free form labels.
`owner`	`WidgetOwner`	Who is responsible for the widget.
`owner.userId`required	`string (uuid)`	The owning user.
`owner.email`	`string (email)`	Where to reach the owner.
`owner.notify`	`boolean`	Whether the owner is told about changes. default true.
`retiredAt`	`string (date-time) or null`	When the widget was retired, or null while it is active.
`createdAt`required	`string (date-time)`	When the widget was created. read only.

Request samples

# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation also accepts provisionToken.
# This operation is idempotent. Repeating it does not repeat its effect.
curl -X POST 'https://depot.example.com/api/v1/widgets' \
  -H 'X-Csrf-Token: <csrf-token>' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -b 'outpost_console=<console-session>' \
  --data '{
  "name": "string",
  "state": "active",
  "labels": [
    "string"
  ],
  "owner": {
    "userId": "00000000-0000-0000-0000-000000000000",
    "email": "[email protected]",
    "notify": true
  }
}'

# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation also accepts provisionToken.
# 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 = @'
{
  "name": "string",
  "state": "active",
  "labels": [
    "string"
  ],
  "owner": {
    "userId": "00000000-0000-0000-0000-000000000000",
    "email": "[email protected]",
    "notify": true
  }
}
'@

$response = Invoke-RestMethod `
    -Method Post `
    -Uri 'https://depot.example.com/api/v1/widgets' `
    -Headers $headers `
    -ContentType 'application/json' `
    -Body $body

$response | ConvertTo-Json -Depth 10

# Sign in first. outpost_console is a session cookie, so send it with every request.
# This operation also accepts provisionToken.
# This operation is idempotent. Repeating it does not repeat its effect.

import requests

url = "https://depot.example.com/api/v1/widgets"
headers = {
    "X-Csrf-Token": "<csrf-token>",
    "Accept": "application/json",
    "Content-Type": "application/json",
}
cookies = {
    "outpost_console": "<console-session>",
}
payload = {
    "name": "string",
    "state": "active",
    "labels": [
        "string",
    ],
    "owner": {
        "userId": "00000000-0000-0000-0000-000000000000",
        "email": "[email protected]",
        "notify": True,
    },
}

response = requests.post(url, headers=headers, cookies=cookies, json=payload, timeout=30)
response.raise_for_status()
print(response.json())

// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation also accepts provisionToken.
// This operation is idempotent. Repeating it does not repeat its effect.
package main

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

func main() {
  body := []byte(`{
  "name": "string",
  "state": "active",
  "labels": [
    "string"
  ],
  "owner": {
    "userId": "00000000-0000-0000-0000-000000000000",
    "email": "[email protected]",
    "notify": true
  }
}`)

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

// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation also accepts provisionToken.
// 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/widgets";

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({
    "name": "string",
    "state": "active",
    "labels": [
      "string"
    ],
    "owner": {
      "userId": "00000000-0000-0000-0000-000000000000",
      "email": "[email protected]",
      "notify": true
    }
  }),
});

if (!response.ok) {
  throw new Error(`Request failed with status ${response.status}`);
}

const data = await response.json();
console.log(data);

// Sign in first. outpost_console is a session cookie, so send it with every request.
// This operation also accepts provisionToken.
// 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 = """
{
  "name": "string",
  "state": "active",
  "labels": [
    "string"
  ],
  "owner": {
    "userId": "00000000-0000-0000-0000-000000000000",
    "email": "[email protected]",
    "notify": true
  }
}
""";

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

Content is licensed CC BY 4.0. Code samples are MIT. Outpost and the Outpost mark are trademarks of Outpost Business Solutions, PBC and are not covered by either licence.

Minimal widgets

GET /api/v1/widgets

Parameters

Responses

Request samples

POST /api/v1/widgets

Request body

Responses

Request samples

GET `/api/v1/widgets`

POST `/api/v1/widgets`