Docs API reference

Named conditions

A meaning given a name once — "between_talks", "doors_open" — that any rule on any block can then refer to by key. Change what it means here and every screen using it follows. Conditions are built from SENSORS (the clock, the date, a data value, the live session); GET /named-conditions/sensors lists them with their operators, so you never have to guess. This is configuration, not content: a named condition says what something *means*, never what a screen shows.

List named conditions

GET /named-conditions rules

Every named condition in the workspace, by key.

Parameters

limit integer query

Page size, 1–200.

1–200. Default 50
cursor string query

The next_cursor of the previous page.

Responses

200 A page of named conditions.
401 Missing or invalid API key.
403 The key lacks the scope, or the role is read-only.

Response fields (200)

items object[] required
8 fields in items
- key string required
  
  Lowercase letters, digits and underscores. THE ADDRESS: rules store the key, so renaming means moving every reference.
- label string required
  
  What a person calls it. Defaults to the key.
- description string
  
  What it means, in one line.
- match string required
  
  How the top-level entries combine. Default all.
  
  One of all, any
- when object[] required
  
  At least one entry.
- reads_as string read-only
  
  The whole thing as a sentence.
- created_at integer read-only
- updated_at integer read-only
next_cursor string or null required

Pass as cursor for the next page; null on the last page.

Request

curl "https://www.wunderframe.com/api/v1/named-conditions?limit=50" \
  -H "Authorization: Bearer $WUNDERFRAME_API_KEY"

Response 200

{
  "items": [
    {
      "key": "friday_evening",
      "label": "Friday evening",
      "description": "After six, at the end of the week.",
      "match": "all",
      "when": [
        {
          "id": "c1",
          "sensor": "clock",
          "op": "after",
          "value": {
            "time": "18:00"
          }
        },
        {
          "id": "g1",
          "all": "any",
          "when": [
            {
              "id": "c2",
              "sensor": "weekday",
              "op": "in",
              "value": {
                "days": [
                  5
                ]
              }
            },
            {
              "id": "c3",
              "sensor": "weekday",
              "op": "in",
              "value": {
                "days": [
                  6
                ]
              }
            }
          ]
        }
      ],
      "reads_as": "the time is from 18:00 and (the weekday is Fri or the weekday is Sat)"
    }
  ],
  "next_cursor": null
}

Error example

Response 401

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key."
  }
}

Create or replace a named condition

POST /named-conditions rules

An upsert by key, the same as PUT /named-conditions/{key} — posting an existing key updates that one rather than making a second with the same name.

Request body required

key string required

Lowercase letters, digits and underscores. THE ADDRESS: rules store the key, so renaming means moving every reference.
label string required

What a person calls it. Defaults to the key.
description string

What it means, in one line.
match string required

How the top-level entries combine. Default all.

One of all, any
when object[] required

At least one entry.

Responses

200 The saved named condition.
400 The request is invalid — details.field names the field when there is one.
401 Missing or invalid API key.
403 The key lacks the scope, or the role is read-only.

Response fields (200)

key string required

Lowercase letters, digits and underscores. THE ADDRESS: rules store the key, so renaming means moving every reference.
label string required

What a person calls it. Defaults to the key.
description string

What it means, in one line.
match string required

How the top-level entries combine. Default all.

One of all, any
when object[] required

At least one entry.
reads_as string read-only

The whole thing as a sentence.
created_at integer read-only
updated_at integer read-only

Request

curl -X POST "https://www.wunderframe.com/api/v1/named-conditions" \
  -H "Authorization: Bearer $WUNDERFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "key": "friday_evening",
  "label": "Friday evening",
  "match": "all",
  "when": [
    {
      "id": "c1",
      "sensor": "clock",
      "op": "after",
      "value": {
        "time": "18:00"
      }
    },
    {
      "id": "g1",
      "all": "any",
      "when": [
        {
          "id": "c2",
          "sensor": "weekday",
          "op": "in",
          "value": {
            "days": [
              5
            ]
          }
        },
        {
          "id": "c3",
          "sensor": "weekday",
          "op": "in",
          "value": {
            "days": [
              6
            ]
          }
        }
      ]
    }
  ]
}'

