Skip to main content
PUT
Create or replace a custom stat definition

Authorizations

Authorization
string
header
required

Use an API key or OAuth access token. Enter only the token in the authorization dialog; requests send it as Authorization: Bearer <TOKEN>.

Create an API key in your workspace's Settings → API keys. Keys start with wm_api_ and only work in the workspace where they were created. Read-only keys can read data; creating, updating, or deleting data requires a read-write key.

OAuth access tokens are issued for connected Windmill applications.

Both token types use the authenticated user's workspace permissions. Each endpoint's permission requirements and the sharing settings of the requested items still apply.

Path Parameters

companyId
string
required

Company ID. A URL slug is also accepted. The caller must have access to this company.

Required string length: 1 - 128
Example:

"company-acme"

Body

application/json

Complete display configuration for a workspace custom stat.

stat
string
required

Identifier of the workspace custom stat to create or update. The write is scoped to the caller's workspace; global Windmill definitions are never modified.

Required string length: 1 - 100
Pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
Example:

"custom-items-completed"

valueType
enum<string>
required

Aggregation type. It can change only before values have been recorded for this definition. Changing it afterward returns 409; create a new definition for the new type.

Available options:
COUNT,
AGGREGATE,
AVERAGE
Example:

"COUNT"

label
string
required

Display name of the stat, from 1 to 200 characters.

Required string length: 1 - 200
Example:

"Items completed"

unitSingular
string
required

Singular display unit for the value, from 1 to 100 characters.

Required string length: 1 - 100
Example:

"item"

shortLabel
string

Compact display name, up to 100 characters. Resets to null when omitted.

Maximum string length: 100
Example:

"Completed"

description
string

What the stat measures, up to 1,000 characters. Resets to null when omitted.

Maximum string length: 1000
Example:

"Number of completed work items."

unitPlural
string

Plural display unit, up to 100 characters. Resets to null when omitted.

Maximum string length: 100
Example:

"items"

denominatorUnitSingular
string

Denominator display unit, up to 100 characters. Resets to null when omitted.

Maximum string length: 100
Example:

"item"

displayAsPercent
boolean

Whether clients should display a percentage. Resets to false when omitted.

Example:

false

icon
Icon · object

Display icon for the stat. Resets to null when omitted.

Response

The created or updated stat definition

statMetadata
Stat definition · object
required

The created or updated stat definition.