Skip to content
Plune Plune Plune Docs

Change a widget

PATCH
/v1/widgets/{id}
 
curl --request PATCH \
  --url https://beta-api.plune.ai/v1/widgets/example \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "title": "Runs and failures", "position": 1 }'

Title, recipe or place (position). The recipe is judged and costed as on creation.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
id
required
string

Request Body required

Section titled “Request Body required ”
Media type application/json

Any of the three fields; an empty object is refused (400).

object
title
string
>= 1 characters <= 120 characters
config

The whole recipe of a widget; the server judges it on every write and every draft. Entities: case, run_result, run, requirement (a defect is not one yet). Properties come from a closed catalogue: a case has type, state, priority, suite, is_flaky, is_muted, tag; a result status, sub_status, source, muted, case_priority, environment, label; a run kind, environment, status_event, label; a requirement type, status, priority, category. A donut takes one block. A segment is cut across all blocks and only by a property they all have (label for runs and results; any groupable property for a single entity). Limits: 5 blocks, 10 segment values, 10 filters a block, 16 KiB.

object
schemaVersion
required
integer
Allowed values: 1
render
required
string
Allowed values: bar line donut table
bucket
string
default: day
Allowed values: day week month
accumulated

Line only: the population at each moment. For run_result and run (they only arrive); a case, a requirement and a defect wait.

boolean
blocks
required
Array<object>
>= 1 items <= 5 items
object
entity
required
string
Allowed values: case run_result run requirement
metric

A duration only for run_result and run.

string
default: count
Allowed values: count duration_sum duration_avg
filters
Array<object>
<= 10 items
object
property
required
string
values
required
Array<string>
>= 1 items <= 50 items
groupBy

A groupable property of the entity. More than 20 groups: the rest is folded into «Other» with a true sum.

string
segment
object
by
required
string
values
required
Array<string>
>= 1 items <= 10 items
position
integer
<= 10000
Example 
{
  "title": "Runs and failures",
  "position": 1
}

Responses

Section titled “ Responses ”

200

Section titled “200 ”

The widget as it is now

Media type application/json
object
id
required
string format: uuid
projectId
required
string
title
required
string
>= 1 characters <= 120 characters
config
required

The whole recipe of a widget; the server judges it on every write and every draft. Entities: case, run_result, run, requirement (a defect is not one yet). Properties come from a closed catalogue: a case has type, state, priority, suite, is_flaky, is_muted, tag; a result status, sub_status, source, muted, case_priority, environment, label; a run kind, environment, status_event, label; a requirement type, status, priority, category. A donut takes one block. A segment is cut across all blocks and only by a property they all have (label for runs and results; any groupable property for a single entity). Limits: 5 blocks, 10 segment values, 10 filters a block, 16 KiB.

object
schemaVersion
required
integer
Allowed values: 1
render
required
string
Allowed values: bar line donut table
bucket
string
default: day
Allowed values: day week month
accumulated

Line only: the population at each moment. For run_result and run (they only arrive); a case, a requirement and a defect wait.

boolean
blocks
required
Array<object>
>= 1 items <= 5 items
object
entity
required
string
Allowed values: case run_result run requirement
metric

A duration only for run_result and run.

string
default: count
Allowed values: count duration_sum duration_avg
filters
Array<object>
<= 10 items
object
property
required
string
values
required
Array<string>
>= 1 items <= 50 items
groupBy

A groupable property of the entity. More than 20 groups: the rest is folded into «Other» with a true sum.

string
segment
object
by
required
string
values
required
Array<string>
>= 1 items <= 10 items
position
required

The order on the dashboard.

integer
createdBy
required
string
nullable
createdAt
required
string format: date-time
updatedAt
required
string format: date-time
Example 
{
  "id": "6f1c2b3a-0000-4000-8000-0000000000b4",
  "projectId": "u-shop::default",
  "title": "Runs and failures",
  "config": {
    "schemaVersion": 1,
    "render": "line",
    "bucket": "day",
    "accumulated": false,
    "blocks": [
      {
        "entity": "run",
        "metric": "count",
        "filters": [
          {
            "property": "kind",
            "values": [
              "automated"
            ]
          }
        ]
      },
      {
        "entity": "run_result",
        "metric": "count",
        "filters": [
          {
            "property": "status",
            "values": [
              "failed",
              "broken"
            ]
          }
        ]
      }
    ],
    "segment": {
      "by": "label",
      "values": [
        "nightly"
      ]
    }
  },
  "position": 1,
  "createdBy": "u-shop",
  "createdAt": "2026-09-16T09:12:04.151Z",
  "updatedAt": "2026-09-16T09:12:04.151Z"
}

400

Section titled “400 ”

Invalid body, nothing to change, or over the cost budget

Media type application/json
object
error
required
string
Example generated
{
  "error": "example"
}

401

Section titled “401 ”

No / invalid token or session

403

Section titled “403 ”

A read-only member

Media type application/json
object
error
required
string
Example generated
{
  "error": "example"
}

404

Section titled “404 ”

No such widget in the project

Media type application/json
object
error
required
string
Example generated
{
  "error": "example"
}

429

Section titled “429 ”

Rate-limited: the per-route throttle, or the per-minute request limit of the plan an API token counts by (#1442; the body names the plan, #2092). Retry-After carries the seconds until the window rolls over.

Media type application/json
object
error
required
string
Example generated
{
  "error": "example"
}

Headers

Section titled “Headers ”
Retry-After
integer

Seconds until the window rolls over