Make a widget a preset, or replace a preset

Offers one of the partner’s own widgets as a preset under key. If the partner already has a preset under that key it is replaced, so sending the same request twice is safe. Saving replaces the whole preset: a title, description or position you leave out goes back to its default.

Keys are 1 to 64 characters: lowercase letters, digits, hyphens and underscores, the first a letter or a digit (rating, quiz-3).

The widget must belong to the partner’s account; a widget that does not exist and one that belongs to somebody else are refused in the same way (404 PRESET_WIDGET_NOT_FOUND). A widget is a preset under at most one key (409 PRESET_WIDGET_ALREADY_USED; details.key says which), and an account can have at most 100 presets (409 PRESET_LIMIT_REACHED).

Later changes to the widget reach new copies and new compositions; copies made earlier are not touched. Deleting the widget removes its preset.

PUT /partners/{partnerId}/presets/{key}

Make a widget a preset, or replace a preset

cURL

curl --request PUT \
  --url https://api.widgetic.com/v1/partners/{partnerId}/presets/{key} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "widgetId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "Example title",
  "description": "Example description",
  "position": 42
}
'

200

{
  "success": true,
  "data": {
    "key": "rating",
    "widgetId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "title": "Star rating",
    "description": "Example description",
    "position": 42,
    "widgetName": "Example widgetName",
    "thumbnailUrl": "Example thumbnailUrl",
    "createdAt": "2026-01-15T09:30:00.000Z",
    "updatedAt": "2026-01-15T09:30:00.000Z"
  },
  "meta": {
    "page": 1,
    "size": 20,
    "total": 135,
    "limit": 20,
    "offset": 0,
    "hasNextPage": true,
    "hasPreviousPage": false,
    "nextCursor": "<string>",
    "warnings": [
      "<string>"
    ]
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

partnerId · string<uuid> · required

The partner whose preset to set

key · string · required

The name your code uses for the preset

Pattern: ^[a-z0-9][a-z0-9_-]{0,63}$

Body

application/json

widgetId · string<uuid> · required

One of the partner's own widgets. A widget is a preset under at most one key.

title · string | null

What your picker shows. Leave it out to show the widget's own name.

Required string length: 1 - 120

description · string | null

Maximum string length: 500

position · integer · default: 0

Where the preset sits in the list. Smallest first; presets with the same position are ordered by key.

Required range: 0 <= x <= 10000

Response

200

application/json

The preset as saved

success · boolean · required

Always true on a success.

Example:

true

data · object · required

A widget the partner offers its managed users as a starting point, under a key the partner's code names. It belongs to the partner's account, so every managed user of the partner sees the same list.

Show child attributes

Example:

{
  "key": "rating",
  "widgetId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "title": "Star rating",
  "description": "Example description",
  "position": 42,
  "widgetName": "Example widgetName",
  "thumbnailUrl": "Example thumbnailUrl",
  "createdAt": "2026-01-15T09:30:00.000Z",
  "updatedAt": "2026-01-15T09:30:00.000Z"
}

meta · object

Extra information about the answer: where a page sits in a list, the cursor of the next page, or warnings about a call that succeeded with a caveat.

Show child attributes