---
title: "Minimal widgets"
description: "Every widgets operation in the Minimal API, with parameters, responses and code samples in six languages."
url: "https://support.outpostplatform.com/api/generated/minimal/widgets/"
product: "platform"
type: "reference"
status: "reviewed"
last_reviewed: 2026-09-13
source: "https://gitlab.com/outpostplatform/docs/-/edit/main/src/content/docs/api/generated/minimal/widgets.mdx"
license: "CC BY 4.0"
---

# Minimal widgets

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` {#example.widgets.list}

**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. |

#### Request samples

```bash
# 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>'
```

```powershell
# 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
```

```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/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())
```

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

```ts
// 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);
```

```csharp
// 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` {#example.widgets.create}

**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`.

#### 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. |

#### Request samples

```bash
# 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": "user@example.com",
    "notify": true
  }
}'
```

```powershell
# 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": "user@example.com",
    "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
```

```python
# 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": "user@example.com",
        "notify": True,
    },
}

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 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": "user@example.com",
    "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))
}
```

```ts
// 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": "user@example.com",
			"notify": true
		}
	}),
});

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

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

```csharp
// 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": "user@example.com",
    "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());
```