Response 200

{
  "key": "friday_evening",
  "label": "Friday evening",
  "description": "After six, at the end of the week.",
  "match": "all",
  "when": [
    {
      "id": "c1",
      "sensor": "clock",
      "op": "after",
      "value": {
        "time": "18:00"
      }
    },
    {
      "id": "g1",
      "all": "any",
      "when": [
        {
          "id": "c2",
          "sensor": "weekday",
          "op": "in",
          "value": {
            "days": [
              5
            ]
          }
        },
        {
          "id": "c3",
          "sensor": "weekday",
          "op": "in",
          "value": {
            "days": [
              6
            ]
          }
        }
      ]
    }
  ],
  "reads_as": "the time is from 18:00 and (the weekday is Fri or the weekday is Sat)"
}

Error example

Response 400

{
  "error": {
    "code": "invalid",
    "message": "The request is invalid — `details.field` names the field when there is one."
  }
}

List the sensors a condition can read

GET /named-conditions/sensors rules

What sensor, property and op may be, generated from the sensors this deployment actually has — so it cannot drift from what the evaluator accepts. Each reading carries a ready-made example you can paste into when.

Responses

200 The sensor vocabulary.
401 Missing or invalid API key.
403 The key lacks the scope, or the role is read-only.

Response fields (200)

sensors object[]
3 fields in sensors
- sensor string
- label string
- readings object[]
  
  One per reading the sensor offers, each with its own operators and a ready-made example.
  4 fields in readings
  - property string
  - label string
  - ops object[]
    
    2 fields in ops
    
    op string
    
    label string
  - example object
    
    One reading, compared. sensor and op must come from /named-conditions/sensors.
    
    5 fields in example
    
    id string
    
    Any stable string. Generated if you leave it out.
    
    sensor string required
    
    What to read, e.g. clock, weekday, session, field, trait.
    
    property string
    
    WHICH reading, for a sensor that has several (the session's status vs its start). Omit for a sensor with one.
    
    op string required
    
    The comparison, e.g. after, is, in.
    
    value object
    
    Operator-specific, e.g. { "time": "18:00" }.

Request

curl "https://www.wunderframe.com/api/v1/named-conditions/sensors" \
  -H "Authorization: Bearer $WUNDERFRAME_API_KEY"

Response 200

{
  "sensors": [
    {
      "sensor": "session",
      "label": "The live session",
      "readings": [
        {
          "property": "status",
          "label": "where it is",
          "ops": [
            {
              "op": "is",
              "label": "is"
            },
            {
              "op": "is_not",
              "label": "is not"
            }
          ],
          "example": {
            "sensor": "session",
            "property": "status",
            "op": "is",
            "value": {
              "status": "live"
            }
          }
        }
      ]
    }
  ]
}

Error example

Response 401

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key."
  }
}

Get a named condition

GET /named-conditions/{key} rules

Parameters

key string required path

The named condition’s key.

Responses

200 The named condition.
401 Missing or invalid API key.
403 The key lacks the scope, or the role is read-only.
404 Not found in this workspace.

Response fields (200)

key string required

Lowercase letters, digits and underscores. THE ADDRESS: rules store the key, so renaming means moving every reference.
label string required

What a person calls it. Defaults to the key.
description string

What it means, in one line.
match string required

How the top-level entries combine. Default all.

One of all, any
when object[] required

At least one entry.
reads_as string read-only

The whole thing as a sentence.
created_at integer read-only
updated_at integer read-only

Request

curl "https://www.wunderframe.com/api/v1/named-conditions/friday_evening" \
  -H "Authorization: Bearer $WUNDERFRAME_API_KEY"

Response 200

{
  "key": "friday_evening",
  "label": "Friday evening",
  "description": "After six, at the end of the week.",
  "match": "all",
  "when": [
    {
      "id": "c1",
      "sensor": "clock",
      "op": "after",
      "value": {
        "time": "18:00"
      }
    },
    {
      "id": "g1",
      "all": "any",
      "when": [
        {
          "id": "c2",
          "sensor": "weekday",
          "op": "in",
          "value": {
            "days": [
              5
            ]
          }
        },
        {
          "id": "c3",
          "sensor": "weekday",
          "op": "in",
          "value": {
            "days": [
              6
            ]
          }
        }
      ]
    }
  ],
  "reads_as": "the time is from 18:00 and (the weekday is Fri or the weekday is Sat)"
}

Error example

Response 401

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key."
  }
}

Create or replace a named condition

PUT /named-conditions/{key} rules

Idempotent by key, so a system can sync its own vocabulary by replaying the same calls. A key in the body must match the path.

Parameters

key string required path

The named condition’s key.

Request body required

key string required

Lowercase letters, digits and underscores. THE ADDRESS: rules store the key, so renaming means moving every reference.
label string required

What a person calls it. Defaults to the key.
description string

What it means, in one line.
match string required

How the top-level entries combine. Default all.

One of all, any
when object[] required

At least one entry.

Responses

200 The saved named condition.
400 The request is invalid — details.field names the field when there is one.
401 Missing or invalid API key.
403 The key lacks the scope, or the role is read-only.

Response fields (200)

key string required

Lowercase letters, digits and underscores. THE ADDRESS: rules store the key, so renaming means moving every reference.
label string required

What a person calls it. Defaults to the key.
description string

What it means, in one line.
match string required

How the top-level entries combine. Default all.

One of all, any
when object[] required

At least one entry.
reads_as string read-only

The whole thing as a sentence.
created_at integer read-only
updated_at integer read-only

Request

curl -X PUT "https://www.wunderframe.com/api/v1/named-conditions/friday_evening" \
  -H "Authorization: Bearer $WUNDERFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "label": "Friday evening",
  "match": "all",
  "when": [
    {
      "id": "c1",
      "sensor": "clock",
      "op": "after",
      "value": {
        "time": "18:00"
      }
    },
    {
      "id": "g1",
      "all": "any",
      "when": [
        {
          "id": "c2",
          "sensor": "weekday",
          "op": "in",
          "value": {
            "days": [
              5
            ]
          }
        },
        {
          "id": "c3",
          "sensor": "weekday",
          "op": "in",
          "value": {
            "days": [
              6
            ]
          }
        }
      ]
    }
  ]
}'

Response 200

{
  "key": "friday_evening",
  "label": "Friday evening",
  "description": "After six, at the end of the week.",
  "match": "all",
  "when": [
    {
      "id": "c1",
      "sensor": "clock",
      "op": "after",
      "value": {
        "time": "18:00"
      }
    },
    {
      "id": "g1",
      "all": "any",
      "when": [
        {
          "id": "c2",
          "sensor": "weekday",
          "op": "in",
          "value": {
            "days": [
              5
            ]
          }
        },
        {
          "id": "c3",
          "sensor": "weekday",
          "op": "in",
          "value": {
            "days": [
              6
            ]
          }
        }
      ]
    }
  ],
  "reads_as": "the time is from 18:00 and (the weekday is Fri or the weekday is Sat)"
}

Error example

Response 400

{
  "error": {
    "code": "invalid",
    "message": "The request is invalid — `details.field` names the field when there is one."
  }
}

Delete a named condition

DELETE /named-conditions/{key} rules

A rule still referring to it simply stops holding — it never starts holding instead, so this cannot make a screen change by itself.

Parameters

key string required path

The named condition’s key.

Responses

204 Deleted.
401 Missing or invalid API key.
403 The key lacks the scope, or the role is read-only.
404 Not found in this workspace.

Request

curl -X DELETE "https://www.wunderframe.com/api/v1/named-conditions/friday_evening" \
  -H "Authorization: Bearer $WUNDERFRAME_API_KEY"

204 — no body.

Error example

Response 401

{
  "error": {
    "code": "unauthorized",
    "message": "Missing or invalid API key."
  }
}