{
  "openapi": "3.0.3",
  "info": {
    "title": "A/I",
    "version": "1.1.0",
    "contact": {
      "name": "A/I Integration support",
      "url": "https://www.hotek.com",
      "email": "api@hotek.nl"
    },
    "description": "The A/I API manages customers, locations, gateways and the devices behind them, and reads device state and capabilities.\n\n## Use cases\n\n| Use case | Endpoint |\n|---|---|\n| [Find a door](#/get-v1-search-devices) | `GET /v1/search/devices?query=door1` |\n| [All doors](#/get-v1-devices) | `GET /v1/devices` |\n| [One door with its actions](#/get-v1-devices-device) | `GET /v1/devices/{device}` |\n| [All locations](#/get-v1-locations) | `GET /v1/locations` |\n| [Find a location](#/get-v1-search-locations) | `GET /v1/search/locations?query=USA` |\n| [Doors at a location](#/get-v1-locations-location-devices) | `GET /v1/locations/{location}/devices` |\n| [Open, close or toggle a door](#/get-v1-actions-action) | `GET /v1/actions/{action}`, with a URL from the `actions` of `GET /v1/devices/{device}` |\n\n## Authentication\n\nEvery endpoint except token issuing needs a bearer token. Request one with `POST /v1/auth/token` (email, password and a device name) and send it on each request:\n\n```\nAuthorization: Bearer <token>\n```\n\nWhat a token may see and change depends on the role of the consumer it belongs to.\n\n## Requests and responses\n\nSend and accept JSON: set `Accept: application/json` on every request and `Content-Type: application/json` when sending a body.\n\n## Errors\n\n- `401` the token is missing or invalid: `{\"message\": \"Unauthenticated.\"}`\n- `403` the token's role may not perform this action.\n- `404` the resource in the path does not exist.\n- `422` the request body failed validation; `errors` lists the messages per field."
  },
  "tags": [
    {
      "name": "Auth"
    },
    {
      "name": "Devices"
    },
    {
      "name": "Actions"
    },
    {
      "name": "Search"
    },
    {
      "name": "Customers"
    },
    {
      "name": "Locations"
    },
    {
      "name": "Consumers",
      "x-hidden": true
    },
    {
      "name": "Gateways",
      "x-hidden": true
    },
    {
      "name": "Device types",
      "x-hidden": true
    },
    {
      "name": "Capabilities",
      "x-hidden": true
    },
    {
      "name": "Roles",
      "x-hidden": true
    }
  ],
  "servers": [
    {
      "url": "https://api.example.com"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "Token from `POST /v1/auth/token`."
      }
    },
    "responses": {
      "Unauthenticated": {
        "description": "Unauthenticated",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "message": {
                  "type": "string"
                }
              }
            },
            "example": {
              "message": "Unauthenticated."
            }
          }
        }
      },
      "NotFound": {
        "description": "Not found"
      },
      "ValidationFailed": {
        "description": "Validation failed",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "message": {
                  "type": "string"
                },
                "errors": {
                  "type": "object",
                  "description": "Field name to a list of messages."
                }
              }
            }
          }
        }
      }
    }
  },
  "paths": {
    "/v1/actions/{action}": {
      "get": {
        "operationId": "get-v1-actions-action",
        "tags": [
          "Actions"
        ],
        "summary": "Run an action on a device or gateway",
        "description": "Runs an action on a device or gateway and returns a status object. Take the URL from the `actions` of the device or gateway.",
        "parameters": [
          {
            "name": "action",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/auth/consumer": {
      "get": {
        "operationId": "get-v1-auth-consumer",
        "tags": [
          "Auth"
        ],
        "summary": "Show the authenticated consumer",
        "description": "Returns the consumer that owns the bearer token. Responds with HTTP 201.",
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string"
                        }
                      }
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "ref_id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "created_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "updated_at": {
                          "type": "string",
                          "format": "date-time"
                        },
                        "company": {
                          "type": "string"
                        },
                        "email": {
                          "type": "string"
                        },
                        "description": {
                          "nullable": true
                        },
                        "email_verified_at": {
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "links": {
                    "self": "/v1/auth/consumer"
                  },
                  "data": {
                    "id": "c87addc5-9c3e-411e-81e6-3b8f1952ebed",
                    "ref_id": "01hq3rk8w00000000000000adm",
                    "name": "Lisa Smits",
                    "created_at": "2026-07-21T17:31:39.000000Z",
                    "updated_at": "2026-10-22T10:19:47.000000Z",
                    "company": "Polder Parks",
                    "email": "lisa.smits@example.com",
                    "description": null,
                    "email_verified_at": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/auth/token": {
      "post": {
        "operationId": "post-v1-auth-token",
        "tags": [
          "Auth"
        ],
        "summary": "Issue an access token",
        "description": "Exchanges email and password for a bearer token. Replaces any earlier token issued to the same consumer under the same device_name. Returns 201 with the token and the consumer, or 422 when the credentials are wrong. No token needed.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "email",
                  "password",
                  "device_name"
                ],
                "properties": {
                  "email": {
                    "type": "string",
                    "description": "Consumer email address.",
                    "x-rules": "required|email"
                  },
                  "password": {
                    "type": "string",
                    "description": "Consumer password.",
                    "x-rules": "required"
                  },
                  "device_name": {
                    "type": "string",
                    "description": "Name for the token, used to replace an earlier token of the same consumer and name.",
                    "x-rules": "required"
                  }
                }
              },
              "example": {
                "email": "lisa.smits@example.com",
                "password": "Tulip-Harbor-4821",
                "device_name": "booking-sync"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string"
                        }
                      }
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "token": {
                          "type": "string"
                        },
                        "user": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "ref_id": {
                              "type": "string"
                            },
                            "name": {
                              "type": "string"
                            },
                            "created_at": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "updated_at": {
                              "type": "string",
                              "format": "date-time"
                            },
                            "company": {
                              "type": "string"
                            },
                            "email": {
                              "type": "string"
                            },
                            "description": {
                              "nullable": true
                            },
                            "email_verified_at": {
                              "nullable": true
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "links": {
                    "self": "/v1/auth/token"
                  },
                  "data": {
                    "token": "1287|u8jzPde0IgxLd6GncfBAepfJBd0Kh8oOOL8dKLzd69838e04",
                    "user": {
                      "id": "c87addc5-9c3e-411e-81e6-3b8f1952ebed",
                      "ref_id": "01hq3rk8w00000000000000adm",
                      "name": "Lisa Smits",
                      "created_at": "2026-07-21T17:31:39.000000Z",
                      "updated_at": "2026-10-22T10:19:47.000000Z",
                      "company": "Polder Parks",
                      "email": "lisa.smits@example.com",
                      "description": null,
                      "email_verified_at": null
                    }
                  }
                }
              }
            }
          },
          "422": {
            "$ref": "#/components/responses/ValidationFailed"
          }
        },
        "security": []
      }
    },
    "/v1/capabilities": {
      "get": {
        "operationId": "get-v1-capabilities",
        "tags": [
          "Capabilities"
        ],
        "summary": "List capabilities",
        "description": "Deprecated. Use GET /v1/devices/{device}/capabilities.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string"
                        }
                      }
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "object",
                          "properties": {
                            "code": {
                              "type": "integer"
                            },
                            "message": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "links": {
                    "self": "/v1/capabilities"
                  },
                  "data": {
                    "success": {
                      "code": 200,
                      "message": "OK"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/capabilities/{capability}": {
      "get": {
        "operationId": "get-v1-capabilities-capability",
        "tags": [
          "Capabilities"
        ],
        "summary": "Show a capability",
        "description": "Deprecated.",
        "parameters": [
          {
            "name": "capability",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "1"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string"
                        }
                      }
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "object",
                          "properties": {
                            "code": {
                              "type": "integer"
                            },
                            "message": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "links": {
                    "self": "/v1/capabilities/1"
                  },
                  "data": {
                    "success": {
                      "code": 200,
                      "message": "OK"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/consumers": {
      "get": {
        "operationId": "get-v1-consumers",
        "tags": [
          "Consumers"
        ],
        "summary": "List consumers",
        "description": "Returns a page of consumers, sorted by name.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1 to 50. Values outside the range are clamped. Default 50.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, starting at 1.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "direction",
            "in": "query",
            "required": false,
            "description": "Sort direction, asc or desc. Default asc.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Search term, matched with LIKE against the searchable columns. No filtering when empty.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search_key",
            "in": "query",
            "required": false,
            "description": "Column to search: email, name, company or all. Default: name, email and company.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fuzzy",
            "in": "query",
            "required": false,
            "description": "Match mode for the term: start (term%), end (%term), fuzzy (characters in order, %t%e%s%t%). Any other value matches anywhere in the column (%term%). Default: match anywhere.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "ref_id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "email": {
                            "type": "string"
                          },
                          "company": {
                            "type": "string"
                          },
                          "role": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "current_page": {
                          "type": "integer"
                        },
                        "prev_page": {
                          "type": "boolean"
                        },
                        "next_page": {
                          "type": "integer"
                        },
                        "last_page": {
                          "type": "integer"
                        },
                        "from": {
                          "type": "integer"
                        },
                        "to": {
                          "type": "integer"
                        },
                        "per_page": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "first": {
                          "type": "string"
                        },
                        "last": {
                          "type": "string"
                        },
                        "next": {
                          "type": "string"
                        },
                        "prev": {
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "01jsxhfkskntbhpxgdw1jbfn8b",
                      "ref_id": "01jsxhfkskntbhpxgdw1jbfn8b",
                      "name": "Sophie Bakker",
                      "email": "sophie.bakker@example.com",
                      "company": "Northwind Stays",
                      "role": "user"
                    },
                    {
                      "id": "01f7v1h2q2a5ckqj35ryksy7wj",
                      "ref_id": "01f7v1h2q2a5ckqj35ryksy7wj",
                      "name": "Max de Haan",
                      "email": "max.de.haan@example.com",
                      "company": "Tulip Inn Collective",
                      "role": "user"
                    },
                    {
                      "id": "01k94prsjstgkhqxedvc08pb8y",
                      "ref_id": "01k94prsjstgkhqxedvc08pb8y",
                      "name": "Liam Jansen",
                      "email": "liam.jansen@example.com",
                      "company": "Meadow Lodges",
                      "role": "user"
                    }
                  ],
                  "meta": {
                    "current_page": 1,
                    "prev_page": false,
                    "next_page": 2,
                    "last_page": 2,
                    "from": 1,
                    "to": 50,
                    "per_page": 50,
                    "limit": 50,
                    "total": 55
                  },
                  "links": {
                    "first": "v1/consumers?page=1",
                    "last": "v1/consumers?page=2",
                    "next": "v1/consumers?page=2",
                    "prev": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      },
      "post": {
        "operationId": "post-v1-consumers",
        "tags": [
          "Consumers"
        ],
        "summary": "Create a consumer",
        "description": "Creates a consumer with its API token and returns it with HTTP 201.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "email",
                  "company",
                  "password",
                  "role"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Display name.",
                    "x-rules": "required"
                  },
                  "email": {
                    "type": "string",
                    "description": "Email address, used to sign in.",
                    "x-rules": "required|email"
                  },
                  "company": {
                    "type": "string",
                    "description": "Company name. Also used to name the generated token.",
                    "x-rules": "required"
                  },
                  "password": {
                    "type": "string",
                    "description": "Password. Stored hashed.",
                    "x-rules": "required|string"
                  },
                  "customer": {
                    "type": "string",
                    "description": "Customer to link the consumer to (uuid or ref_id of an existing customer). On the deployed line this returns 500 after the consumer is created, without linking it; leave it out and link with POST /v1/customers/{customer}/consumers.",
                    "x-rules": "nullable|uuid|new CustomerExists()"
                  },
                  "role": {
                    "type": "string",
                    "description": "The integer role number (0 admin, 1 user, 2 system), or the role ref_id (user 01e5mvnexg5hfnmsx6146r681b, admin 01e5mvnex76fxnp1fyrwpxkw83, system 01e5mvnewz1d27g9s4vrageah3); GET /v1/roles does not return ref_ids. Must not exceed the caller's role.",
                    "x-rules": "required|new RoleHasToBeEqualOrLessToOwnRole()"
                  },
                  "description": {
                    "type": "string",
                    "description": "Free text.",
                    "x-rules": "nullable|string"
                  }
                }
              },
              "example": {
                "name": "Emma de Vries",
                "email": "emma.de.vries.e8ca@example.com",
                "company": "Harborview Hotels",
                "password": "Tulip-Harbor-4821",
                "role": 1
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "ref_id": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "email": {
                      "type": "string"
                    },
                    "company": {
                      "type": "string"
                    },
                    "role": {
                      "type": "string"
                    },
                    "token": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "id": "01m5hxcp20jb8qc6jz1jf4g0hb",
                  "ref_id": "01m5hxcp20jb8qc6jz1jf4g0hb",
                  "name": "Emma de Vries",
                  "email": "emma.de.vries.e8ca@example.com",
                  "company": "Harborview Hotels",
                  "role": "user",
                  "token": "***"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "422": {
            "$ref": "#/components/responses/ValidationFailed"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/consumers/{consumer}": {
      "delete": {
        "operationId": "delete-v1-consumers-consumer",
        "tags": [
          "Consumers"
        ],
        "summary": "Delete a consumer",
        "description": "Deletes the consumer and all its tokens. {consumer} is the consumer ref_id. Returns 200.",
        "parameters": [
          {
            "name": "consumer",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "01m5hxcp20jb8qc6jz1jf4g0hb"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string"
                        }
                      }
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "object",
                          "properties": {
                            "code": {
                              "type": "integer"
                            },
                            "message": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "links": {
                    "self": "/v1/consumers/01m5hxcp20jb8qc6jz1jf4g0hb"
                  },
                  "data": {
                    "success": {
                      "code": 200,
                      "message": "OK"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      },
      "get": {
        "operationId": "get-v1-consumers-consumer",
        "tags": [
          "Consumers"
        ],
        "summary": "Show a consumer",
        "description": "Returns one consumer. {consumer} is the consumer ref_id.",
        "parameters": [
          {
            "name": "consumer",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "01jsxhfkskntbhpxgdw1jbfn8b"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string"
                        }
                      }
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "ref_id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "email": {
                          "type": "string"
                        },
                        "company": {
                          "type": "string"
                        },
                        "role": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "links": {
                    "self": "/v1/consumers/01jsxhfkskntbhpxgdw1jbfn8b"
                  },
                  "data": {
                    "id": "01jsxhfkskntbhpxgdw1jbfn8b",
                    "ref_id": "01jsxhfkskntbhpxgdw1jbfn8b",
                    "name": "Sophie Bakker",
                    "email": "sophie.bakker@example.com",
                    "company": "Northwind Stays",
                    "role": "user"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      },
      "put": {
        "operationId": "put-v1-consumers-consumer",
        "tags": [
          "Consumers"
        ],
        "summary": "Update a consumer",
        "description": "Updates the consumer. token=true generates a new API token and invalidates the consumer's earlier tokens. A given customer is added to the consumer's customers. {consumer} is the consumer ref_id.",
        "parameters": [
          {
            "name": "consumer",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "01m5hxcp20jb8qc6jz1jf4g0hb"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "email",
                  "company"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Display name.",
                    "x-rules": "required"
                  },
                  "email": {
                    "type": "string",
                    "description": "Email address.",
                    "x-rules": "required|email"
                  },
                  "company": {
                    "type": "string",
                    "description": "Company name. Also used to name a regenerated token.",
                    "x-rules": "required"
                  },
                  "description": {
                    "type": "string",
                    "description": "Free text.",
                    "x-rules": "nullable|string"
                  },
                  "password": {
                    "type": "string",
                    "description": "New password. Stored hashed. Left unchanged when omitted.",
                    "x-rules": "nullable"
                  },
                  "token": {
                    "type": "boolean",
                    "description": "true generates a new API token for the consumer. Integers are read as booleans (0 is false).",
                    "x-rules": "nullable|boolean"
                  },
                  "customer": {
                    "type": "string",
                    "description": "Customer to attach to the consumer (uuid or ref_id of an existing customer).",
                    "x-rules": "nullable|uuid|new CustomerExists()"
                  },
                  "role": {
                    "type": "string",
                    "description": "The integer role number (0 admin, 1 user, 2 system), or the role ref_id (user 01e5mvnexg5hfnmsx6146r681b, admin 01e5mvnex76fxnp1fyrwpxkw83, system 01e5mvnewz1d27g9s4vrageah3); GET /v1/roles does not return ref_ids. Must not exceed the caller's role.",
                    "x-rules": "sometimes|new RoleHasToBeEqualOrLessToOwnRole()"
                  }
                }
              },
              "example": {
                "name": "Emma de Vries",
                "email": "emma.de.vries.e8ca@example.com",
                "company": "Harborview Hotels",
                "description": "Front desk integration"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "ref_id": {
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "email": {
                      "type": "string"
                    },
                    "company": {
                      "type": "string"
                    },
                    "role": {
                      "type": "string"
                    }
                  }
                },
                "example": {
                  "id": "01m5hxcp20jb8qc6jz1jf4g0hb",
                  "ref_id": "01m5hxcp20jb8qc6jz1jf4g0hb",
                  "name": "Emma de Vries",
                  "email": "emma.de.vries.e8ca@example.com",
                  "company": "Harborview Hotels",
                  "role": "user"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationFailed"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/consumers/{consumer}/customers": {
      "get": {
        "operationId": "get-v1-consumers-consumer-customers",
        "tags": [
          "Consumers"
        ],
        "summary": "List customers of a consumer",
        "description": "Returns a page of the customers linked to the consumer. {consumer} is the consumer ref_id.",
        "parameters": [
          {
            "name": "consumer",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "01jsxhfkskntbhpxgdw1jbfn8b"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1 to 50. Values outside the range are clamped. Default 50.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, starting at 1.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "ref_id": {
                            "type": "string"
                          },
                          "reference": {
                            "type": "string"
                          },
                          "company": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "current_page": {
                          "type": "integer"
                        },
                        "prev_page": {
                          "type": "boolean"
                        },
                        "next_page": {
                          "type": "boolean"
                        },
                        "last_page": {
                          "type": "integer"
                        },
                        "from": {
                          "type": "integer"
                        },
                        "to": {
                          "type": "integer"
                        },
                        "per_page": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "first": {
                          "type": "string"
                        },
                        "last": {
                          "type": "string"
                        },
                        "next": {
                          "nullable": true
                        },
                        "prev": {
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "882afb3b-6fc8-4a68-8d58-7a5d1dcbb99b",
                      "ref_id": "01jra7mr80npj0j7rb1d9xf20z",
                      "reference": "654684",
                      "company": "Tulip Inn Collective"
                    }
                  ],
                  "meta": {
                    "current_page": 1,
                    "prev_page": false,
                    "next_page": false,
                    "last_page": 1,
                    "from": 1,
                    "to": 1,
                    "per_page": 50,
                    "limit": 50,
                    "total": 1
                  },
                  "links": {
                    "first": "v1/consumers/01jsxhfkskntbhpxgdw1jbfn8b/customers?page=1",
                    "last": "v1/consumers/01jsxhfkskntbhpxgdw1jbfn8b/customers?page=1",
                    "next": null,
                    "prev": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      },
      "post": {
        "operationId": "post-v1-consumers-consumer-customers",
        "tags": [
          "Consumers"
        ],
        "summary": "Toggle a customer on a consumer",
        "description": "Links the customer to the consumer, or unlinks it when already linked. {consumer} is the consumer ref_id.",
        "parameters": [
          {
            "name": "consumer",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "customer_id"
                ],
                "properties": {
                  "customer_id": {
                    "type": "string",
                    "description": "Customer to toggle (uuid or ref_id of an existing customer).",
                    "x-rules": "['required|uuid', new CustomerExists()]"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationFailed"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/consumers/{consumer}/locations": {
      "get": {
        "operationId": "get-v1-consumers-consumer-locations",
        "tags": [
          "Consumers"
        ],
        "summary": "List locations of a consumer",
        "description": "Returns a page of the locations the consumer can see. {consumer} is the consumer ref_id.",
        "parameters": [
          {
            "name": "consumer",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "01jsxhfkskntbhpxgdw1jbfn8b"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1 to 50. Values outside the range are clamped. Default 50.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, starting at 1.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "ref_id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "reference": {
                            "nullable": true
                          },
                          "customer": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "ref_id": {
                                "nullable": true
                              },
                              "company": {
                                "nullable": true
                              }
                            }
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "current_page": {
                          "type": "integer"
                        },
                        "prev_page": {
                          "type": "boolean"
                        },
                        "next_page": {
                          "type": "boolean"
                        },
                        "last_page": {
                          "type": "integer"
                        },
                        "from": {
                          "type": "integer"
                        },
                        "to": {
                          "type": "integer"
                        },
                        "per_page": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "first": {
                          "type": "string"
                        },
                        "last": {
                          "type": "string"
                        },
                        "next": {
                          "nullable": true
                        },
                        "prev": {
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "fed1e9ee-f42f-48aa-b198-14be37670bf4",
                      "ref_id": "01jra7nfbhc4jwkqsvye619cyf",
                      "name": "Grand Plaza Eindhoven",
                      "reference": null,
                      "customer": {
                        "id": "882afb3b-6fc8-4a68-8d58-7a5d1dcbb99b",
                        "ref_id": null,
                        "company": null
                      }
                    }
                  ],
                  "meta": {
                    "current_page": 1,
                    "prev_page": false,
                    "next_page": false,
                    "last_page": 1,
                    "from": 1,
                    "to": 1,
                    "per_page": 50,
                    "limit": 50,
                    "total": 1
                  },
                  "links": {
                    "first": "v1/consumers/01jsxhfkskntbhpxgdw1jbfn8b/locations?page=1",
                    "last": "v1/consumers/01jsxhfkskntbhpxgdw1jbfn8b/locations?page=1",
                    "next": null,
                    "prev": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/consumers/{consumer}/roles": {
      "post": {
        "operationId": "post-v1-consumers-consumer-roles",
        "tags": [
          "Consumers"
        ],
        "summary": "Set the role of a consumer",
        "description": "Sets the role of the consumer. {consumer} is the consumer ref_id. Returns 200, or 204 when the consumer is not found.",
        "parameters": [
          {
            "name": "consumer",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "role"
                ],
                "properties": {
                  "role": {
                    "type": "string",
                    "description": "The role ref_id (user 01e5mvnexg5hfnmsx6146r681b, admin 01e5mvnex76fxnp1fyrwpxkw83, system 01e5mvnewz1d27g9s4vrageah3); GET /v1/roles does not return ref_ids. Must not exceed the caller's role.",
                    "x-rules": "required|new RoleHasToBeEqualOrLessToOwnRole()"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationFailed"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/customers": {
      "get": {
        "operationId": "get-v1-customers",
        "tags": [
          "Customers"
        ],
        "summary": "List customers",
        "description": "Returns a page of customers, sorted by company.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1 to 50. Values outside the range are clamped. Default 50.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, starting at 1.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "direction",
            "in": "query",
            "required": false,
            "description": "Sort direction, asc or desc. Default asc.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Search term, matched with LIKE against the searchable columns. No filtering when empty.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search_key",
            "in": "query",
            "required": false,
            "description": "Column to search: company or all. Default: company.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fuzzy",
            "in": "query",
            "required": false,
            "description": "Match mode for the term: start (term%), end (%term), fuzzy (characters in order, %t%e%s%t%). Any other value matches anywhere in the column (%term%). Default: match anywhere.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "ref_id": {
                            "type": "string"
                          },
                          "reference": {
                            "type": "string"
                          },
                          "company": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "current_page": {
                          "type": "integer"
                        },
                        "prev_page": {
                          "type": "boolean"
                        },
                        "next_page": {
                          "type": "boolean"
                        },
                        "last_page": {
                          "type": "integer"
                        },
                        "from": {
                          "type": "integer"
                        },
                        "to": {
                          "type": "integer"
                        },
                        "per_page": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "first": {
                          "type": "string"
                        },
                        "last": {
                          "type": "string"
                        },
                        "next": {
                          "nullable": true
                        },
                        "prev": {
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c",
                      "ref_id": "01e31vwgfbfkcxfavhba7k682q",
                      "reference": "18996",
                      "company": "Seaside Resorts"
                    },
                    {
                      "id": "41f9b289-f3a0-4e8f-8f8a-b0bdf43e0e88",
                      "ref_id": "01k6d7sz6zzaj4e4hrdzjz7s85",
                      "reference": "0124",
                      "company": "Brightdoor Systems"
                    },
                    {
                      "id": "8422ab96-d903-49ef-a7da-103eec7bd256",
                      "ref_id": "01k94q5rzc3kqwmt5rh9secqck",
                      "reference": "12334",
                      "company": "Northwind Stays"
                    }
                  ],
                  "meta": {
                    "current_page": 1,
                    "prev_page": false,
                    "next_page": false,
                    "last_page": 1,
                    "from": 1,
                    "to": 22,
                    "per_page": 50,
                    "limit": 50,
                    "total": 22
                  },
                  "links": {
                    "first": "v1/customers?page=1",
                    "last": "v1/customers?page=1",
                    "next": null,
                    "prev": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      },
      "post": {
        "operationId": "post-v1-customers",
        "tags": [
          "Customers"
        ],
        "summary": "Create a customer",
        "description": "Creates a customer and returns it with HTTP 201. A realm is generated when none is given.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "company"
                ],
                "properties": {
                  "company": {
                    "type": "string",
                    "description": "Company name. Unique among customers.",
                    "x-rules": "required|unique:iot_customers"
                  },
                  "realm": {
                    "type": "string",
                    "description": "Realm. Unique among customers. A ULID is generated when omitted.",
                    "x-rules": "nullable|unique:iot_customers"
                  },
                  "reference": {
                    "type": "string",
                    "description": "Your own reference for the customer.",
                    "x-rules": "nullable"
                  }
                }
              },
              "example": {
                "company": "Harborview Hotels",
                "reference": "HV-e8ca"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "ref_id": {
                          "type": "string"
                        },
                        "reference": {
                          "type": "string"
                        },
                        "company": {
                          "type": "string"
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "aa7fb10d-d22f-44e0-bdbd-7935d0796d6d",
                    "ref_id": "01m5hxcn9yybzmkj9k614q1f1n",
                    "reference": "HV-e8ca",
                    "company": "Harborview Hotels"
                  },
                  "links": {
                    "self": "v1/customers"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "422": {
            "$ref": "#/components/responses/ValidationFailed"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/customers/{customer}": {
      "delete": {
        "operationId": "delete-v1-customers-customer",
        "tags": [
          "Customers"
        ],
        "summary": "Delete a customer",
        "description": "Deletes the customer together with its locations, their gateways and the devices of those gateways. {customer} is the customer id or ref_id. Returns 204.",
        "parameters": [
          {
            "name": "customer",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "aa7fb10d-d22f-44e0-bdbd-7935d0796d6d"
          }
        ],
        "responses": {
          "204": {
            "description": "No content"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      },
      "get": {
        "operationId": "get-v1-customers-customer",
        "tags": [
          "Customers"
        ],
        "summary": "Show a customer",
        "description": "Returns one customer. {customer} is the customer id or ref_id.",
        "parameters": [
          {
            "name": "customer",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "ref_id": {
                          "type": "string"
                        },
                        "reference": {
                          "type": "string"
                        },
                        "company": {
                          "type": "string"
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c",
                    "ref_id": "01e31vwgfbfkcxfavhba7k682q",
                    "reference": "18996",
                    "company": "Seaside Resorts"
                  },
                  "links": {
                    "self": "v1/customers/b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      },
      "put": {
        "operationId": "put-v1-customers-customer",
        "tags": [
          "Customers"
        ],
        "summary": "Update a customer",
        "description": "Updates the customer. {customer} is the customer id or ref_id.",
        "parameters": [
          {
            "name": "customer",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "aa7fb10d-d22f-44e0-bdbd-7935d0796d6d"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [],
                "properties": {
                  "company": {
                    "type": "string",
                    "description": "Company name. Unique among customers.",
                    "x-rules": "nullable|unique:iot_customers,company,<customer id>"
                  },
                  "realm": {
                    "type": "string",
                    "description": "Realm. Unique among customers.",
                    "x-rules": "nullable|unique:iot_customers,realm,<customer id>"
                  },
                  "reference": {
                    "type": "string",
                    "description": "Your own reference for the customer.",
                    "x-rules": "nullable"
                  }
                }
              },
              "example": {
                "company": "Harborview Hotels",
                "reference": "HV-e8ca-NL"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "ref_id": {
                          "type": "string"
                        },
                        "reference": {
                          "type": "string"
                        },
                        "company": {
                          "type": "string"
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "aa7fb10d-d22f-44e0-bdbd-7935d0796d6d",
                    "ref_id": "01m5hxcn9yybzmkj9k614q1f1n",
                    "reference": "HV-e8ca-NL",
                    "company": "Harborview Hotels"
                  },
                  "links": {
                    "self": "v1/customers/aa7fb10d-d22f-44e0-bdbd-7935d0796d6d"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationFailed"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/customers/{customer}/consumers": {
      "get": {
        "operationId": "get-v1-customers-customer-consumers",
        "tags": [
          "Customers"
        ],
        "summary": "List consumers of a customer",
        "description": "Returns a page of the consumers linked to the customer. {customer} is the customer id or ref_id.",
        "parameters": [
          {
            "name": "customer",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1 to 50. Values outside the range are clamped. Default 50.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, starting at 1.",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "ref_id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "email": {
                            "type": "string"
                          },
                          "company": {
                            "type": "string"
                          },
                          "role": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "current_page": {
                          "type": "integer"
                        },
                        "prev_page": {
                          "type": "boolean"
                        },
                        "next_page": {
                          "type": "boolean"
                        },
                        "last_page": {
                          "type": "integer"
                        },
                        "from": {
                          "type": "integer"
                        },
                        "to": {
                          "type": "integer"
                        },
                        "per_page": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "first": {
                          "type": "string"
                        },
                        "last": {
                          "type": "string"
                        },
                        "next": {
                          "nullable": true
                        },
                        "prev": {
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "01f7v1h2q2a5ckqj35ryksy7wj",
                      "ref_id": "01f7v1h2q2a5ckqj35ryksy7wj",
                      "name": "Max de Haan",
                      "email": "max.de.haan@example.com",
                      "company": "Tulip Inn Collective",
                      "role": "user"
                    }
                  ],
                  "meta": {
                    "current_page": 1,
                    "prev_page": false,
                    "next_page": false,
                    "last_page": 1,
                    "from": 1,
                    "to": 1,
                    "per_page": 50,
                    "limit": 50,
                    "total": 1
                  },
                  "links": {
                    "first": "v1/customers/b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c/consumers?page=1",
                    "last": "v1/customers/b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c/consumers?page=1",
                    "next": null,
                    "prev": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      },
      "post": {
        "operationId": "post-v1-customers-customer-consumers",
        "tags": [
          "Customers"
        ],
        "summary": "Toggle a consumer on a customer",
        "description": "Links the consumer to the customer, or unlinks it when already linked. {customer} is the customer id or ref_id.",
        "parameters": [
          {
            "name": "customer",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "aa7fb10d-d22f-44e0-bdbd-7935d0796d6d"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "consumer_id"
                ],
                "properties": {
                  "consumer_id": {
                    "type": "string",
                    "description": "ref_id of an existing consumer. The handler looks the consumer up by ref_id only.",
                    "x-rules": "required|new ConsumerExists()"
                  }
                }
              },
              "example": {
                "consumer_id": "01m5hxcp20jb8qc6jz1jf4g0hb"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string"
                        }
                      }
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "object",
                          "properties": {
                            "code": {
                              "type": "integer"
                            },
                            "message": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "links": {
                    "self": "/v1/customers/aa7fb10d-d22f-44e0-bdbd-7935d0796d6d/consumers"
                  },
                  "data": {
                    "success": {
                      "code": 200,
                      "message": "OK"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationFailed"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/customers/{customer}/devices": {
      "get": {
        "operationId": "get-v1-customers-customer-devices",
        "tags": [
          "Customers"
        ],
        "summary": "List devices of a customer",
        "description": "Returns a page of the customer's devices, sorted by label. {customer} is the customer id or ref_id.",
        "parameters": [
          {
            "name": "customer",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1 to 50. Values outside the range are clamped. Default 50.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, starting at 1.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Search term, matched with LIKE against the searchable columns. No filtering when empty.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search_key",
            "in": "query",
            "required": false,
            "description": "Column to search: label, mac_address or all. Default: label and mac_address.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fuzzy",
            "in": "query",
            "required": false,
            "description": "Match mode for the term: start (term%), end (%term), fuzzy (characters in order, %t%e%s%t%). Any other value matches anywhere in the column (%term%). Default: match anywhere.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "1 returns only rows reported online by the Zabbix webhook, 0 returns the rest. A row without a status record counts as not online. No filtering when absent.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "ref_id": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          },
                          "mac_address": {
                            "type": "string"
                          },
                          "customer": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "company": {
                                "type": "string"
                              }
                            }
                          },
                          "location": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              }
                            }
                          },
                          "gateway": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "label": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "mac_address": {
                                "type": "string"
                              }
                            }
                          },
                          "device_type": {
                            "type": "string"
                          },
                          "state": {
                            "type": "object",
                            "properties": {
                              "active": {
                                "type": "boolean"
                              },
                              "last_reported": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                              }
                            }
                          },
                          "sensors": {
                            "type": "object",
                            "properties": {
                              "bat": {
                                "type": "number"
                              },
                              "rssi": {
                                "type": "integer"
                              },
                              "temp": {
                                "type": "integer"
                              }
                            }
                          },
                          "status": {
                            "type": "object",
                            "properties": {
                              "online": {
                                "type": "boolean"
                              },
                              "active": {
                                "type": "boolean"
                              },
                              "battery": {
                                "type": "number"
                              },
                              "rssi": {
                                "type": "integer"
                              },
                              "temperature": {
                                "type": "integer"
                              },
                              "action": {
                                "type": "string"
                              },
                              "updated_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                              }
                            }
                          },
                          "capabilities": {
                            "type": "object",
                            "properties": {
                              "open": {
                                "type": "string"
                              },
                              "close": {
                                "type": "string"
                              },
                              "toggle": {
                                "type": "string"
                              },
                              "led": {
                                "type": "string"
                              }
                            }
                          },
                          "actions": {
                            "type": "object",
                            "properties": {
                              "open": {
                                "type": "string"
                              },
                              "close": {
                                "type": "string"
                              },
                              "toggle": {
                                "type": "string"
                              },
                              "led": {
                                "type": "string"
                              }
                            }
                          },
                          "topic": {
                            "type": "string"
                          },
                          "custom": {
                            "nullable": true
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "current_page": {
                          "type": "integer"
                        },
                        "prev_page": {
                          "type": "boolean"
                        },
                        "next_page": {
                          "type": "integer"
                        },
                        "last_page": {
                          "type": "integer"
                        },
                        "from": {
                          "type": "integer"
                        },
                        "to": {
                          "type": "integer"
                        },
                        "per_page": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "first": {
                          "type": "string"
                        },
                        "last": {
                          "type": "string"
                        },
                        "next": {
                          "type": "string"
                        },
                        "prev": {
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "9fc3dab9-6d57-4b71-9038-28f3d0d73e02",
                      "ref_id": "01e3703zycjk9fmre5s45sc1yp",
                      "label": "Room 101",
                      "mac_address": "0x124b002422e23a",
                      "customer": {
                        "id": "b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c",
                        "ref_id": "01e31vwgfbfkcxfavhba7k682q",
                        "company": "Seaside Resorts"
                      },
                      "location": {
                        "id": "cf098ef1-bc66-4679-9da9-336ab5d1c561",
                        "ref_id": "01fkk63yt82hbs5h0gxjrexs43",
                        "name": "Grand Plaza Eindhoven"
                      },
                      "gateway": {
                        "id": "91cd4cf8-561b-4647-bae5-143167b586e7",
                        "label": "Room 312",
                        "ref_id": "01e36zxjget8jkmggpzemhdbw0",
                        "mac_address": "0x124b000d27b431"
                      },
                      "device_type": "lock",
                      "state": {
                        "active": true,
                        "last_reported": "2024-11-28 13:55:14"
                      },
                      "sensors": {
                        "bat": 5.5,
                        "rssi": -45,
                        "temp": 29
                      },
                      "status": {
                        "online": true,
                        "active": true,
                        "battery": 5.5,
                        "rssi": -45,
                        "temperature": 29,
                        "action": "close",
                        "updated_at": "2024-11-28 13:55:14"
                      },
                      "capabilities": {
                        "open": "c70a5a66-7a78-49cf-9dae-2881badc5cc8",
                        "close": "7733462c-a76e-4a38-9b37-6a7cb29a966e",
                        "toggle": "ac06b722-4683-4482-b642-c3f70c0bf162",
                        "led": "28e9d909-2ced-47ee-ae21-b71c9d8d6367"
                      },
                      "actions": {
                        "open": "/v1/actions/dv-01e3703zycjk9fmre5s45sc1yp-open-lock",
                        "close": "/v1/actions/dv-01e3703zycjk9fmre5s45sc1yp-close-lock",
                        "toggle": "/v1/actions/dv-01e3703zycjk9fmre5s45sc1yp-toggle-lock",
                        "led": "/v1/actions/dv-01e3703zycjk9fmre5s45sc1yp-toggle-led"
                      },
                      "topic": "0x124b000d27b431_0x124b002422e23a",
                      "custom": null
                    },
                    {
                      "id": "14f00a2e-74a0-455e-a58b-dc08d67c0b72",
                      "ref_id": "01ga6j1yp7rrs65ycsnr1ekaph",
                      "label": "Annex gateway",
                      "mac_address": "0x124b0024d7224e",
                      "customer": {
                        "id": "b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c",
                        "ref_id": "01e31vwgfbfkcxfavhba7k682q",
                        "company": "Seaside Resorts"
                      },
                      "location": {
                        "id": "cf098ef1-bc66-4679-9da9-336ab5d1c561",
                        "ref_id": "01fkk63yt82hbs5h0gxjrexs43",
                        "name": "Grand Plaza Eindhoven"
                      },
                      "gateway": {
                        "id": "91cd4cf8-561b-4647-bae5-143167b586e7",
                        "label": "Room 312",
                        "ref_id": "01e36zxjget8jkmggpzemhdbw0",
                        "mac_address": "0x124b000d27b431"
                      },
                      "device_type": "lock",
                      "state": {
                        "active": true,
                        "last_reported": "2024-11-28 13:54:55"
                      },
                      "sensors": {
                        "bat": 5.3,
                        "rssi": -59,
                        "temp": 22
                      },
                      "status": {
                        "online": true,
                        "active": true,
                        "battery": 5.3,
                        "rssi": -59,
                        "temperature": 22,
                        "action": "close",
                        "updated_at": "2024-11-28 13:54:55"
                      },
                      "capabilities": {
                        "open": "c70a5a66-7a78-49cf-9dae-2881badc5cc8",
                        "close": "7733462c-a76e-4a38-9b37-6a7cb29a966e",
                        "toggle": "ac06b722-4683-4482-b642-c3f70c0bf162",
                        "led": "28e9d909-2ced-47ee-ae21-b71c9d8d6367"
                      },
                      "actions": {
                        "open": "/v1/actions/dv-01ga6j1yp7rrs65ycsnr1ekaph-open-lock",
                        "close": "/v1/actions/dv-01ga6j1yp7rrs65ycsnr1ekaph-close-lock",
                        "toggle": "/v1/actions/dv-01ga6j1yp7rrs65ycsnr1ekaph-toggle-lock",
                        "led": "/v1/actions/dv-01ga6j1yp7rrs65ycsnr1ekaph-toggle-led"
                      },
                      "topic": "0x124b000d27b431_0x124b0024d7224e",
                      "custom": null
                    },
                    {
                      "id": "2c2821e1-0e05-3f00-84a5-92763e46494e",
                      "ref_id": "gj4xtsejf6mk9ycvwrspfkdz79",
                      "label": "Floor 2 gateway",
                      "mac_address": "0x124b00119dae46",
                      "customer": {
                        "id": "b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c",
                        "ref_id": "01e31vwgfbfkcxfavhba7k682q",
                        "company": "Seaside Resorts"
                      },
                      "location": {
                        "id": "cf098ef1-bc66-4679-9da9-336ab5d1c561",
                        "ref_id": "01fkk63yt82hbs5h0gxjrexs43",
                        "name": "Grand Plaza Eindhoven"
                      },
                      "gateway": {
                        "id": "91cd4cf8-561b-4647-bae5-143167b586e7",
                        "label": "Room 312",
                        "ref_id": "01e36zxjget8jkmggpzemhdbw0",
                        "mac_address": "0x124b000d27b431"
                      },
                      "device_type": "lock",
                      "state": {
                        "active": true,
                        "last_reported": null
                      },
                      "sensors": {
                        "bat": 0,
                        "rssi": 0,
                        "temp": 0
                      },
                      "status": {
                        "online": false,
                        "active": true,
                        "battery": 0,
                        "rssi": 0,
                        "temperature": 0,
                        "action": "",
                        "updated_at": null
                      },
                      "capabilities": {
                        "open": "c70a5a66-7a78-49cf-9dae-2881badc5cc8",
                        "close": "7733462c-a76e-4a38-9b37-6a7cb29a966e",
                        "toggle": "ac06b722-4683-4482-b642-c3f70c0bf162",
                        "led": "28e9d909-2ced-47ee-ae21-b71c9d8d6367"
                      },
                      "actions": {
                        "open": "/v1/actions/dv-gj4xtsejf6mk9ycvwrspfkdz79-open-lock",
                        "close": "/v1/actions/dv-gj4xtsejf6mk9ycvwrspfkdz79-close-lock",
                        "toggle": "/v1/actions/dv-gj4xtsejf6mk9ycvwrspfkdz79-toggle-lock",
                        "led": "/v1/actions/dv-gj4xtsejf6mk9ycvwrspfkdz79-toggle-led"
                      },
                      "topic": "0x124b000d27b431_0x124b00119dae46",
                      "custom": null
                    }
                  ],
                  "meta": {
                    "current_page": 1,
                    "prev_page": false,
                    "next_page": 2,
                    "last_page": 2,
                    "from": 1,
                    "to": 50,
                    "per_page": 50,
                    "limit": 50,
                    "total": 85
                  },
                  "links": {
                    "first": "v1/customers/b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c/devices?page=1",
                    "last": "v1/customers/b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c/devices?page=2",
                    "next": "v1/customers/b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c/devices?page=2",
                    "prev": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      },
      "post": {
        "operationId": "post-v1-customers-customer-devices",
        "tags": [
          "Customers"
        ],
        "summary": "Toggle a device on a customer",
        "description": "Sets the customer as owner of the device, or clears the owner when this customer already owns it. Returns 200, or 204 when the device is not found. {customer} is the customer id or ref_id. Currently returns 500; send customer_id when creating the device instead.",
        "parameters": [
          {
            "name": "customer",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "device"
                ],
                "properties": {
                  "device": {
                    "type": "string",
                    "description": "Device to toggle (uuid or ref_id of an existing device).",
                    "x-rules": "required|new DeviceExists()"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationFailed"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/customers/{customer}/gateways": {
      "get": {
        "operationId": "get-v1-customers-customer-gateways",
        "tags": [
          "Customers"
        ],
        "summary": "List gateways of a customer",
        "description": "Returns a page of the customer's gateways, sorted by label. {customer} is the customer id or ref_id.",
        "parameters": [
          {
            "name": "customer",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1 to 50. Values outside the range are clamped. Default 50.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, starting at 1.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Search term, matched with LIKE against the searchable columns. No filtering when empty.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search_key",
            "in": "query",
            "required": false,
            "description": "Column to search: label, mac_address or all. Default: label and mac_address.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fuzzy",
            "in": "query",
            "required": false,
            "description": "Match mode for the term: start (term%), end (%term), fuzzy (characters in order, %t%e%s%t%). Any other value matches anywhere in the column (%term%). Default: match anywhere.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "1 returns only rows reported online by the Zabbix webhook, 0 returns the rest. A row without a status record counts as not online. No filtering when absent.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "ref_id": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          },
                          "state": {
                            "type": "array",
                            "items": {}
                          },
                          "mac_address": {
                            "type": "string"
                          },
                          "customer": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "company": {
                                "type": "string"
                              }
                            }
                          },
                          "location": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              }
                            }
                          },
                          "device_type": {
                            "type": "string"
                          },
                          "actions": {
                            "type": "object",
                            "properties": {
                              "open": {
                                "type": "string"
                              },
                              "close": {
                                "type": "string"
                              }
                            }
                          },
                          "topic": {
                            "type": "string"
                          },
                          "status": {
                            "type": "object",
                            "properties": {
                              "online": {
                                "type": "boolean"
                              },
                              "battery": {
                                "type": "integer"
                              },
                              "rssi": {
                                "type": "integer"
                              },
                              "temperature": {
                                "type": "integer"
                              },
                              "action": {
                                "type": "string"
                              },
                              "updated_at": {
                                "type": "string",
                                "format": "date-time"
                              }
                            }
                          },
                          "monitoring": {
                            "type": "array",
                            "items": {}
                          },
                          "custom": {
                            "nullable": true
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "current_page": {
                          "type": "integer"
                        },
                        "prev_page": {
                          "type": "boolean"
                        },
                        "next_page": {
                          "type": "boolean"
                        },
                        "last_page": {
                          "type": "integer"
                        },
                        "from": {
                          "type": "integer"
                        },
                        "to": {
                          "type": "integer"
                        },
                        "per_page": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "first": {
                          "type": "string"
                        },
                        "last": {
                          "type": "string"
                        },
                        "next": {
                          "nullable": true
                        },
                        "prev": {
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "91cd4cf8-561b-4647-bae5-143167b586e7",
                      "ref_id": "01e36zxjget8jkmggpzemhdbw0",
                      "label": "Room 312",
                      "state": [],
                      "mac_address": "0x124b000d27b431",
                      "customer": {
                        "id": "b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c",
                        "ref_id": "01e31vwgfbfkcxfavhba7k682q",
                        "company": "Seaside Resorts"
                      },
                      "location": {
                        "id": "cf098ef1-bc66-4679-9da9-336ab5d1c561",
                        "ref_id": "01fkk63yt82hbs5h0gxjrexs43",
                        "name": "Grand Plaza Eindhoven"
                      },
                      "device_type": "gateway",
                      "actions": {
                        "open": "/v1/actions/gw-01e36zxjget8jkmggpzemhdbw0-open-gateway",
                        "close": "/v1/actions/gw-01e36zxjget8jkmggpzemhdbw0-close-gateway"
                      },
                      "topic": "0x124b000d27b431_network",
                      "status": {
                        "online": true,
                        "battery": 0,
                        "rssi": 0,
                        "temperature": 0,
                        "action": "close",
                        "updated_at": "2026-03-13 13:22:20"
                      },
                      "monitoring": [],
                      "custom": null
                    }
                  ],
                  "meta": {
                    "current_page": 1,
                    "prev_page": false,
                    "next_page": false,
                    "last_page": 1,
                    "from": 1,
                    "to": 1,
                    "per_page": 50,
                    "limit": 50,
                    "total": 1
                  },
                  "links": {
                    "first": "v1/customers/b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c/gateways?page=1",
                    "last": "v1/customers/b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c/gateways?page=1",
                    "next": null,
                    "prev": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      },
      "post": {
        "operationId": "post-v1-customers-customer-gateways",
        "tags": [
          "Customers"
        ],
        "summary": "Toggle a gateway on a customer",
        "description": "Sets the customer as owner of the gateway, or clears the owner when this customer already owns it. Returns 404 when the gateway is not found. {customer} is the customer id or ref_id. Currently returns 500; set the owner through the gateway's location instead.",
        "parameters": [
          {
            "name": "customer",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "gateway"
                ],
                "properties": {
                  "gateway": {
                    "type": "string",
                    "description": "Gateway to toggle (uuid or ref_id of an existing gateway).",
                    "x-rules": "required|new GatewayExists()"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationFailed"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/customers/{customer}/locations": {
      "get": {
        "operationId": "get-v1-customers-customer-locations",
        "tags": [
          "Customers"
        ],
        "summary": "List locations of a customer",
        "description": "Returns a page of the customer's locations, sorted by name. {customer} is the customer id or ref_id.",
        "parameters": [
          {
            "name": "customer",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1 to 50. Values outside the range are clamped. Default 50.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, starting at 1.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Search term, matched with LIKE against the searchable columns. No filtering when empty.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search_key",
            "in": "query",
            "required": false,
            "description": "Column to search: name or all. Default: name.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fuzzy",
            "in": "query",
            "required": false,
            "description": "Match mode for the term: start (term%), end (%term), fuzzy (characters in order, %t%e%s%t%). Any other value matches anywhere in the column (%term%). Default: match anywhere.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "ref_id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "reference": {
                            "type": "string"
                          },
                          "customer": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "company": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "current_page": {
                          "type": "integer"
                        },
                        "prev_page": {
                          "type": "boolean"
                        },
                        "next_page": {
                          "type": "boolean"
                        },
                        "last_page": {
                          "type": "integer"
                        },
                        "from": {
                          "type": "integer"
                        },
                        "to": {
                          "type": "integer"
                        },
                        "per_page": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "first": {
                          "type": "string"
                        },
                        "last": {
                          "type": "string"
                        },
                        "next": {
                          "nullable": true
                        },
                        "prev": {
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "cf098ef1-bc66-4679-9da9-336ab5d1c561",
                      "ref_id": "01fkk63yt82hbs5h0gxjrexs43",
                      "name": "Grand Plaza Eindhoven",
                      "reference": "c2odemo89",
                      "customer": {
                        "id": "b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c",
                        "ref_id": "01e31vwgfbfkcxfavhba7k682q",
                        "company": "Seaside Resorts"
                      }
                    }
                  ],
                  "meta": {
                    "current_page": 1,
                    "prev_page": false,
                    "next_page": false,
                    "last_page": 1,
                    "from": 1,
                    "to": 1,
                    "per_page": 50,
                    "limit": 50,
                    "total": 1
                  },
                  "links": {
                    "first": "v1/customers/b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c/locations?page=1",
                    "last": "v1/customers/b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c/locations?page=1",
                    "next": null,
                    "prev": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/devices": {
      "get": {
        "operationId": "get-v1-devices",
        "tags": [
          "Devices"
        ],
        "summary": "List devices",
        "description": "Returns a page of devices, sorted by label.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1 to 50. Values outside the range are clamped. Default 50.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, starting at 1.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "direction",
            "in": "query",
            "required": false,
            "description": "Sort direction, asc or desc. Default asc.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Search term, matched with LIKE against the searchable columns. No filtering when empty.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search_key",
            "in": "query",
            "required": false,
            "description": "Column to search: label, mac_address or all. Default: label and mac_address.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fuzzy",
            "in": "query",
            "required": false,
            "description": "Match mode for the term: start (term%), end (%term), fuzzy (characters in order, %t%e%s%t%). Any other value matches anywhere in the column (%term%). Default: match anywhere.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "1 returns only rows reported online by the Zabbix webhook, 0 returns the rest. A row without a status record counts as not online. No filtering when absent.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "ref_id": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          },
                          "mac_address": {
                            "type": "string"
                          },
                          "customer": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "company": {
                                "type": "string"
                              }
                            }
                          },
                          "location": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              }
                            }
                          },
                          "gateway": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "label": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "mac_address": {
                                "type": "string"
                              }
                            }
                          },
                          "device_type": {
                            "type": "string"
                          },
                          "state": {
                            "type": "object",
                            "properties": {
                              "active": {
                                "type": "boolean"
                              },
                              "last_reported": {
                                "type": "string",
                                "format": "date-time"
                              }
                            }
                          },
                          "sensors": {
                            "type": "object",
                            "properties": {
                              "bat": {
                                "type": "integer"
                              },
                              "rssi": {
                                "type": "integer"
                              },
                              "temp": {
                                "type": "integer"
                              }
                            }
                          },
                          "status": {
                            "type": "object",
                            "properties": {
                              "online": {
                                "type": "boolean"
                              },
                              "active": {
                                "type": "boolean"
                              },
                              "battery": {
                                "type": "integer"
                              },
                              "rssi": {
                                "type": "integer"
                              },
                              "temperature": {
                                "type": "integer"
                              },
                              "action": {
                                "type": "string"
                              },
                              "updated_at": {
                                "type": "string",
                                "format": "date-time"
                              }
                            }
                          },
                          "capabilities": {
                            "type": "object",
                            "properties": {
                              "open": {
                                "type": "string"
                              },
                              "close": {
                                "type": "string"
                              },
                              "toggle": {
                                "type": "string"
                              },
                              "led": {
                                "type": "string"
                              }
                            }
                          },
                          "actions": {
                            "type": "object",
                            "properties": {
                              "open": {
                                "type": "string"
                              },
                              "close": {
                                "type": "string"
                              },
                              "toggle": {
                                "type": "string"
                              },
                              "led": {
                                "type": "string"
                              }
                            }
                          },
                          "topic": {
                            "type": "string"
                          },
                          "custom": {
                            "nullable": true
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "current_page": {
                          "type": "integer"
                        },
                        "prev_page": {
                          "type": "boolean"
                        },
                        "next_page": {
                          "type": "integer"
                        },
                        "last_page": {
                          "type": "integer"
                        },
                        "from": {
                          "type": "integer"
                        },
                        "to": {
                          "type": "integer"
                        },
                        "per_page": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "first": {
                          "type": "string"
                        },
                        "last": {
                          "type": "string"
                        },
                        "next": {
                          "type": "string"
                        },
                        "prev": {
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "65fcb74b-92d9-40c6-8732-b30b9afa2488",
                      "ref_id": "01hzpjvzgjxm2qkwd9bw7dhc5h",
                      "label": "Staff entrance",
                      "mac_address": "asrfadf4",
                      "customer": {
                        "id": "eb88e4e7-c451-4112-9bb1-2124a0f5b48e",
                        "ref_id": "01hyfvr34329jb8gw1rft7sea7",
                        "company": "Keyless Labs"
                      },
                      "location": {
                        "id": "79fad71c-c6a8-41c0-b1cd-b579b11371df",
                        "ref_id": "01hyfvrp008ept70kak8ss9r5z",
                        "name": "Riverside Maastricht"
                      },
                      "gateway": {
                        "id": "83b30351-a4e0-46f0-af8b-0b054aecb7f5",
                        "label": "Lobby entrance",
                        "ref_id": "01hyfvsdpe1srnrtqdnbt45rm3",
                        "mac_address": "0x0123456789"
                      },
                      "device_type": "lock",
                      "state": {
                        "active": true,
                        "last_reported": "2024-06-06 10:38:48"
                      },
                      "sensors": {
                        "bat": 0,
                        "rssi": 0,
                        "temp": 0
                      },
                      "status": {
                        "online": true,
                        "active": true,
                        "battery": 0,
                        "rssi": 0,
                        "temperature": 0,
                        "action": "close",
                        "updated_at": "2024-06-06 10:38:48"
                      },
                      "capabilities": {
                        "open": "c70a5a66-7a78-49cf-9dae-2881badc5cc8",
                        "close": "7733462c-a76e-4a38-9b37-6a7cb29a966e",
                        "toggle": "ac06b722-4683-4482-b642-c3f70c0bf162",
                        "led": "28e9d909-2ced-47ee-ae21-b71c9d8d6367"
                      },
                      "actions": {
                        "open": "/v1/actions/dv-01hzpjvzgjxm2qkwd9bw7dhc5h-open-lock",
                        "close": "/v1/actions/dv-01hzpjvzgjxm2qkwd9bw7dhc5h-close-lock",
                        "toggle": "/v1/actions/dv-01hzpjvzgjxm2qkwd9bw7dhc5h-toggle-lock",
                        "led": "/v1/actions/dv-01hzpjvzgjxm2qkwd9bw7dhc5h-toggle-led"
                      },
                      "topic": "0x0123456789_asrfadf4",
                      "custom": null
                    },
                    {
                      "id": "aca19e7d-1ba4-4405-ab9f-065690a06ae3",
                      "ref_id": "01hzpk0fc10wbc6jdxh61q880t",
                      "label": "Bungalow 12",
                      "mac_address": "4565df4s6d54fs6d5f4",
                      "customer": {
                        "id": "eb88e4e7-c451-4112-9bb1-2124a0f5b48e",
                        "ref_id": "01hyfvr34329jb8gw1rft7sea7",
                        "company": "Keyless Labs"
                      },
                      "location": {
                        "id": "79fad71c-c6a8-41c0-b1cd-b579b11371df",
                        "ref_id": "01hyfvrp008ept70kak8ss9r5z",
                        "name": "Riverside Maastricht"
                      },
                      "gateway": {
                        "id": "83b30351-a4e0-46f0-af8b-0b054aecb7f5",
                        "label": "Lobby entrance",
                        "ref_id": "01hyfvsdpe1srnrtqdnbt45rm3",
                        "mac_address": "0x0123456789"
                      },
                      "device_type": "lock",
                      "state": {
                        "active": true,
                        "last_reported": "2024-06-06 10:40:53"
                      },
                      "sensors": {
                        "bat": 0,
                        "rssi": 0,
                        "temp": 0
                      },
                      "status": {
                        "online": true,
                        "active": true,
                        "battery": 0,
                        "rssi": 0,
                        "temperature": 0,
                        "action": "close",
                        "updated_at": "2024-06-06 10:40:53"
                      },
                      "capabilities": {
                        "open": "c70a5a66-7a78-49cf-9dae-2881badc5cc8",
                        "close": "7733462c-a76e-4a38-9b37-6a7cb29a966e",
                        "toggle": "ac06b722-4683-4482-b642-c3f70c0bf162",
                        "led": "28e9d909-2ced-47ee-ae21-b71c9d8d6367"
                      },
                      "actions": {
                        "open": "/v1/actions/dv-01hzpk0fc10wbc6jdxh61q880t-open-lock",
                        "close": "/v1/actions/dv-01hzpk0fc10wbc6jdxh61q880t-close-lock",
                        "toggle": "/v1/actions/dv-01hzpk0fc10wbc6jdxh61q880t-toggle-lock",
                        "led": "/v1/actions/dv-01hzpk0fc10wbc6jdxh61q880t-toggle-led"
                      },
                      "topic": "0x0123456789_4565df4s6d54fs6d5f4",
                      "custom": null
                    },
                    {
                      "id": "2217a217-dd84-400d-9f4a-90ff02fc5ff3",
                      "ref_id": "01k6d7v7p1r2v1rg0ygteky06p",
                      "label": "Suite 401",
                      "mac_address": "0x12499920",
                      "customer": {
                        "id": "41f9b289-f3a0-4e8f-8f8a-b0bdf43e0e88",
                        "ref_id": "01k6d7sz6zzaj4e4hrdzjz7s85",
                        "company": "Brightdoor Systems"
                      },
                      "location": {
                        "id": "ffc8aa72-a7c9-4347-9908-5bb9de1a6f8d",
                        "ref_id": "01k6d7tn2dhvszt89hjme18pn8",
                        "name": "Riverside Maastricht"
                      },
                      "gateway": {
                        "id": "78ebf3df-a5f4-43da-ab2e-aa3f5f3f072a",
                        "label": "Bungalow 14",
                        "ref_id": "01k6d7twqsbyx2w2x21r3pfhqt",
                        "mac_address": "0s124d"
                      },
                      "device_type": "lock",
                      "state": {
                        "active": true,
                        "last_reported": "2025-09-30 11:45:29"
                      },
                      "sensors": {
                        "bat": 0,
                        "rssi": 0,
                        "temp": 0
                      },
                      "status": {
                        "online": false,
                        "active": true,
                        "battery": 0,
                        "rssi": 0,
                        "temperature": 0,
                        "action": "close",
                        "updated_at": "2025-09-30 11:45:29"
                      },
                      "capabilities": {
                        "open": "c70a5a66-7a78-49cf-9dae-2881badc5cc8",
                        "close": "7733462c-a76e-4a38-9b37-6a7cb29a966e",
                        "toggle": "ac06b722-4683-4482-b642-c3f70c0bf162",
                        "led": "28e9d909-2ced-47ee-ae21-b71c9d8d6367"
                      },
                      "actions": {
                        "open": "/v1/actions/dv-01k6d7v7p1r2v1rg0ygteky06p-open-lock",
                        "close": "/v1/actions/dv-01k6d7v7p1r2v1rg0ygteky06p-close-lock",
                        "toggle": "/v1/actions/dv-01k6d7v7p1r2v1rg0ygteky06p-toggle-lock",
                        "led": "/v1/actions/dv-01k6d7v7p1r2v1rg0ygteky06p-toggle-led"
                      },
                      "topic": "0s124d_0x12499920",
                      "custom": null
                    }
                  ],
                  "meta": {
                    "current_page": 1,
                    "prev_page": false,
                    "next_page": 2,
                    "last_page": 43,
                    "from": 1,
                    "to": 50,
                    "per_page": 50,
                    "limit": 50,
                    "total": 2117
                  },
                  "links": {
                    "first": "v1/devices?page=1",
                    "last": "v1/devices?page=43",
                    "next": "v1/devices?page=2",
                    "prev": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      },
      "post": {
        "operationId": "post-v1-devices",
        "tags": [
          "Devices"
        ],
        "summary": "Create a device",
        "description": "Creates the device. Customer and location are taken from the gateway.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "label",
                  "mac_address",
                  "gateway_id",
                  "device_type"
                ],
                "properties": {
                  "label": {
                    "type": "string",
                    "description": "Device label.",
                    "x-rules": "required"
                  },
                  "mac_address": {
                    "type": "string",
                    "description": "MAC address, letters and digits only. Unique among devices and gateways.",
                    "x-rules": "required|alpha_num|unique:iot_devices"
                  },
                  "custom": {
                    "type": "object",
                    "description": "Free-form key/value data. Keys may not contain whitespace; values are strings, integers or arrays.",
                    "x-rules": "nullable|array|new CustomArray()"
                  },
                  "gateway_id": {
                    "type": "string",
                    "description": "Gateway the device is attached to (uuid or ref_id).",
                    "x-rules": "required|new GatewayExists()"
                  },
                  "customer_id": {
                    "type": "string",
                    "description": "Validated but not used: the stored customer is the gateway's customer.",
                    "x-rules": "nullable|new CustomerExists()"
                  },
                  "device_type": {
                    "type": "string",
                    "description": "Device type name: camera, doorbell, gateway, led, light, lock, power, qr, sound, switch, temperature, utility or voice.",
                    "x-rules": "required|string|new DeviceTypeExists()"
                  },
                  "nest_id": {
                    "type": "string",
                    "description": "ref_id of an existing nest. Validated but not stored by this handler.",
                    "x-rules": "nullable|string|new NestExists()"
                  }
                }
              },
              "example": {
                "label": "Room 101",
                "mac_address": "d0c5e8ca0002",
                "gateway_id": "0b8cf01a-13a5-4ecb-94d4-b89e755e9fc7",
                "customer_id": "aa7fb10d-d22f-44e0-bdbd-7935d0796d6d",
                "device_type": "lock"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string"
                        }
                      }
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "ref_id": {
                          "type": "string"
                        },
                        "label": {
                          "type": "string"
                        },
                        "mac_address": {
                          "type": "string"
                        },
                        "customer": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "ref_id": {
                              "nullable": true
                            },
                            "company": {
                              "nullable": true
                            }
                          }
                        },
                        "location": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "ref_id": {
                              "nullable": true
                            },
                            "name": {
                              "nullable": true
                            }
                          }
                        },
                        "gateway": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "label": {
                              "type": "string"
                            },
                            "ref_id": {
                              "type": "string"
                            },
                            "mac_address": {
                              "type": "string"
                            }
                          }
                        },
                        "device_type": {
                          "type": "string"
                        },
                        "state": {
                          "type": "object",
                          "properties": {
                            "active": {
                              "type": "boolean"
                            },
                            "last_reported": {
                              "nullable": true
                            }
                          }
                        },
                        "sensors": {
                          "type": "object",
                          "properties": {
                            "bat": {
                              "type": "integer"
                            },
                            "rssi": {
                              "type": "integer"
                            },
                            "temp": {
                              "type": "integer"
                            }
                          }
                        },
                        "status": {
                          "type": "object",
                          "properties": {
                            "online": {
                              "type": "boolean"
                            },
                            "active": {
                              "type": "boolean"
                            },
                            "battery": {
                              "type": "integer"
                            },
                            "rssi": {
                              "type": "integer"
                            },
                            "temperature": {
                              "type": "integer"
                            },
                            "action": {
                              "type": "string"
                            },
                            "updated_at": {
                              "nullable": true
                            }
                          }
                        },
                        "capabilities": {
                          "type": "object",
                          "properties": {
                            "open": {
                              "type": "string"
                            },
                            "close": {
                              "type": "string"
                            },
                            "toggle": {
                              "type": "string"
                            },
                            "led": {
                              "type": "string"
                            }
                          }
                        },
                        "actions": {
                          "type": "object",
                          "properties": {
                            "open": {
                              "type": "string"
                            },
                            "close": {
                              "type": "string"
                            },
                            "toggle": {
                              "type": "string"
                            },
                            "led": {
                              "type": "string"
                            }
                          }
                        },
                        "topic": {
                          "type": "string"
                        },
                        "custom": {
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "links": {
                    "self": "/v1/devices"
                  },
                  "data": {
                    "id": "c032da71-853c-4242-8859-b897e59f1dbe",
                    "ref_id": "01m5hxcr4ebc4hwcg5ry9kct3n",
                    "label": "Room 101",
                    "mac_address": "d0c5e8ca0002",
                    "customer": {
                      "id": "aa7fb10d-d22f-44e0-bdbd-7935d0796d6d",
                      "ref_id": null,
                      "company": null
                    },
                    "location": {
                      "id": "4ad9c6b8-615c-43e7-8484-ce9c09a40400",
                      "ref_id": null,
                      "name": null
                    },
                    "gateway": {
                      "id": "0b8cf01a-13a5-4ecb-94d4-b89e755e9fc7",
                      "label": "Floor 1 gateway east",
                      "ref_id": "01m5hxcqdgmbxdvg30g22w5rhf",
                      "mac_address": "d0c5e8ca0001"
                    },
                    "device_type": "lock",
                    "state": {
                      "active": true,
                      "last_reported": null
                    },
                    "sensors": {
                      "bat": 0,
                      "rssi": 0,
                      "temp": 0
                    },
                    "status": {
                      "online": false,
                      "active": true,
                      "battery": 0,
                      "rssi": 0,
                      "temperature": 0,
                      "action": "",
                      "updated_at": null
                    },
                    "capabilities": {
                      "open": "c70a5a66-7a78-49cf-9dae-2881badc5cc8",
                      "close": "7733462c-a76e-4a38-9b37-6a7cb29a966e",
                      "toggle": "ac06b722-4683-4482-b642-c3f70c0bf162",
                      "led": "28e9d909-2ced-47ee-ae21-b71c9d8d6367"
                    },
                    "actions": {
                      "open": "/v1/actions/dv-01m5hxcr4ebc4hwcg5ry9kct3n-open-lock",
                      "close": "/v1/actions/dv-01m5hxcr4ebc4hwcg5ry9kct3n-close-lock",
                      "toggle": "/v1/actions/dv-01m5hxcr4ebc4hwcg5ry9kct3n-toggle-lock",
                      "led": "/v1/actions/dv-01m5hxcr4ebc4hwcg5ry9kct3n-toggle-led"
                    },
                    "topic": "d0c5e8ca0001_d0c5e8ca0002",
                    "custom": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "422": {
            "$ref": "#/components/responses/ValidationFailed"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/devices/{device}": {
      "delete": {
        "operationId": "delete-v1-devices-device",
        "tags": [
          "Devices"
        ],
        "summary": "Delete a device",
        "description": "Deletes the device. {device} is the device id or ref_id. Returns 204.",
        "parameters": [
          {
            "name": "device",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "c032da71-853c-4242-8859-b897e59f1dbe"
          }
        ],
        "responses": {
          "204": {
            "description": "No content"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      },
      "get": {
        "operationId": "get-v1-devices-device",
        "tags": [
          "Devices"
        ],
        "summary": "Show a device",
        "description": "Returns one device with its customer, location, gateway, state and sensor values. {device} is the device id or ref_id. Run one of its `actions` with [Run an action](#/get-v1-actions-action).",
        "parameters": [
          {
            "name": "device",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "65fcb74b-92d9-40c6-8732-b30b9afa2488"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string"
                        }
                      }
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "ref_id": {
                          "type": "string"
                        },
                        "label": {
                          "type": "string"
                        },
                        "mac_address": {
                          "type": "string"
                        },
                        "customer": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "ref_id": {
                              "type": "string"
                            },
                            "company": {
                              "type": "string"
                            }
                          }
                        },
                        "location": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "ref_id": {
                              "type": "string"
                            },
                            "name": {
                              "type": "string"
                            }
                          }
                        },
                        "gateway": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "label": {
                              "type": "string"
                            },
                            "ref_id": {
                              "type": "string"
                            },
                            "mac_address": {
                              "type": "string"
                            }
                          }
                        },
                        "device_type": {
                          "type": "string"
                        },
                        "state": {
                          "type": "object",
                          "properties": {
                            "active": {
                              "type": "boolean"
                            },
                            "last_reported": {
                              "type": "string",
                              "format": "date-time"
                            }
                          }
                        },
                        "sensors": {
                          "type": "object",
                          "properties": {
                            "bat": {
                              "type": "integer"
                            },
                            "rssi": {
                              "type": "integer"
                            },
                            "temp": {
                              "type": "integer"
                            }
                          }
                        },
                        "status": {
                          "type": "object",
                          "properties": {
                            "online": {
                              "type": "boolean"
                            },
                            "active": {
                              "type": "boolean"
                            },
                            "battery": {
                              "type": "integer"
                            },
                            "rssi": {
                              "type": "integer"
                            },
                            "temperature": {
                              "type": "integer"
                            },
                            "action": {
                              "type": "string"
                            },
                            "updated_at": {
                              "type": "string",
                              "format": "date-time"
                            }
                          }
                        },
                        "capabilities": {
                          "type": "object",
                          "properties": {
                            "open": {
                              "type": "string"
                            },
                            "close": {
                              "type": "string"
                            },
                            "toggle": {
                              "type": "string"
                            },
                            "led": {
                              "type": "string"
                            }
                          }
                        },
                        "actions": {
                          "type": "object",
                          "properties": {
                            "open": {
                              "type": "string"
                            },
                            "close": {
                              "type": "string"
                            },
                            "toggle": {
                              "type": "string"
                            },
                            "led": {
                              "type": "string"
                            }
                          }
                        },
                        "topic": {
                          "type": "string"
                        },
                        "custom": {
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "links": {
                    "self": "/v1/devices/65fcb74b-92d9-40c6-8732-b30b9afa2488"
                  },
                  "data": {
                    "id": "65fcb74b-92d9-40c6-8732-b30b9afa2488",
                    "ref_id": "01hzpjvzgjxm2qkwd9bw7dhc5h",
                    "label": "Staff entrance",
                    "mac_address": "asrfadf4",
                    "customer": {
                      "id": "eb88e4e7-c451-4112-9bb1-2124a0f5b48e",
                      "ref_id": "01hyfvr34329jb8gw1rft7sea7",
                      "company": "Keyless Labs"
                    },
                    "location": {
                      "id": "79fad71c-c6a8-41c0-b1cd-b579b11371df",
                      "ref_id": "01hyfvrp008ept70kak8ss9r5z",
                      "name": "Riverside Maastricht"
                    },
                    "gateway": {
                      "id": "83b30351-a4e0-46f0-af8b-0b054aecb7f5",
                      "label": "Lobby entrance",
                      "ref_id": "01hyfvsdpe1srnrtqdnbt45rm3",
                      "mac_address": "0x0123456789"
                    },
                    "device_type": "lock",
                    "state": {
                      "active": true,
                      "last_reported": "2024-06-06 10:38:48"
                    },
                    "sensors": {
                      "bat": 0,
                      "rssi": 0,
                      "temp": 0
                    },
                    "status": {
                      "online": true,
                      "active": true,
                      "battery": 0,
                      "rssi": 0,
                      "temperature": 0,
                      "action": "close",
                      "updated_at": "2024-06-06 10:38:48"
                    },
                    "capabilities": {
                      "open": "c70a5a66-7a78-49cf-9dae-2881badc5cc8",
                      "close": "7733462c-a76e-4a38-9b37-6a7cb29a966e",
                      "toggle": "ac06b722-4683-4482-b642-c3f70c0bf162",
                      "led": "28e9d909-2ced-47ee-ae21-b71c9d8d6367"
                    },
                    "actions": {
                      "open": "/v1/actions/dv-01hzpjvzgjxm2qkwd9bw7dhc5h-open-lock",
                      "close": "/v1/actions/dv-01hzpjvzgjxm2qkwd9bw7dhc5h-close-lock",
                      "toggle": "/v1/actions/dv-01hzpjvzgjxm2qkwd9bw7dhc5h-toggle-lock",
                      "led": "/v1/actions/dv-01hzpjvzgjxm2qkwd9bw7dhc5h-toggle-led"
                    },
                    "topic": "0x0123456789_asrfadf4",
                    "custom": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      },
      "put": {
        "operationId": "put-v1-devices-device",
        "tags": [
          "Devices"
        ],
        "summary": "Update a device",
        "description": "Updates the device. Customer and location follow the gateway. {device} is the device id or ref_id.",
        "parameters": [
          {
            "name": "device",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "c032da71-853c-4242-8859-b897e59f1dbe"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "gateway_id"
                ],
                "properties": {
                  "label": {
                    "type": "string",
                    "description": "Device label.",
                    "x-rules": "sometimes|string"
                  },
                  "mac_address": {
                    "type": "string",
                    "description": "MAC address, letters and digits only. Unique among devices and gateways.",
                    "x-rules": "sometimes|alpha_num|unique:iot_devices,mac_address,<device id>"
                  },
                  "custom": {
                    "type": "object",
                    "description": "Free-form key/value data. Keys may not contain whitespace; values are strings, integers or arrays.",
                    "x-rules": "sometimes|array|new CustomArray()"
                  },
                  "gateway_id": {
                    "type": "string",
                    "description": "Gateway the device is attached to (uuid or ref_id).",
                    "x-rules": "required|new GatewayExists()"
                  },
                  "device_type": {
                    "type": "string",
                    "description": "Device type name: camera, doorbell, gateway, led, light, lock, power, qr, sound, switch, temperature, utility or voice.",
                    "x-rules": "sometimes|string|new DeviceTypeExists()"
                  },
                  "nest_id": {
                    "type": "string",
                    "description": "ref_id of an existing nest. Validated but not stored by this handler.",
                    "x-rules": "nullable|string|new NestExists()"
                  }
                }
              },
              "example": {
                "label": "Room 101 entrance",
                "gateway_id": "0b8cf01a-13a5-4ecb-94d4-b89e755e9fc7"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string"
                        }
                      }
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "ref_id": {
                          "type": "string"
                        },
                        "label": {
                          "type": "string"
                        },
                        "mac_address": {
                          "type": "string"
                        },
                        "customer": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "ref_id": {
                              "type": "string"
                            },
                            "company": {
                              "type": "string"
                            }
                          }
                        },
                        "location": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "ref_id": {
                              "type": "string"
                            },
                            "name": {
                              "type": "string"
                            }
                          }
                        },
                        "gateway": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "label": {
                              "type": "string"
                            },
                            "ref_id": {
                              "type": "string"
                            },
                            "mac_address": {
                              "type": "string"
                            }
                          }
                        },
                        "device_type": {
                          "type": "string"
                        },
                        "state": {
                          "type": "object",
                          "properties": {
                            "active": {
                              "type": "boolean"
                            },
                            "last_reported": {
                              "type": "string",
                              "format": "date-time"
                            }
                          }
                        },
                        "sensors": {
                          "type": "object",
                          "properties": {
                            "bat": {
                              "type": "integer"
                            },
                            "rssi": {
                              "type": "integer"
                            },
                            "temp": {
                              "type": "integer"
                            }
                          }
                        },
                        "status": {
                          "type": "object",
                          "properties": {
                            "online": {
                              "type": "boolean"
                            },
                            "active": {
                              "type": "boolean"
                            },
                            "battery": {
                              "type": "integer"
                            },
                            "rssi": {
                              "type": "integer"
                            },
                            "temperature": {
                              "type": "integer"
                            },
                            "action": {
                              "type": "string"
                            },
                            "updated_at": {
                              "type": "string",
                              "format": "date-time"
                            }
                          }
                        },
                        "capabilities": {
                          "type": "object",
                          "properties": {
                            "open": {
                              "type": "string"
                            },
                            "close": {
                              "type": "string"
                            },
                            "toggle": {
                              "type": "string"
                            },
                            "led": {
                              "type": "string"
                            }
                          }
                        },
                        "actions": {
                          "type": "object",
                          "properties": {
                            "open": {
                              "type": "string"
                            },
                            "close": {
                              "type": "string"
                            },
                            "toggle": {
                              "type": "string"
                            },
                            "led": {
                              "type": "string"
                            }
                          }
                        },
                        "topic": {
                          "type": "string"
                        },
                        "custom": {
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "links": {
                    "self": "/v1/devices/c032da71-853c-4242-8859-b897e59f1dbe"
                  },
                  "data": {
                    "id": "c032da71-853c-4242-8859-b897e59f1dbe",
                    "ref_id": "01m5hxcr4ebc4hwcg5ry9kct3n",
                    "label": "Room 101 entrance",
                    "mac_address": "d0c5e8ca0002",
                    "customer": {
                      "id": "aa7fb10d-d22f-44e0-bdbd-7935d0796d6d",
                      "ref_id": "01m5hxcn9yybzmkj9k614q1f1n",
                      "company": "Harborview Hotels"
                    },
                    "location": {
                      "id": "4ad9c6b8-615c-43e7-8484-ce9c09a40400",
                      "ref_id": "01m5hxcnmpmtv8g18wa8eng8d4",
                      "name": "Harborview Amsterdam Centraal"
                    },
                    "gateway": {
                      "id": "0b8cf01a-13a5-4ecb-94d4-b89e755e9fc7",
                      "label": "Floor 1 gateway east",
                      "ref_id": "01m5hxcqdgmbxdvg30g22w5rhf",
                      "mac_address": "d0c5e8ca0001"
                    },
                    "device_type": "lock",
                    "state": {
                      "active": true,
                      "last_reported": "2026-10-22 13:39:16"
                    },
                    "sensors": {
                      "bat": 0,
                      "rssi": 0,
                      "temp": 0
                    },
                    "status": {
                      "online": false,
                      "active": true,
                      "battery": 0,
                      "rssi": 0,
                      "temperature": 0,
                      "action": "close",
                      "updated_at": "2026-10-22 13:39:16"
                    },
                    "capabilities": {
                      "open": "c70a5a66-7a78-49cf-9dae-2881badc5cc8",
                      "close": "7733462c-a76e-4a38-9b37-6a7cb29a966e",
                      "toggle": "ac06b722-4683-4482-b642-c3f70c0bf162",
                      "led": "28e9d909-2ced-47ee-ae21-b71c9d8d6367"
                    },
                    "actions": {
                      "open": "/v1/actions/dv-01m5hxcr4ebc4hwcg5ry9kct3n-open-lock",
                      "close": "/v1/actions/dv-01m5hxcr4ebc4hwcg5ry9kct3n-close-lock",
                      "toggle": "/v1/actions/dv-01m5hxcr4ebc4hwcg5ry9kct3n-toggle-lock",
                      "led": "/v1/actions/dv-01m5hxcr4ebc4hwcg5ry9kct3n-toggle-led"
                    },
                    "topic": "d0c5e8ca0001_d0c5e8ca0002",
                    "custom": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationFailed"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/devices/{device}/capabilities": {
      "get": {
        "operationId": "get-v1-devices-device-capabilities",
        "tags": [
          "Devices"
        ],
        "summary": "List capabilities of a device",
        "description": "Returns the capabilities of the device's type (id, capability name and ref_id). The id is what POST /v1/devices/{device}/state expects. {device} is the device id or ref_id.",
        "parameters": [
          {
            "name": "device",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "65fcb74b-92d9-40c6-8732-b30b9afa2488"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "capability": {
                            "type": "string"
                          },
                          "ref_id": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "c70a5a66-7a78-49cf-9dae-2881badc5cc8",
                      "capability": "open",
                      "ref_id": "01e0z7zrqfsm3ncrbd7e3y3j3c"
                    },
                    {
                      "id": "7733462c-a76e-4a38-9b37-6a7cb29a966e",
                      "capability": "close",
                      "ref_id": "01e0z7zrqpkc504pha1h6qcxnv"
                    },
                    {
                      "id": "ac06b722-4683-4482-b642-c3f70c0bf162",
                      "capability": "toggle",
                      "ref_id": "01e0z7zrq1ht4j7pq9frf128e3"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/devices/{device}/state": {
      "get": {
        "operationId": "get-v1-devices-device-state",
        "tags": [
          "Devices"
        ],
        "summary": "Show the state of a device",
        "description": "Returns the state of the device. {device} is the device id or ref_id.",
        "parameters": [
          {
            "name": "device",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "65fcb74b-92d9-40c6-8732-b30b9afa2488"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string"
                        }
                      }
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "state": {
                          "type": "array",
                          "items": {}
                        }
                      }
                    }
                  }
                },
                "example": {
                  "links": {
                    "self": "/v1/devices/65fcb74b-92d9-40c6-8732-b30b9afa2488/state"
                  },
                  "data": {
                    "state": []
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      },
      "post": {
        "operationId": "post-v1-devices-device-state",
        "tags": [
          "Devices"
        ],
        "summary": "Send a command to a device",
        "description": "Sends the capability's command to the device and returns 200 without confirming delivery. {device} is the device id or ref_id.",
        "parameters": [
          {
            "name": "device",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "capability"
                ],
                "properties": {
                  "capability": {
                    "type": "string",
                    "description": "Id of one of the device's capabilities (uuid from GET /v1/devices/{device}/capabilities).",
                    "x-rules": "required|uuid|new DeviceCapabilityExists()"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationFailed"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/devicestate/{hostId}/{state}": {
      "get": {
        "operationId": "get-v1-devicestate-hostId-state",
        "tags": [
          "Devices"
        ],
        "summary": "Set the active state from a Zabbix callback",
        "description": "Monitoring callback. Sets the device or gateway with host id {hostId} active when {state} is 1, otherwise inactive. Returns 204 when no device or gateway has that host id.",
        "parameters": [
          {
            "name": "hostId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "state",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/devicetriggers/{hostId}": {
      "post": {
        "operationId": "post-v1-devicetriggers-hostId",
        "tags": [
          "Devices"
        ],
        "summary": "Update a status from a Zabbix trigger",
        "description": "Monitoring callback. Updates the status of the device or gateway with host id {hostId}. Returns 200, or 204 when no device or gateway has that host id.",
        "parameters": [
          {
            "name": "hostId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "label",
                  "value"
                ],
                "properties": {
                  "label": {
                    "type": "string",
                    "description": "What the value is for: 'state' or 'action'.",
                    "x-rules": "required"
                  },
                  "value": {
                    "type": "string",
                    "description": "The new value.",
                    "x-rules": "required"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationFailed"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/devicetypes/{devicetype}": {
      "get": {
        "operationId": "get-v1-devicetypes-devicetype",
        "tags": [
          "Device types"
        ],
        "summary": "Show a device type",
        "description": "Returns one device type. {devicetype} is the type id.",
        "parameters": [
          {
            "name": "devicetype",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "23a125ac-6fd1-4b08-876e-09a4b49d6376"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "capabilities": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "capability": {
                                "type": "string"
                              },
                              "has_led": {
                                "type": "boolean"
                              }
                            }
                          }
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": {
                    "id": "23a125ac-6fd1-4b08-876e-09a4b49d6376",
                    "name": "lock",
                    "capabilities": [
                      {
                        "id": "c70a5a66-7a78-49cf-9dae-2881badc5cc8",
                        "ref_id": "01e0z7zrqfsm3ncrbd7e3y3j3c",
                        "capability": "open",
                        "has_led": false
                      },
                      {
                        "id": "7733462c-a76e-4a38-9b37-6a7cb29a966e",
                        "ref_id": "01e0z7zrqpkc504pha1h6qcxnv",
                        "capability": "close",
                        "has_led": false
                      },
                      {
                        "id": "ac06b722-4683-4482-b642-c3f70c0bf162",
                        "ref_id": "01e0z7zrq1ht4j7pq9frf128e3",
                        "capability": "toggle",
                        "has_led": false
                      }
                    ]
                  },
                  "links": {
                    "self": "v1/devicetypes/23a125ac-6fd1-4b08-876e-09a4b49d6376"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/devicetypes/{devicetype}/capabilities": {
      "get": {
        "operationId": "get-v1-devicetypes-devicetype-capabilities",
        "tags": [
          "Device types"
        ],
        "summary": "List capabilities of a device type",
        "description": "Deprecated.",
        "parameters": [
          {
            "name": "devicetype",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "23a125ac-6fd1-4b08-876e-09a4b49d6376"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string"
                        }
                      }
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "object",
                          "properties": {
                            "code": {
                              "type": "integer"
                            },
                            "message": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "links": {
                    "self": "/v1/devicetypes/23a125ac-6fd1-4b08-876e-09a4b49d6376/capabilities"
                  },
                  "data": {
                    "success": {
                      "code": 200,
                      "message": "OK"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/gateways": {
      "get": {
        "operationId": "get-v1-gateways",
        "tags": [
          "Gateways"
        ],
        "summary": "List gateways",
        "description": "Returns a page of gateways, sorted by label.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1 to 50. Values outside the range are clamped. Default 50.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, starting at 1.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "direction",
            "in": "query",
            "required": false,
            "description": "Sort direction, asc or desc. Default asc.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Search term, matched with LIKE against the searchable columns. No filtering when empty.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search_key",
            "in": "query",
            "required": false,
            "description": "Column to search: label, mac_address or all. Default: label and mac_address.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fuzzy",
            "in": "query",
            "required": false,
            "description": "Match mode for the term: start (term%), end (%term), fuzzy (characters in order, %t%e%s%t%). Any other value matches anywhere in the column (%term%). Default: match anywhere.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "1 returns only rows reported online by the Zabbix webhook, 0 returns the rest. A row without a status record counts as not online. No filtering when absent.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "ref_id": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          },
                          "state": {
                            "type": "array",
                            "items": {}
                          },
                          "mac_address": {
                            "type": "string"
                          },
                          "customer": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "company": {
                                "type": "string"
                              }
                            }
                          },
                          "location": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              }
                            }
                          },
                          "device_type": {
                            "type": "string"
                          },
                          "actions": {
                            "type": "object",
                            "properties": {
                              "open": {
                                "type": "string"
                              },
                              "close": {
                                "type": "string"
                              }
                            }
                          },
                          "topic": {
                            "type": "string"
                          },
                          "status": {
                            "type": "object",
                            "properties": {
                              "online": {
                                "type": "boolean"
                              },
                              "battery": {
                                "type": "integer"
                              },
                              "rssi": {
                                "type": "integer"
                              },
                              "temperature": {
                                "type": "integer"
                              },
                              "action": {
                                "type": "string"
                              },
                              "updated_at": {
                                "type": "string",
                                "format": "date-time"
                              }
                            }
                          },
                          "monitoring": {
                            "type": "array",
                            "items": {}
                          },
                          "custom": {
                            "nullable": true
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "current_page": {
                          "type": "integer"
                        },
                        "prev_page": {
                          "type": "boolean"
                        },
                        "next_page": {
                          "type": "boolean"
                        },
                        "last_page": {
                          "type": "integer"
                        },
                        "from": {
                          "type": "integer"
                        },
                        "to": {
                          "type": "integer"
                        },
                        "per_page": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "first": {
                          "type": "string"
                        },
                        "last": {
                          "type": "string"
                        },
                        "next": {
                          "nullable": true
                        },
                        "prev": {
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "2daf7361-fa52-4ce0-ae0b-e417558b69ff",
                      "ref_id": "01jvvhhxpzy14nres1bxbct9a3",
                      "label": "Suite 401",
                      "state": [],
                      "mac_address": "0x123",
                      "customer": {
                        "id": "daf62a38-5a89-4944-b01f-7b6cc9e88f77",
                        "ref_id": "01eg1v6h2qt17etgwe17jd3fbh",
                        "company": "Polder Parks"
                      },
                      "location": {
                        "id": "bd7838dc-7368-4317-89e0-2272f8d9f068",
                        "ref_id": "01fkk6424dnmwq7egj0hy7varf",
                        "name": "Meadow Lodge Veluwe"
                      },
                      "device_type": "gateway",
                      "actions": {
                        "open": "/v1/actions/gw-01jvvhhxpzy14nres1bxbct9a3-open-gateway",
                        "close": "/v1/actions/gw-01jvvhhxpzy14nres1bxbct9a3-close-gateway"
                      },
                      "topic": "0x123_network",
                      "status": {
                        "online": true,
                        "battery": 0,
                        "rssi": 0,
                        "temperature": 0,
                        "action": "close",
                        "updated_at": "2025-05-22 07:31:40"
                      },
                      "monitoring": [],
                      "custom": null
                    },
                    {
                      "id": "9ad2b747-5a37-4131-8ea8-e7b6a8824ff0",
                      "ref_id": "01gvz1g7y6ypsw755hvyrma6af",
                      "label": "Spa door",
                      "state": [],
                      "mac_address": "0x01234567890",
                      "customer": {
                        "id": "d8548e65-6f2e-4a68-bea8-297a13a98131",
                        "ref_id": "01gvz1e90q1f8dnheadzv4pbxm",
                        "company": "Linden Hotels"
                      },
                      "location": {
                        "id": "4060486d-15f0-47d8-9b7a-a37d9466360b",
                        "ref_id": "01gvz1f6n7zt9fgzz2230pjw6t",
                        "name": "Meadow Lodge Veluwe"
                      },
                      "device_type": "gateway",
                      "actions": {
                        "open": "/v1/actions/gw-01gvz1g7y6ypsw755hvyrma6af-open-gateway",
                        "close": "/v1/actions/gw-01gvz1g7y6ypsw755hvyrma6af-close-gateway"
                      },
                      "topic": "0x01234567890_network",
                      "status": {
                        "online": true,
                        "battery": 0,
                        "rssi": 0,
                        "temperature": 0,
                        "action": "close",
                        "updated_at": "2023-03-20 07:22:45"
                      },
                      "monitoring": [],
                      "custom": null
                    },
                    {
                      "id": "d5be484e-f107-4251-85b2-6095a16679a4",
                      "ref_id": "01ghxvz56e8sb3bad09wbvhm9w",
                      "label": "Room 103",
                      "state": [],
                      "mac_address": "0x124b0026e85852",
                      "customer": {
                        "id": "daf62a38-5a89-4944-b01f-7b6cc9e88f77",
                        "ref_id": "01eg1v6h2qt17etgwe17jd3fbh",
                        "company": "Polder Parks"
                      },
                      "location": {
                        "id": "bd7838dc-7368-4317-89e0-2272f8d9f068",
                        "ref_id": "01fkk6424dnmwq7egj0hy7varf",
                        "name": "Meadow Lodge Veluwe"
                      },
                      "device_type": "gateway",
                      "actions": {
                        "open": "/v1/actions/gw-01ghxvz56e8sb3bad09wbvhm9w-open-gateway",
                        "close": "/v1/actions/gw-01ghxvz56e8sb3bad09wbvhm9w-close-gateway"
                      },
                      "topic": "0x124b0026e85852_network",
                      "status": {
                        "online": true,
                        "battery": 0,
                        "rssi": 0,
                        "temperature": 0,
                        "action": "close",
                        "updated_at": "2023-10-06 08:31:03"
                      },
                      "monitoring": [],
                      "custom": null
                    }
                  ],
                  "meta": {
                    "current_page": 1,
                    "prev_page": false,
                    "next_page": false,
                    "last_page": 1,
                    "from": 1,
                    "to": 28,
                    "per_page": 50,
                    "limit": 50,
                    "total": 28
                  },
                  "links": {
                    "first": "v1/gateways?page=1",
                    "last": "v1/gateways?page=1",
                    "next": null,
                    "prev": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      },
      "post": {
        "operationId": "post-v1-gateways",
        "tags": [
          "Gateways"
        ],
        "summary": "Create a gateway",
        "description": "Creates the gateway. Customer comes from the location.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "label",
                  "mac_address",
                  "location_id"
                ],
                "properties": {
                  "label": {
                    "type": "string",
                    "description": "Gateway label. Unique among devices and gateways.",
                    "x-rules": "required|string|unique:iot_devices"
                  },
                  "mac_address": {
                    "type": "string",
                    "description": "MAC address, letters and digits only. Unique among devices and gateways.",
                    "x-rules": "required|alpha_num|unique:iot_devices"
                  },
                  "location_id": {
                    "type": "string",
                    "description": "Location of the gateway (uuid or ref_id).",
                    "x-rules": "required|new LocationExists()"
                  },
                  "nest_id": {
                    "type": "string",
                    "description": "ref_id of an existing nest. Validated but not stored by this handler.",
                    "x-rules": "nullable|string|new NestExists()"
                  },
                  "custom": {
                    "type": "object",
                    "description": "Free-form key/value data. Keys may not contain whitespace; values are strings, integers or arrays.",
                    "x-rules": "nullable|array|new CustomArray()"
                  }
                }
              },
              "example": {
                "label": "Floor 1 gateway",
                "mac_address": "d0c5e8ca0001",
                "location_id": "4ad9c6b8-615c-43e7-8484-ce9c09a40400"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string"
                        }
                      }
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "ref_id": {
                          "type": "string"
                        },
                        "label": {
                          "type": "string"
                        },
                        "state": {
                          "type": "array",
                          "items": {}
                        },
                        "mac_address": {
                          "type": "string"
                        },
                        "customer": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "ref_id": {
                              "nullable": true
                            },
                            "company": {
                              "nullable": true
                            }
                          }
                        },
                        "location": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "ref_id": {
                              "nullable": true
                            },
                            "name": {
                              "nullable": true
                            }
                          }
                        },
                        "device_type": {
                          "type": "string"
                        },
                        "actions": {
                          "type": "object",
                          "properties": {
                            "open": {
                              "type": "string"
                            },
                            "close": {
                              "type": "string"
                            }
                          }
                        },
                        "topic": {
                          "type": "string"
                        },
                        "status": {
                          "type": "object",
                          "properties": {
                            "online": {
                              "type": "boolean"
                            },
                            "battery": {
                              "type": "integer"
                            },
                            "rssi": {
                              "type": "integer"
                            },
                            "temperature": {
                              "type": "integer"
                            },
                            "action": {
                              "type": "string"
                            },
                            "updated_at": {
                              "nullable": true
                            }
                          }
                        },
                        "monitoring": {
                          "type": "array",
                          "items": {}
                        },
                        "custom": {
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "links": {
                    "self": "/v1/gateways"
                  },
                  "data": {
                    "id": "0b8cf01a-13a5-4ecb-94d4-b89e755e9fc7",
                    "ref_id": "01m5hxcqdgmbxdvg30g22w5rhf",
                    "label": "Floor 1 gateway",
                    "state": [],
                    "mac_address": "d0c5e8ca0001",
                    "customer": {
                      "id": "aa7fb10d-d22f-44e0-bdbd-7935d0796d6d",
                      "ref_id": null,
                      "company": null
                    },
                    "location": {
                      "id": "4ad9c6b8-615c-43e7-8484-ce9c09a40400",
                      "ref_id": null,
                      "name": null
                    },
                    "device_type": "gateway",
                    "actions": {
                      "open": "/v1/actions/gw-01m5hxcqdgmbxdvg30g22w5rhf-open-gateway",
                      "close": "/v1/actions/gw-01m5hxcqdgmbxdvg30g22w5rhf-close-gateway"
                    },
                    "topic": "d0c5e8ca0001_network",
                    "status": {
                      "online": false,
                      "battery": 0,
                      "rssi": 0,
                      "temperature": 0,
                      "action": "close",
                      "updated_at": null
                    },
                    "monitoring": [],
                    "custom": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "422": {
            "$ref": "#/components/responses/ValidationFailed"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/gateways/{gateway}": {
      "delete": {
        "operationId": "delete-v1-gateways-gateway",
        "tags": [
          "Gateways"
        ],
        "summary": "Delete a gateway",
        "description": "Deletes the gateway and every device on it. {gateway} is the gateway id or ref_id. Returns 204.",
        "parameters": [
          {
            "name": "gateway",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "0b8cf01a-13a5-4ecb-94d4-b89e755e9fc7"
          }
        ],
        "responses": {
          "204": {
            "description": "No content"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      },
      "get": {
        "operationId": "get-v1-gateways-gateway",
        "tags": [
          "Gateways"
        ],
        "summary": "Show a gateway",
        "description": "Returns one gateway. {gateway} is the gateway id or ref_id.",
        "parameters": [
          {
            "name": "gateway",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2daf7361-fa52-4ce0-ae0b-e417558b69ff"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string"
                        }
                      }
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "ref_id": {
                          "type": "string"
                        },
                        "label": {
                          "type": "string"
                        },
                        "state": {
                          "type": "array",
                          "items": {}
                        },
                        "mac_address": {
                          "type": "string"
                        },
                        "customer": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "ref_id": {
                              "type": "string"
                            },
                            "company": {
                              "type": "string"
                            }
                          }
                        },
                        "location": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "ref_id": {
                              "type": "string"
                            },
                            "name": {
                              "type": "string"
                            }
                          }
                        },
                        "device_type": {
                          "type": "string"
                        },
                        "actions": {
                          "type": "object",
                          "properties": {
                            "open": {
                              "type": "string"
                            },
                            "close": {
                              "type": "string"
                            }
                          }
                        },
                        "topic": {
                          "type": "string"
                        },
                        "status": {
                          "type": "object",
                          "properties": {
                            "online": {
                              "type": "boolean"
                            },
                            "battery": {
                              "type": "integer"
                            },
                            "rssi": {
                              "type": "integer"
                            },
                            "temperature": {
                              "type": "integer"
                            },
                            "action": {
                              "type": "string"
                            },
                            "updated_at": {
                              "type": "string",
                              "format": "date-time"
                            }
                          }
                        },
                        "monitoring": {
                          "type": "array",
                          "items": {}
                        },
                        "custom": {
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "links": {
                    "self": "/v1/gateways/2daf7361-fa52-4ce0-ae0b-e417558b69ff"
                  },
                  "data": {
                    "id": "2daf7361-fa52-4ce0-ae0b-e417558b69ff",
                    "ref_id": "01jvvhhxpzy14nres1bxbct9a3",
                    "label": "Suite 401",
                    "state": [],
                    "mac_address": "0x123",
                    "customer": {
                      "id": "daf62a38-5a89-4944-b01f-7b6cc9e88f77",
                      "ref_id": "01eg1v6h2qt17etgwe17jd3fbh",
                      "company": "Polder Parks"
                    },
                    "location": {
                      "id": "bd7838dc-7368-4317-89e0-2272f8d9f068",
                      "ref_id": "01fkk6424dnmwq7egj0hy7varf",
                      "name": "Meadow Lodge Veluwe"
                    },
                    "device_type": "gateway",
                    "actions": {
                      "open": "/v1/actions/gw-01jvvhhxpzy14nres1bxbct9a3-open-gateway",
                      "close": "/v1/actions/gw-01jvvhhxpzy14nres1bxbct9a3-close-gateway"
                    },
                    "topic": "0x123_network",
                    "status": {
                      "online": true,
                      "battery": 0,
                      "rssi": 0,
                      "temperature": 0,
                      "action": "close",
                      "updated_at": "2025-05-22 07:31:40"
                    },
                    "monitoring": [],
                    "custom": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      },
      "put": {
        "operationId": "put-v1-gateways-gateway",
        "tags": [
          "Gateways"
        ],
        "summary": "Update a gateway",
        "description": "Updates the gateway and moves all its devices to the same location and customer. Always send location_id. {gateway} is the gateway id or ref_id.",
        "parameters": [
          {
            "name": "gateway",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "0b8cf01a-13a5-4ecb-94d4-b89e755e9fc7"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [],
                "properties": {
                  "label": {
                    "type": "string",
                    "description": "Gateway label.",
                    "x-rules": "sometimes|required"
                  },
                  "mac_address": {
                    "type": "string",
                    "description": "MAC address, letters and digits only. Unique among devices and gateways.",
                    "x-rules": "sometimes|required|alpha_num|unique:iot_devices,mac_address,<gateway id>"
                  },
                  "location_id": {
                    "type": "string",
                    "description": "Location of the gateway (uuid or ref_id).",
                    "x-rules": "sometimes|new LocationExists()"
                  },
                  "custom": {
                    "type": "object",
                    "description": "Free-form key/value data. Keys may not contain whitespace; values are strings, integers or arrays.",
                    "x-rules": "nullable|array|new CustomArray()"
                  },
                  "nest_id": {
                    "type": "string",
                    "description": "ref_id of an existing nest. Validated but not stored by this handler.",
                    "x-rules": "nullable|string|new NestExists()"
                  }
                }
              },
              "example": {
                "label": "Floor 1 gateway east",
                "location_id": "4ad9c6b8-615c-43e7-8484-ce9c09a40400"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string"
                        }
                      }
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "ref_id": {
                          "type": "string"
                        },
                        "label": {
                          "type": "string"
                        },
                        "state": {
                          "type": "array",
                          "items": {}
                        },
                        "mac_address": {
                          "type": "string"
                        },
                        "customer": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "ref_id": {
                              "type": "string"
                            },
                            "company": {
                              "type": "string"
                            }
                          }
                        },
                        "location": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "ref_id": {
                              "type": "string"
                            },
                            "name": {
                              "type": "string"
                            }
                          }
                        },
                        "device_type": {
                          "type": "string"
                        },
                        "actions": {
                          "type": "object",
                          "properties": {
                            "open": {
                              "type": "string"
                            },
                            "close": {
                              "type": "string"
                            }
                          }
                        },
                        "topic": {
                          "type": "string"
                        },
                        "status": {
                          "type": "object",
                          "properties": {
                            "online": {
                              "type": "boolean"
                            },
                            "battery": {
                              "type": "integer"
                            },
                            "rssi": {
                              "type": "integer"
                            },
                            "temperature": {
                              "type": "integer"
                            },
                            "action": {
                              "type": "string"
                            },
                            "updated_at": {
                              "type": "string",
                              "format": "date-time"
                            }
                          }
                        },
                        "monitoring": {
                          "type": "array",
                          "items": {}
                        },
                        "custom": {
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "links": {
                    "self": "/v1/gateways/0b8cf01a-13a5-4ecb-94d4-b89e755e9fc7"
                  },
                  "data": {
                    "id": "0b8cf01a-13a5-4ecb-94d4-b89e755e9fc7",
                    "ref_id": "01m5hxcqdgmbxdvg30g22w5rhf",
                    "label": "Floor 1 gateway east",
                    "state": [],
                    "mac_address": "d0c5e8ca0001",
                    "customer": {
                      "id": "aa7fb10d-d22f-44e0-bdbd-7935d0796d6d",
                      "ref_id": "01m5hxcn9yybzmkj9k614q1f1n",
                      "company": "Harborview Hotels"
                    },
                    "location": {
                      "id": "4ad9c6b8-615c-43e7-8484-ce9c09a40400",
                      "ref_id": "01m5hxcnmpmtv8g18wa8eng8d4",
                      "name": "Harborview Amsterdam Centraal"
                    },
                    "device_type": "gateway",
                    "actions": {
                      "open": "/v1/actions/gw-01m5hxcqdgmbxdvg30g22w5rhf-open-gateway",
                      "close": "/v1/actions/gw-01m5hxcqdgmbxdvg30g22w5rhf-close-gateway"
                    },
                    "topic": "d0c5e8ca0001_network",
                    "status": {
                      "online": false,
                      "battery": 0,
                      "rssi": 0,
                      "temperature": 0,
                      "action": "close",
                      "updated_at": "2026-10-22 13:39:15"
                    },
                    "monitoring": [],
                    "custom": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationFailed"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/gateways/{gateway}/devices": {
      "get": {
        "operationId": "get-v1-gateways-gateway-devices",
        "tags": [
          "Gateways"
        ],
        "summary": "List devices of a gateway",
        "description": "Returns a page of the devices attached to the gateway, sorted by label. {gateway} is the gateway id or ref_id.",
        "parameters": [
          {
            "name": "gateway",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "2daf7361-fa52-4ce0-ae0b-e417558b69ff"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1 to 50. Values outside the range are clamped. Default 50.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, starting at 1.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Search term, matched with LIKE against the searchable columns. No filtering when empty.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search_key",
            "in": "query",
            "required": false,
            "description": "Column to search: label, mac_address or all. Default: label and mac_address.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fuzzy",
            "in": "query",
            "required": false,
            "description": "Match mode for the term: start (term%), end (%term), fuzzy (characters in order, %t%e%s%t%). Any other value matches anywhere in the column (%term%). Default: match anywhere.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "1 returns only rows reported online by the Zabbix webhook, 0 returns the rest. A row without a status record counts as not online. No filtering when absent.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "ref_id": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          },
                          "mac_address": {
                            "type": "string"
                          },
                          "customer": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "company": {
                                "type": "string"
                              }
                            }
                          },
                          "location": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              }
                            }
                          },
                          "gateway": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "label": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "mac_address": {
                                "type": "string"
                              }
                            }
                          },
                          "device_type": {
                            "type": "string"
                          },
                          "state": {
                            "type": "object",
                            "properties": {
                              "active": {
                                "type": "boolean"
                              },
                              "last_reported": {
                                "nullable": true
                              }
                            }
                          },
                          "sensors": {
                            "type": "object",
                            "properties": {
                              "bat": {
                                "type": "integer"
                              },
                              "rssi": {
                                "type": "integer"
                              },
                              "temp": {
                                "type": "integer"
                              }
                            }
                          },
                          "status": {
                            "type": "object",
                            "properties": {
                              "online": {
                                "type": "boolean"
                              },
                              "active": {
                                "type": "boolean"
                              },
                              "battery": {
                                "type": "integer"
                              },
                              "rssi": {
                                "type": "integer"
                              },
                              "temperature": {
                                "type": "integer"
                              },
                              "action": {
                                "type": "string"
                              },
                              "updated_at": {
                                "nullable": true
                              }
                            }
                          },
                          "capabilities": {
                            "type": "object",
                            "properties": {
                              "open": {
                                "type": "string"
                              },
                              "close": {
                                "type": "string"
                              },
                              "toggle": {
                                "type": "string"
                              },
                              "led": {
                                "type": "string"
                              }
                            }
                          },
                          "actions": {
                            "type": "object",
                            "properties": {
                              "open": {
                                "type": "string"
                              },
                              "close": {
                                "type": "string"
                              },
                              "toggle": {
                                "type": "string"
                              },
                              "led": {
                                "type": "string"
                              }
                            }
                          },
                          "topic": {
                            "type": "string"
                          },
                          "custom": {
                            "nullable": true
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "current_page": {
                          "type": "integer"
                        },
                        "prev_page": {
                          "type": "boolean"
                        },
                        "next_page": {
                          "type": "integer"
                        },
                        "last_page": {
                          "type": "integer"
                        },
                        "from": {
                          "type": "integer"
                        },
                        "to": {
                          "type": "integer"
                        },
                        "per_page": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "first": {
                          "type": "string"
                        },
                        "last": {
                          "type": "string"
                        },
                        "next": {
                          "type": "string"
                        },
                        "prev": {
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "f0e1d695-fea9-3717-8e89-8cdf26174643",
                      "ref_id": "9x988fxttas3d3a1c2m50qh8d1",
                      "label": "Gym",
                      "mac_address": "0x124b00d92b9482",
                      "customer": {
                        "id": "daf62a38-5a89-4944-b01f-7b6cc9e88f77",
                        "ref_id": "01eg1v6h2qt17etgwe17jd3fbh",
                        "company": "Polder Parks"
                      },
                      "location": {
                        "id": "bd7838dc-7368-4317-89e0-2272f8d9f068",
                        "ref_id": "01fkk6424dnmwq7egj0hy7varf",
                        "name": "Meadow Lodge Veluwe"
                      },
                      "gateway": {
                        "id": "2daf7361-fa52-4ce0-ae0b-e417558b69ff",
                        "label": "Suite 401",
                        "ref_id": "01jvvhhxpzy14nres1bxbct9a3",
                        "mac_address": "0x123"
                      },
                      "device_type": "lock",
                      "state": {
                        "active": true,
                        "last_reported": null
                      },
                      "sensors": {
                        "bat": 0,
                        "rssi": 0,
                        "temp": 0
                      },
                      "status": {
                        "online": false,
                        "active": true,
                        "battery": 0,
                        "rssi": 0,
                        "temperature": 0,
                        "action": "",
                        "updated_at": null
                      },
                      "capabilities": {
                        "open": "c70a5a66-7a78-49cf-9dae-2881badc5cc8",
                        "close": "7733462c-a76e-4a38-9b37-6a7cb29a966e",
                        "toggle": "ac06b722-4683-4482-b642-c3f70c0bf162",
                        "led": "28e9d909-2ced-47ee-ae21-b71c9d8d6367"
                      },
                      "actions": {
                        "open": "/v1/actions/dv-9x988fxttas3d3a1c2m50qh8d1-open-lock",
                        "close": "/v1/actions/dv-9x988fxttas3d3a1c2m50qh8d1-close-lock",
                        "toggle": "/v1/actions/dv-9x988fxttas3d3a1c2m50qh8d1-toggle-lock",
                        "led": "/v1/actions/dv-9x988fxttas3d3a1c2m50qh8d1-toggle-led"
                      },
                      "topic": "0x123_0x124b00d92b9482",
                      "custom": null
                    },
                    {
                      "id": "82af32bf-c9b3-3bf8-8a6c-c969f3cddf47",
                      "ref_id": "8yft66jq9bzwv1szf3eyrnx8sb",
                      "label": "Room 102",
                      "mac_address": "0x124b00a876cb95",
                      "customer": {
                        "id": "daf62a38-5a89-4944-b01f-7b6cc9e88f77",
                        "ref_id": "01eg1v6h2qt17etgwe17jd3fbh",
                        "company": "Polder Parks"
                      },
                      "location": {
                        "id": "bd7838dc-7368-4317-89e0-2272f8d9f068",
                        "ref_id": "01fkk6424dnmwq7egj0hy7varf",
                        "name": "Meadow Lodge Veluwe"
                      },
                      "gateway": {
                        "id": "2daf7361-fa52-4ce0-ae0b-e417558b69ff",
                        "label": "Suite 401",
                        "ref_id": "01jvvhhxpzy14nres1bxbct9a3",
                        "mac_address": "0x123"
                      },
                      "device_type": "lock",
                      "state": {
                        "active": true,
                        "last_reported": null
                      },
                      "sensors": {
                        "bat": 0,
                        "rssi": 0,
                        "temp": 0
                      },
                      "status": {
                        "online": false,
                        "active": true,
                        "battery": 0,
                        "rssi": 0,
                        "temperature": 0,
                        "action": "",
                        "updated_at": null
                      },
                      "capabilities": {
                        "open": "c70a5a66-7a78-49cf-9dae-2881badc5cc8",
                        "close": "7733462c-a76e-4a38-9b37-6a7cb29a966e",
                        "toggle": "ac06b722-4683-4482-b642-c3f70c0bf162",
                        "led": "28e9d909-2ced-47ee-ae21-b71c9d8d6367"
                      },
                      "actions": {
                        "open": "/v1/actions/dv-8yft66jq9bzwv1szf3eyrnx8sb-open-lock",
                        "close": "/v1/actions/dv-8yft66jq9bzwv1szf3eyrnx8sb-close-lock",
                        "toggle": "/v1/actions/dv-8yft66jq9bzwv1szf3eyrnx8sb-toggle-lock",
                        "led": "/v1/actions/dv-8yft66jq9bzwv1szf3eyrnx8sb-toggle-led"
                      },
                      "topic": "0x123_0x124b00a876cb95",
                      "custom": null
                    },
                    {
                      "id": "4ed3aed4-9457-337e-a3b0-eb16f69ed00b",
                      "ref_id": "bvw6pr8yn635mnxz5p6bwnd3w4",
                      "label": "Room 102",
                      "mac_address": "0x124b001015d33f",
                      "customer": {
                        "id": "daf62a38-5a89-4944-b01f-7b6cc9e88f77",
                        "ref_id": "01eg1v6h2qt17etgwe17jd3fbh",
                        "company": "Polder Parks"
                      },
                      "location": {
                        "id": "bd7838dc-7368-4317-89e0-2272f8d9f068",
                        "ref_id": "01fkk6424dnmwq7egj0hy7varf",
                        "name": "Meadow Lodge Veluwe"
                      },
                      "gateway": {
                        "id": "2daf7361-fa52-4ce0-ae0b-e417558b69ff",
                        "label": "Suite 401",
                        "ref_id": "01jvvhhxpzy14nres1bxbct9a3",
                        "mac_address": "0x123"
                      },
                      "device_type": "lock",
                      "state": {
                        "active": true,
                        "last_reported": null
                      },
                      "sensors": {
                        "bat": 0,
                        "rssi": 0,
                        "temp": 0
                      },
                      "status": {
                        "online": false,
                        "active": true,
                        "battery": 0,
                        "rssi": 0,
                        "temperature": 0,
                        "action": "",
                        "updated_at": null
                      },
                      "capabilities": {
                        "open": "c70a5a66-7a78-49cf-9dae-2881badc5cc8",
                        "close": "7733462c-a76e-4a38-9b37-6a7cb29a966e",
                        "toggle": "ac06b722-4683-4482-b642-c3f70c0bf162",
                        "led": "28e9d909-2ced-47ee-ae21-b71c9d8d6367"
                      },
                      "actions": {
                        "open": "/v1/actions/dv-bvw6pr8yn635mnxz5p6bwnd3w4-open-lock",
                        "close": "/v1/actions/dv-bvw6pr8yn635mnxz5p6bwnd3w4-close-lock",
                        "toggle": "/v1/actions/dv-bvw6pr8yn635mnxz5p6bwnd3w4-toggle-lock",
                        "led": "/v1/actions/dv-bvw6pr8yn635mnxz5p6bwnd3w4-toggle-led"
                      },
                      "topic": "0x123_0x124b001015d33f",
                      "custom": null
                    }
                  ],
                  "meta": {
                    "current_page": 1,
                    "prev_page": false,
                    "next_page": 2,
                    "last_page": 2,
                    "from": 1,
                    "to": 50,
                    "per_page": 50,
                    "limit": 50,
                    "total": 85
                  },
                  "links": {
                    "first": "v1/gateways/2daf7361-fa52-4ce0-ae0b-e417558b69ff/devices?page=1",
                    "last": "v1/gateways/2daf7361-fa52-4ce0-ae0b-e417558b69ff/devices?page=2",
                    "next": "v1/gateways/2daf7361-fa52-4ce0-ae0b-e417558b69ff/devices?page=2",
                    "prev": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/locations": {
      "get": {
        "operationId": "get-v1-locations",
        "tags": [
          "Locations"
        ],
        "summary": "List locations",
        "description": "Returns a page of locations with their customer, sorted by name.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1 to 50. Values outside the range are clamped. Default 50.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, starting at 1.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "direction",
            "in": "query",
            "required": false,
            "description": "Sort direction, asc or desc. Default asc.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Search term, matched with LIKE against the searchable columns. No filtering when empty.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search_key",
            "in": "query",
            "required": false,
            "description": "Column to search: name or all. Default: name.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fuzzy",
            "in": "query",
            "required": false,
            "description": "Match mode for the term: start (term%), end (%term), fuzzy (characters in order, %t%e%s%t%). Any other value matches anywhere in the column (%term%). Default: match anywhere.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "ref_id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "reference": {
                            "type": "string"
                          },
                          "customer": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "company": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "current_page": {
                          "type": "integer"
                        },
                        "prev_page": {
                          "type": "boolean"
                        },
                        "next_page": {
                          "type": "boolean"
                        },
                        "last_page": {
                          "type": "integer"
                        },
                        "from": {
                          "type": "integer"
                        },
                        "to": {
                          "type": "integer"
                        },
                        "per_page": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "first": {
                          "type": "string"
                        },
                        "last": {
                          "type": "string"
                        },
                        "next": {
                          "nullable": true
                        },
                        "prev": {
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "cf098ef1-bc66-4679-9da9-336ab5d1c561",
                      "ref_id": "01fkk63yt82hbs5h0gxjrexs43",
                      "name": "Grand Plaza Eindhoven",
                      "reference": "c2odemo89",
                      "customer": {
                        "id": "b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c",
                        "ref_id": "01e31vwgfbfkcxfavhba7k682q",
                        "company": "Seaside Resorts"
                      }
                    },
                    {
                      "id": "ffc8aa72-a7c9-4347-9908-5bb9de1a6f8d",
                      "ref_id": "01k6d7tn2dhvszt89hjme18pn8",
                      "name": "Riverside Maastricht",
                      "reference": "12",
                      "customer": {
                        "id": "41f9b289-f3a0-4e8f-8f8a-b0bdf43e0e88",
                        "ref_id": "01k6d7sz6zzaj4e4hrdzjz7s85",
                        "company": "Brightdoor Systems"
                      }
                    },
                    {
                      "id": "701d919c-75ff-4912-8ae0-fdea75432669",
                      "ref_id": "01k94q63a6cj9shdm5yrdg66rx",
                      "name": "Northwind Rotterdam",
                      "reference": "134555",
                      "customer": {
                        "id": "8422ab96-d903-49ef-a7da-103eec7bd256",
                        "ref_id": "01k94q5rzc3kqwmt5rh9secqck",
                        "company": "Northwind Stays"
                      }
                    }
                  ],
                  "meta": {
                    "current_page": 1,
                    "prev_page": false,
                    "next_page": false,
                    "last_page": 1,
                    "from": 1,
                    "to": 22,
                    "per_page": 50,
                    "limit": 50,
                    "total": 22
                  },
                  "links": {
                    "first": "v1/locations?page=1",
                    "last": "v1/locations?page=1",
                    "next": null,
                    "prev": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      },
      "post": {
        "operationId": "post-v1-locations",
        "tags": [
          "Locations"
        ],
        "summary": "Create a location",
        "description": "Creates a location for a customer and returns it with HTTP 201.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "customer_id"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Location name.",
                    "x-rules": "required"
                  },
                  "customer_id": {
                    "type": "string",
                    "description": "Customer that owns the location (uuid or ref_id).",
                    "x-rules": "required|new CustomerExists()"
                  },
                  "reference": {
                    "type": "string",
                    "description": "Your own reference. Unique among locations.",
                    "x-rules": "nullable|unique:iot_locations"
                  }
                }
              },
              "example": {
                "name": "Harborview Amsterdam",
                "customer_id": "aa7fb10d-d22f-44e0-bdbd-7935d0796d6d",
                "reference": "HV-AMS-e8ca"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string"
                        }
                      }
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "ref_id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "reference": {
                          "type": "string"
                        },
                        "customer": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "ref_id": {
                              "nullable": true
                            },
                            "company": {
                              "nullable": true
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "links": {
                    "self": "/v1/locations"
                  },
                  "data": {
                    "id": "4ad9c6b8-615c-43e7-8484-ce9c09a40400",
                    "ref_id": "01m5hxcnmpmtv8g18wa8eng8d4",
                    "name": "Harborview Amsterdam",
                    "reference": "HV-AMS-e8ca",
                    "customer": {
                      "id": "aa7fb10d-d22f-44e0-bdbd-7935d0796d6d",
                      "ref_id": null,
                      "company": null
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "422": {
            "$ref": "#/components/responses/ValidationFailed"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/locations/{location}": {
      "delete": {
        "operationId": "delete-v1-locations-location",
        "tags": [
          "Locations"
        ],
        "summary": "Delete a location",
        "description": "Deletes the location together with its gateways and their devices. {location} is the location id or ref_id. Returns 204.",
        "parameters": [
          {
            "name": "location",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "4ad9c6b8-615c-43e7-8484-ce9c09a40400"
          }
        ],
        "responses": {
          "204": {
            "description": "No content"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      },
      "get": {
        "operationId": "get-v1-locations-location",
        "tags": [
          "Locations"
        ],
        "summary": "Show a location",
        "description": "Returns one location with its customer. {location} is the location id or ref_id.",
        "parameters": [
          {
            "name": "location",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "cf098ef1-bc66-4679-9da9-336ab5d1c561"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string"
                        }
                      }
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "ref_id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "reference": {
                          "type": "string"
                        },
                        "customer": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "ref_id": {
                              "type": "string"
                            },
                            "company": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "links": {
                    "self": "/v1/locations/cf098ef1-bc66-4679-9da9-336ab5d1c561"
                  },
                  "data": {
                    "id": "cf098ef1-bc66-4679-9da9-336ab5d1c561",
                    "ref_id": "01fkk63yt82hbs5h0gxjrexs43",
                    "name": "Grand Plaza Eindhoven",
                    "reference": "c2odemo89",
                    "customer": {
                      "id": "b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c",
                      "ref_id": "01e31vwgfbfkcxfavhba7k682q",
                      "company": "Seaside Resorts"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      },
      "put": {
        "operationId": "put-v1-locations-location",
        "tags": [
          "Locations"
        ],
        "summary": "Update a location",
        "description": "Updates the location. {location} is the location id or ref_id.",
        "parameters": [
          {
            "name": "location",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "4ad9c6b8-615c-43e7-8484-ce9c09a40400"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "name",
                  "customer_id"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Location name.",
                    "x-rules": "required"
                  },
                  "customer_id": {
                    "type": "string",
                    "description": "Customer that owns the location (uuid or ref_id).",
                    "x-rules": "required|new CustomerExists()"
                  },
                  "reference": {
                    "type": "string",
                    "description": "Your own reference. Unique among locations.",
                    "x-rules": "nullable|unique:iot_locations,reference,<location id>"
                  }
                }
              },
              "example": {
                "name": "Harborview Amsterdam Centraal",
                "customer_id": "aa7fb10d-d22f-44e0-bdbd-7935d0796d6d",
                "reference": "HV-AMS-e8ca"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string"
                        }
                      }
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "ref_id": {
                          "type": "string"
                        },
                        "name": {
                          "type": "string"
                        },
                        "reference": {
                          "type": "string"
                        },
                        "customer": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "ref_id": {
                              "type": "string"
                            },
                            "company": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "links": {
                    "self": "/v1/locations/4ad9c6b8-615c-43e7-8484-ce9c09a40400"
                  },
                  "data": {
                    "id": "4ad9c6b8-615c-43e7-8484-ce9c09a40400",
                    "ref_id": "01m5hxcnmpmtv8g18wa8eng8d4",
                    "name": "Harborview Amsterdam Centraal",
                    "reference": "HV-AMS-e8ca",
                    "customer": {
                      "id": "aa7fb10d-d22f-44e0-bdbd-7935d0796d6d",
                      "ref_id": "01m5hxcn9yybzmkj9k614q1f1n",
                      "company": "Harborview Hotels"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationFailed"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/locations/{location}/devices": {
      "get": {
        "operationId": "get-v1-locations-location-devices",
        "tags": [
          "Locations"
        ],
        "summary": "List devices of a location",
        "description": "Returns a page of the devices at the location, sorted by label. {location} is the location id or ref_id.",
        "parameters": [
          {
            "name": "location",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "cf098ef1-bc66-4679-9da9-336ab5d1c561"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1 to 50. Values outside the range are clamped. Default 50.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, starting at 1.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Search term, matched with LIKE against the searchable columns. No filtering when empty.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search_key",
            "in": "query",
            "required": false,
            "description": "Column to search: label, mac_address or all. Default: label and mac_address.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fuzzy",
            "in": "query",
            "required": false,
            "description": "Match mode for the term: start (term%), end (%term), fuzzy (characters in order, %t%e%s%t%). Any other value matches anywhere in the column (%term%). Default: match anywhere.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "1 returns only rows reported online by the Zabbix webhook, 0 returns the rest. A row without a status record counts as not online. No filtering when absent.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "ref_id": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          },
                          "mac_address": {
                            "type": "string"
                          },
                          "customer": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "company": {
                                "type": "string"
                              }
                            }
                          },
                          "location": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              }
                            }
                          },
                          "gateway": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "label": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "mac_address": {
                                "type": "string"
                              }
                            }
                          },
                          "device_type": {
                            "type": "string"
                          },
                          "state": {
                            "type": "object",
                            "properties": {
                              "active": {
                                "type": "boolean"
                              },
                              "last_reported": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                              }
                            }
                          },
                          "sensors": {
                            "type": "object",
                            "properties": {
                              "bat": {
                                "type": "number"
                              },
                              "rssi": {
                                "type": "integer"
                              },
                              "temp": {
                                "type": "integer"
                              }
                            }
                          },
                          "status": {
                            "type": "object",
                            "properties": {
                              "online": {
                                "type": "boolean"
                              },
                              "active": {
                                "type": "boolean"
                              },
                              "battery": {
                                "type": "number"
                              },
                              "rssi": {
                                "type": "integer"
                              },
                              "temperature": {
                                "type": "integer"
                              },
                              "action": {
                                "type": "string"
                              },
                              "updated_at": {
                                "type": "string",
                                "format": "date-time",
                                "nullable": true
                              }
                            }
                          },
                          "capabilities": {
                            "type": "object",
                            "properties": {
                              "open": {
                                "type": "string"
                              },
                              "close": {
                                "type": "string"
                              },
                              "toggle": {
                                "type": "string"
                              },
                              "led": {
                                "type": "string"
                              }
                            }
                          },
                          "actions": {
                            "type": "object",
                            "properties": {
                              "open": {
                                "type": "string"
                              },
                              "close": {
                                "type": "string"
                              },
                              "toggle": {
                                "type": "string"
                              },
                              "led": {
                                "type": "string"
                              }
                            }
                          },
                          "topic": {
                            "type": "string"
                          },
                          "custom": {
                            "nullable": true
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "current_page": {
                          "type": "integer"
                        },
                        "prev_page": {
                          "type": "boolean"
                        },
                        "next_page": {
                          "type": "integer"
                        },
                        "last_page": {
                          "type": "integer"
                        },
                        "from": {
                          "type": "integer"
                        },
                        "to": {
                          "type": "integer"
                        },
                        "per_page": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "first": {
                          "type": "string"
                        },
                        "last": {
                          "type": "string"
                        },
                        "next": {
                          "type": "string"
                        },
                        "prev": {
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "9fc3dab9-6d57-4b71-9038-28f3d0d73e02",
                      "ref_id": "01e3703zycjk9fmre5s45sc1yp",
                      "label": "Room 101",
                      "mac_address": "0x124b002422e23a",
                      "customer": {
                        "id": "b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c",
                        "ref_id": "01e31vwgfbfkcxfavhba7k682q",
                        "company": "Seaside Resorts"
                      },
                      "location": {
                        "id": "cf098ef1-bc66-4679-9da9-336ab5d1c561",
                        "ref_id": "01fkk63yt82hbs5h0gxjrexs43",
                        "name": "Grand Plaza Eindhoven"
                      },
                      "gateway": {
                        "id": "91cd4cf8-561b-4647-bae5-143167b586e7",
                        "label": "Room 312",
                        "ref_id": "01e36zxjget8jkmggpzemhdbw0",
                        "mac_address": "0x124b000d27b431"
                      },
                      "device_type": "lock",
                      "state": {
                        "active": true,
                        "last_reported": "2024-11-28 13:55:14"
                      },
                      "sensors": {
                        "bat": 5.5,
                        "rssi": -45,
                        "temp": 29
                      },
                      "status": {
                        "online": true,
                        "active": true,
                        "battery": 5.5,
                        "rssi": -45,
                        "temperature": 29,
                        "action": "close",
                        "updated_at": "2024-11-28 13:55:14"
                      },
                      "capabilities": {
                        "open": "c70a5a66-7a78-49cf-9dae-2881badc5cc8",
                        "close": "7733462c-a76e-4a38-9b37-6a7cb29a966e",
                        "toggle": "ac06b722-4683-4482-b642-c3f70c0bf162",
                        "led": "28e9d909-2ced-47ee-ae21-b71c9d8d6367"
                      },
                      "actions": {
                        "open": "/v1/actions/dv-01e3703zycjk9fmre5s45sc1yp-open-lock",
                        "close": "/v1/actions/dv-01e3703zycjk9fmre5s45sc1yp-close-lock",
                        "toggle": "/v1/actions/dv-01e3703zycjk9fmre5s45sc1yp-toggle-lock",
                        "led": "/v1/actions/dv-01e3703zycjk9fmre5s45sc1yp-toggle-led"
                      },
                      "topic": "0x124b000d27b431_0x124b002422e23a",
                      "custom": null
                    },
                    {
                      "id": "14f00a2e-74a0-455e-a58b-dc08d67c0b72",
                      "ref_id": "01ga6j1yp7rrs65ycsnr1ekaph",
                      "label": "Annex gateway",
                      "mac_address": "0x124b0024d7224e",
                      "customer": {
                        "id": "b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c",
                        "ref_id": "01e31vwgfbfkcxfavhba7k682q",
                        "company": "Seaside Resorts"
                      },
                      "location": {
                        "id": "cf098ef1-bc66-4679-9da9-336ab5d1c561",
                        "ref_id": "01fkk63yt82hbs5h0gxjrexs43",
                        "name": "Grand Plaza Eindhoven"
                      },
                      "gateway": {
                        "id": "91cd4cf8-561b-4647-bae5-143167b586e7",
                        "label": "Room 312",
                        "ref_id": "01e36zxjget8jkmggpzemhdbw0",
                        "mac_address": "0x124b000d27b431"
                      },
                      "device_type": "lock",
                      "state": {
                        "active": true,
                        "last_reported": "2024-11-28 13:54:55"
                      },
                      "sensors": {
                        "bat": 5.3,
                        "rssi": -59,
                        "temp": 22
                      },
                      "status": {
                        "online": true,
                        "active": true,
                        "battery": 5.3,
                        "rssi": -59,
                        "temperature": 22,
                        "action": "close",
                        "updated_at": "2024-11-28 13:54:55"
                      },
                      "capabilities": {
                        "open": "c70a5a66-7a78-49cf-9dae-2881badc5cc8",
                        "close": "7733462c-a76e-4a38-9b37-6a7cb29a966e",
                        "toggle": "ac06b722-4683-4482-b642-c3f70c0bf162",
                        "led": "28e9d909-2ced-47ee-ae21-b71c9d8d6367"
                      },
                      "actions": {
                        "open": "/v1/actions/dv-01ga6j1yp7rrs65ycsnr1ekaph-open-lock",
                        "close": "/v1/actions/dv-01ga6j1yp7rrs65ycsnr1ekaph-close-lock",
                        "toggle": "/v1/actions/dv-01ga6j1yp7rrs65ycsnr1ekaph-toggle-lock",
                        "led": "/v1/actions/dv-01ga6j1yp7rrs65ycsnr1ekaph-toggle-led"
                      },
                      "topic": "0x124b000d27b431_0x124b0024d7224e",
                      "custom": null
                    },
                    {
                      "id": "2c2821e1-0e05-3f00-84a5-92763e46494e",
                      "ref_id": "gj4xtsejf6mk9ycvwrspfkdz79",
                      "label": "Floor 2 gateway",
                      "mac_address": "0x124b00119dae46",
                      "customer": {
                        "id": "b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c",
                        "ref_id": "01e31vwgfbfkcxfavhba7k682q",
                        "company": "Seaside Resorts"
                      },
                      "location": {
                        "id": "cf098ef1-bc66-4679-9da9-336ab5d1c561",
                        "ref_id": "01fkk63yt82hbs5h0gxjrexs43",
                        "name": "Grand Plaza Eindhoven"
                      },
                      "gateway": {
                        "id": "91cd4cf8-561b-4647-bae5-143167b586e7",
                        "label": "Room 312",
                        "ref_id": "01e36zxjget8jkmggpzemhdbw0",
                        "mac_address": "0x124b000d27b431"
                      },
                      "device_type": "lock",
                      "state": {
                        "active": true,
                        "last_reported": null
                      },
                      "sensors": {
                        "bat": 0,
                        "rssi": 0,
                        "temp": 0
                      },
                      "status": {
                        "online": false,
                        "active": true,
                        "battery": 0,
                        "rssi": 0,
                        "temperature": 0,
                        "action": "",
                        "updated_at": null
                      },
                      "capabilities": {
                        "open": "c70a5a66-7a78-49cf-9dae-2881badc5cc8",
                        "close": "7733462c-a76e-4a38-9b37-6a7cb29a966e",
                        "toggle": "ac06b722-4683-4482-b642-c3f70c0bf162",
                        "led": "28e9d909-2ced-47ee-ae21-b71c9d8d6367"
                      },
                      "actions": {
                        "open": "/v1/actions/dv-gj4xtsejf6mk9ycvwrspfkdz79-open-lock",
                        "close": "/v1/actions/dv-gj4xtsejf6mk9ycvwrspfkdz79-close-lock",
                        "toggle": "/v1/actions/dv-gj4xtsejf6mk9ycvwrspfkdz79-toggle-lock",
                        "led": "/v1/actions/dv-gj4xtsejf6mk9ycvwrspfkdz79-toggle-led"
                      },
                      "topic": "0x124b000d27b431_0x124b00119dae46",
                      "custom": null
                    }
                  ],
                  "meta": {
                    "current_page": 1,
                    "prev_page": false,
                    "next_page": 2,
                    "last_page": 2,
                    "from": 1,
                    "to": 50,
                    "per_page": 50,
                    "limit": 50,
                    "total": 85
                  },
                  "links": {
                    "first": "v1/locations/cf098ef1-bc66-4679-9da9-336ab5d1c561/devices?page=1",
                    "last": "v1/locations/cf098ef1-bc66-4679-9da9-336ab5d1c561/devices?page=2",
                    "next": "v1/locations/cf098ef1-bc66-4679-9da9-336ab5d1c561/devices?page=2",
                    "prev": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      },
      "post": {
        "operationId": "post-v1-locations-location-devices",
        "tags": [
          "Locations"
        ],
        "summary": "Toggle a device on a location",
        "description": "Adds the device to the location's device list, or removes it when already listed. {location} is the location id or ref_id. Currently returns 500; a device takes the location of its gateway.",
        "parameters": [
          {
            "name": "location",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "device"
                ],
                "properties": {
                  "device": {
                    "type": "string",
                    "description": "Device to toggle (uuid or ref_id of an existing device).",
                    "x-rules": "required|new DeviceExists()"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationFailed"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/locations/{location}/gateways": {
      "get": {
        "operationId": "get-v1-locations-location-gateways",
        "tags": [
          "Locations"
        ],
        "summary": "List gateways of a location",
        "description": "Returns a page of the gateways at the location, sorted by label. {location} is the location id or ref_id.",
        "parameters": [
          {
            "name": "location",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "example": "cf098ef1-bc66-4679-9da9-336ab5d1c561"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1 to 50. Values outside the range are clamped. Default 50.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, starting at 1.",
            "schema": {
              "type": "integer"
            }
          },
          {
            "name": "search",
            "in": "query",
            "required": false,
            "description": "Search term, matched with LIKE against the searchable columns. No filtering when empty.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "search_key",
            "in": "query",
            "required": false,
            "description": "Column to search: label, mac_address or all. Default: label and mac_address.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "fuzzy",
            "in": "query",
            "required": false,
            "description": "Match mode for the term: start (term%), end (%term), fuzzy (characters in order, %t%e%s%t%). Any other value matches anywhere in the column (%term%). Default: match anywhere.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "1 returns only rows reported online by the Zabbix webhook, 0 returns the rest. A row without a status record counts as not online. No filtering when absent.",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "ref_id": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          },
                          "state": {
                            "type": "array",
                            "items": {}
                          },
                          "mac_address": {
                            "type": "string"
                          },
                          "customer": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "company": {
                                "type": "string"
                              }
                            }
                          },
                          "location": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              }
                            }
                          },
                          "device_type": {
                            "type": "string"
                          },
                          "actions": {
                            "type": "object",
                            "properties": {
                              "open": {
                                "type": "string"
                              },
                              "close": {
                                "type": "string"
                              }
                            }
                          },
                          "topic": {
                            "type": "string"
                          },
                          "status": {
                            "type": "object",
                            "properties": {
                              "online": {
                                "type": "boolean"
                              },
                              "battery": {
                                "type": "integer"
                              },
                              "rssi": {
                                "type": "integer"
                              },
                              "temperature": {
                                "type": "integer"
                              },
                              "action": {
                                "type": "string"
                              },
                              "updated_at": {
                                "type": "string",
                                "format": "date-time"
                              }
                            }
                          },
                          "monitoring": {
                            "type": "array",
                            "items": {}
                          },
                          "custom": {
                            "nullable": true
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "current_page": {
                          "type": "integer"
                        },
                        "prev_page": {
                          "type": "boolean"
                        },
                        "next_page": {
                          "type": "boolean"
                        },
                        "last_page": {
                          "type": "integer"
                        },
                        "from": {
                          "type": "integer"
                        },
                        "to": {
                          "type": "integer"
                        },
                        "per_page": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "first": {
                          "type": "string"
                        },
                        "last": {
                          "type": "string"
                        },
                        "next": {
                          "nullable": true
                        },
                        "prev": {
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "91cd4cf8-561b-4647-bae5-143167b586e7",
                      "ref_id": "01e36zxjget8jkmggpzemhdbw0",
                      "label": "Room 312",
                      "state": [],
                      "mac_address": "0x124b000d27b431",
                      "customer": {
                        "id": "b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c",
                        "ref_id": "01e31vwgfbfkcxfavhba7k682q",
                        "company": "Seaside Resorts"
                      },
                      "location": {
                        "id": "cf098ef1-bc66-4679-9da9-336ab5d1c561",
                        "ref_id": "01fkk63yt82hbs5h0gxjrexs43",
                        "name": "Grand Plaza Eindhoven"
                      },
                      "device_type": "gateway",
                      "actions": {
                        "open": "/v1/actions/gw-01e36zxjget8jkmggpzemhdbw0-open-gateway",
                        "close": "/v1/actions/gw-01e36zxjget8jkmggpzemhdbw0-close-gateway"
                      },
                      "topic": "0x124b000d27b431_network",
                      "status": {
                        "online": true,
                        "battery": 0,
                        "rssi": 0,
                        "temperature": 0,
                        "action": "close",
                        "updated_at": "2026-03-13 13:22:20"
                      },
                      "monitoring": [],
                      "custom": null
                    }
                  ],
                  "meta": {
                    "current_page": 1,
                    "prev_page": false,
                    "next_page": false,
                    "last_page": 1,
                    "from": 1,
                    "to": 1,
                    "per_page": 50,
                    "limit": 50,
                    "total": 1
                  },
                  "links": {
                    "first": "v1/locations/cf098ef1-bc66-4679-9da9-336ab5d1c561/gateways?page=1",
                    "last": "v1/locations/cf098ef1-bc66-4679-9da9-336ab5d1c561/gateways?page=1",
                    "next": null,
                    "prev": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      },
      "post": {
        "operationId": "post-v1-locations-location-gateways",
        "tags": [
          "Locations"
        ],
        "summary": "Toggle a gateway on a location",
        "description": "Adds the gateway to the location's gateway list, or removes it when already listed. {location} is the location id or ref_id. Currently returns 500; send location_id when creating or updating the gateway instead.",
        "parameters": [
          {
            "name": "location",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "gateway"
                ],
                "properties": {
                  "gateway": {
                    "type": "string",
                    "description": "Gateway to toggle (uuid or ref_id of an existing gateway).",
                    "x-rules": "required|new GatewayExists()"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "422": {
            "$ref": "#/components/responses/ValidationFailed"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/roles": {
      "get": {
        "operationId": "get-v1-roles",
        "tags": [
          "Roles"
        ],
        "summary": "List roles",
        "description": "Returns the roles (id, ref_id, name, number) up to the caller's own role.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "f5345aca-c221-4f3b-b083-c2aa5fa7b97a",
                      "name": "user"
                    },
                    {
                      "id": "1b59ee81-9e7b-47e0-b960-7afd581aa0ce",
                      "name": "admin"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/search": {
      "get": {
        "operationId": "get-v1-search",
        "tags": [
          "Search"
        ],
        "summary": "Search across resources",
        "description": "Searches devices and gateways (label, mac_address), locations (name), customers (company) and consumers (name, email, company) in one call and returns up to 5 matches for each.\n\nExamples:\n\n- `GET /v1/search?query=door1`\n- `GET /v1/search?query=Amsterdam`\n- `GET /v1/search?query=00:1A:2B`\n- `GET /v1/search?query=door&direction=desc`",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": false,
            "description": "Search term. Empty matches all. Example: `?query=door1`",
            "schema": {
              "type": "string"
            },
            "example": "door"
          },
          {
            "name": "direction",
            "in": "query",
            "required": false,
            "description": "Sort direction, `asc` or `desc`. Default `asc`. Example: `?query=door&direction=desc`",
            "schema": {
              "type": "string"
            },
            "example": "desc"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string"
                        }
                      }
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "devices": {
                          "type": "object",
                          "properties": {
                            "data": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string"
                                  },
                                  "ref_id": {
                                    "type": "string"
                                  },
                                  "label": {
                                    "type": "string"
                                  },
                                  "mac_address": {
                                    "type": "string"
                                  },
                                  "customer": {
                                    "type": "object",
                                    "properties": {
                                      "id": {
                                        "type": "string"
                                      },
                                      "ref_id": {
                                        "type": "string"
                                      },
                                      "company": {
                                        "type": "string"
                                      }
                                    }
                                  },
                                  "location": {
                                    "type": "object",
                                    "properties": {
                                      "id": {
                                        "type": "string"
                                      },
                                      "ref_id": {
                                        "type": "string"
                                      },
                                      "name": {
                                        "type": "string"
                                      }
                                    }
                                  },
                                  "gateway": {
                                    "type": "object",
                                    "properties": {
                                      "id": {
                                        "type": "string"
                                      },
                                      "label": {
                                        "type": "string"
                                      },
                                      "ref_id": {
                                        "type": "string"
                                      },
                                      "mac_address": {
                                        "type": "string"
                                      }
                                    }
                                  },
                                  "device_type": {
                                    "type": "string"
                                  },
                                  "state": {
                                    "type": "object",
                                    "properties": {
                                      "active": {
                                        "type": "boolean"
                                      },
                                      "last_reported": {
                                        "type": "string",
                                        "format": "date-time"
                                      }
                                    }
                                  },
                                  "sensors": {
                                    "type": "object",
                                    "properties": {
                                      "bat": {
                                        "type": "integer"
                                      },
                                      "rssi": {
                                        "type": "integer"
                                      },
                                      "temp": {
                                        "type": "integer"
                                      }
                                    }
                                  },
                                  "status": {
                                    "type": "object",
                                    "properties": {
                                      "online": {
                                        "type": "boolean"
                                      },
                                      "active": {
                                        "type": "boolean"
                                      },
                                      "battery": {
                                        "type": "integer"
                                      },
                                      "rssi": {
                                        "type": "integer"
                                      },
                                      "temperature": {
                                        "type": "integer"
                                      },
                                      "action": {
                                        "type": "string"
                                      },
                                      "updated_at": {
                                        "type": "string",
                                        "format": "date-time"
                                      }
                                    }
                                  },
                                  "capabilities": {
                                    "type": "object",
                                    "properties": {
                                      "open": {
                                        "type": "string"
                                      },
                                      "close": {
                                        "type": "string"
                                      },
                                      "toggle": {
                                        "type": "string"
                                      },
                                      "led": {
                                        "type": "string"
                                      }
                                    }
                                  },
                                  "actions": {
                                    "type": "object",
                                    "properties": {
                                      "open": {
                                        "type": "string"
                                      },
                                      "close": {
                                        "type": "string"
                                      },
                                      "toggle": {
                                        "type": "string"
                                      },
                                      "led": {
                                        "type": "string"
                                      }
                                    }
                                  },
                                  "topic": {
                                    "type": "string"
                                  },
                                  "custom": {
                                    "nullable": true
                                  }
                                }
                              }
                            },
                            "meta": {
                              "type": "object",
                              "properties": {
                                "current_page": {
                                  "type": "integer"
                                },
                                "prev_page": {
                                  "type": "boolean"
                                },
                                "next_page": {
                                  "type": "integer"
                                },
                                "last_page": {
                                  "type": "integer"
                                },
                                "from": {
                                  "type": "integer"
                                },
                                "to": {
                                  "type": "integer"
                                },
                                "per_page": {
                                  "type": "integer"
                                },
                                "limit": {
                                  "type": "integer"
                                },
                                "total": {
                                  "type": "integer"
                                }
                              }
                            },
                            "links": {
                              "type": "object",
                              "properties": {
                                "first": {
                                  "type": "string"
                                },
                                "last": {
                                  "type": "string"
                                },
                                "next": {
                                  "type": "string"
                                },
                                "prev": {
                                  "nullable": true
                                }
                              }
                            }
                          }
                        },
                        "gateways": {
                          "type": "object",
                          "properties": {
                            "data": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string"
                                  },
                                  "ref_id": {
                                    "type": "string"
                                  },
                                  "label": {
                                    "type": "string"
                                  },
                                  "state": {
                                    "type": "array",
                                    "items": {}
                                  },
                                  "mac_address": {
                                    "type": "string"
                                  },
                                  "customer": {
                                    "type": "object",
                                    "properties": {
                                      "id": {
                                        "type": "string"
                                      },
                                      "ref_id": {
                                        "type": "string"
                                      },
                                      "company": {
                                        "type": "string"
                                      }
                                    }
                                  },
                                  "location": {
                                    "type": "object",
                                    "properties": {
                                      "id": {
                                        "type": "string"
                                      },
                                      "ref_id": {
                                        "type": "string"
                                      },
                                      "name": {
                                        "type": "string"
                                      }
                                    }
                                  },
                                  "device_type": {
                                    "type": "string"
                                  },
                                  "actions": {
                                    "type": "object",
                                    "properties": {
                                      "open": {
                                        "type": "string"
                                      },
                                      "close": {
                                        "type": "string"
                                      }
                                    }
                                  },
                                  "topic": {
                                    "type": "string"
                                  },
                                  "status": {
                                    "type": "object",
                                    "properties": {
                                      "online": {
                                        "type": "boolean"
                                      },
                                      "battery": {
                                        "type": "integer"
                                      },
                                      "rssi": {
                                        "type": "integer"
                                      },
                                      "temperature": {
                                        "type": "integer"
                                      },
                                      "action": {
                                        "type": "string"
                                      },
                                      "updated_at": {
                                        "type": "string",
                                        "format": "date-time"
                                      }
                                    }
                                  },
                                  "monitoring": {
                                    "type": "array",
                                    "items": {}
                                  },
                                  "custom": {
                                    "nullable": true
                                  }
                                }
                              }
                            },
                            "meta": {
                              "type": "object",
                              "properties": {
                                "current_page": {
                                  "type": "integer"
                                },
                                "prev_page": {
                                  "type": "boolean"
                                },
                                "next_page": {
                                  "type": "integer"
                                },
                                "last_page": {
                                  "type": "integer"
                                },
                                "from": {
                                  "type": "integer"
                                },
                                "to": {
                                  "type": "integer"
                                },
                                "per_page": {
                                  "type": "integer"
                                },
                                "limit": {
                                  "type": "integer"
                                },
                                "total": {
                                  "type": "integer"
                                }
                              }
                            },
                            "links": {
                              "type": "object",
                              "properties": {
                                "first": {
                                  "type": "string"
                                },
                                "last": {
                                  "type": "string"
                                },
                                "next": {
                                  "type": "string"
                                },
                                "prev": {
                                  "nullable": true
                                }
                              }
                            }
                          }
                        },
                        "locations": {
                          "type": "object",
                          "properties": {
                            "data": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string"
                                  },
                                  "ref_id": {
                                    "type": "string"
                                  },
                                  "name": {
                                    "type": "string"
                                  },
                                  "reference": {
                                    "type": "string"
                                  },
                                  "customer": {
                                    "type": "object",
                                    "properties": {
                                      "id": {
                                        "type": "string"
                                      },
                                      "ref_id": {
                                        "nullable": true
                                      },
                                      "company": {
                                        "nullable": true
                                      }
                                    }
                                  }
                                }
                              }
                            },
                            "meta": {
                              "type": "object",
                              "properties": {
                                "current_page": {
                                  "type": "integer"
                                },
                                "prev_page": {
                                  "type": "boolean"
                                },
                                "next_page": {
                                  "type": "integer"
                                },
                                "last_page": {
                                  "type": "integer"
                                },
                                "from": {
                                  "type": "integer"
                                },
                                "to": {
                                  "type": "integer"
                                },
                                "per_page": {
                                  "type": "integer"
                                },
                                "limit": {
                                  "type": "integer"
                                },
                                "total": {
                                  "type": "integer"
                                }
                              }
                            },
                            "links": {
                              "type": "object",
                              "properties": {
                                "first": {
                                  "type": "string"
                                },
                                "last": {
                                  "type": "string"
                                },
                                "next": {
                                  "type": "string"
                                },
                                "prev": {
                                  "nullable": true
                                }
                              }
                            }
                          }
                        },
                        "customers": {
                          "type": "object",
                          "properties": {
                            "data": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string"
                                  },
                                  "ref_id": {
                                    "type": "string"
                                  },
                                  "reference": {
                                    "type": "string"
                                  },
                                  "company": {
                                    "type": "string"
                                  }
                                }
                              }
                            },
                            "meta": {
                              "type": "object",
                              "properties": {
                                "current_page": {
                                  "type": "integer"
                                },
                                "prev_page": {
                                  "type": "boolean"
                                },
                                "next_page": {
                                  "type": "integer"
                                },
                                "last_page": {
                                  "type": "integer"
                                },
                                "from": {
                                  "type": "integer"
                                },
                                "to": {
                                  "type": "integer"
                                },
                                "per_page": {
                                  "type": "integer"
                                },
                                "limit": {
                                  "type": "integer"
                                },
                                "total": {
                                  "type": "integer"
                                }
                              }
                            },
                            "links": {
                              "type": "object",
                              "properties": {
                                "first": {
                                  "type": "string"
                                },
                                "last": {
                                  "type": "string"
                                },
                                "next": {
                                  "type": "string"
                                },
                                "prev": {
                                  "nullable": true
                                }
                              }
                            }
                          }
                        },
                        "consumers": {
                          "type": "object",
                          "properties": {
                            "data": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "properties": {
                                  "id": {
                                    "type": "string"
                                  },
                                  "ref_id": {
                                    "type": "string"
                                  },
                                  "name": {
                                    "type": "string"
                                  },
                                  "email": {
                                    "type": "string"
                                  },
                                  "company": {
                                    "type": "string"
                                  },
                                  "role": {
                                    "type": "string"
                                  }
                                }
                              }
                            },
                            "meta": {
                              "type": "object",
                              "properties": {
                                "current_page": {
                                  "type": "integer"
                                },
                                "prev_page": {
                                  "type": "boolean"
                                },
                                "next_page": {
                                  "type": "integer"
                                },
                                "last_page": {
                                  "type": "integer"
                                },
                                "from": {
                                  "type": "integer"
                                },
                                "to": {
                                  "type": "integer"
                                },
                                "per_page": {
                                  "type": "integer"
                                },
                                "limit": {
                                  "type": "integer"
                                },
                                "total": {
                                  "type": "integer"
                                }
                              }
                            },
                            "links": {
                              "type": "object",
                              "properties": {
                                "first": {
                                  "type": "string"
                                },
                                "last": {
                                  "type": "string"
                                },
                                "next": {
                                  "type": "string"
                                },
                                "prev": {
                                  "nullable": true
                                }
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "example": {
                  "links": {
                    "self": "/v1/search"
                  },
                  "data": {
                    "devices": {
                      "data": [
                        {
                          "id": "65fcb74b-92d9-40c6-8732-b30b9afa2488",
                          "ref_id": "01hzpjvzgjxm2qkwd9bw7dhc5h",
                          "label": "Staff entrance",
                          "mac_address": "asrfadf4",
                          "customer": {
                            "id": "eb88e4e7-c451-4112-9bb1-2124a0f5b48e",
                            "ref_id": "01hyfvr34329jb8gw1rft7sea7",
                            "company": "Keyless Labs"
                          },
                          "location": {
                            "id": "79fad71c-c6a8-41c0-b1cd-b579b11371df",
                            "ref_id": "01hyfvrp008ept70kak8ss9r5z",
                            "name": "Riverside Maastricht"
                          },
                          "gateway": {
                            "id": "83b30351-a4e0-46f0-af8b-0b054aecb7f5",
                            "label": "Lobby entrance",
                            "ref_id": "01hyfvsdpe1srnrtqdnbt45rm3",
                            "mac_address": "0x0123456789"
                          },
                          "device_type": "lock",
                          "state": {
                            "active": true,
                            "last_reported": "2024-06-06 10:38:48"
                          },
                          "sensors": {
                            "bat": 0,
                            "rssi": 0,
                            "temp": 0
                          },
                          "status": {
                            "online": true,
                            "active": true,
                            "battery": 0,
                            "rssi": 0,
                            "temperature": 0,
                            "action": "close",
                            "updated_at": "2024-06-06 10:38:48"
                          },
                          "capabilities": {
                            "open": "c70a5a66-7a78-49cf-9dae-2881badc5cc8",
                            "close": "7733462c-a76e-4a38-9b37-6a7cb29a966e",
                            "toggle": "ac06b722-4683-4482-b642-c3f70c0bf162",
                            "led": "28e9d909-2ced-47ee-ae21-b71c9d8d6367"
                          },
                          "actions": {
                            "open": "/v1/actions/dv-01hzpjvzgjxm2qkwd9bw7dhc5h-open-lock",
                            "close": "/v1/actions/dv-01hzpjvzgjxm2qkwd9bw7dhc5h-close-lock",
                            "toggle": "/v1/actions/dv-01hzpjvzgjxm2qkwd9bw7dhc5h-toggle-lock",
                            "led": "/v1/actions/dv-01hzpjvzgjxm2qkwd9bw7dhc5h-toggle-led"
                          },
                          "topic": "0x0123456789_asrfadf4",
                          "custom": null
                        },
                        {
                          "id": "aca19e7d-1ba4-4405-ab9f-065690a06ae3",
                          "ref_id": "01hzpk0fc10wbc6jdxh61q880t",
                          "label": "Bungalow 12",
                          "mac_address": "4565df4s6d54fs6d5f4",
                          "customer": {
                            "id": "eb88e4e7-c451-4112-9bb1-2124a0f5b48e",
                            "ref_id": "01hyfvr34329jb8gw1rft7sea7",
                            "company": "Keyless Labs"
                          },
                          "location": {
                            "id": "79fad71c-c6a8-41c0-b1cd-b579b11371df",
                            "ref_id": "01hyfvrp008ept70kak8ss9r5z",
                            "name": "Riverside Maastricht"
                          },
                          "gateway": {
                            "id": "83b30351-a4e0-46f0-af8b-0b054aecb7f5",
                            "label": "Lobby entrance",
                            "ref_id": "01hyfvsdpe1srnrtqdnbt45rm3",
                            "mac_address": "0x0123456789"
                          },
                          "device_type": "lock",
                          "state": {
                            "active": true,
                            "last_reported": "2024-06-06 10:40:53"
                          },
                          "sensors": {
                            "bat": 0,
                            "rssi": 0,
                            "temp": 0
                          },
                          "status": {
                            "online": true,
                            "active": true,
                            "battery": 0,
                            "rssi": 0,
                            "temperature": 0,
                            "action": "close",
                            "updated_at": "2024-06-06 10:40:53"
                          },
                          "capabilities": {
                            "open": "c70a5a66-7a78-49cf-9dae-2881badc5cc8",
                            "close": "7733462c-a76e-4a38-9b37-6a7cb29a966e",
                            "toggle": "ac06b722-4683-4482-b642-c3f70c0bf162",
                            "led": "28e9d909-2ced-47ee-ae21-b71c9d8d6367"
                          },
                          "actions": {
                            "open": "/v1/actions/dv-01hzpk0fc10wbc6jdxh61q880t-open-lock",
                            "close": "/v1/actions/dv-01hzpk0fc10wbc6jdxh61q880t-close-lock",
                            "toggle": "/v1/actions/dv-01hzpk0fc10wbc6jdxh61q880t-toggle-lock",
                            "led": "/v1/actions/dv-01hzpk0fc10wbc6jdxh61q880t-toggle-led"
                          },
                          "topic": "0x0123456789_4565df4s6d54fs6d5f4",
                          "custom": null
                        },
                        {
                          "id": "2217a217-dd84-400d-9f4a-90ff02fc5ff3",
                          "ref_id": "01k6d7v7p1r2v1rg0ygteky06p",
                          "label": "Suite 401",
                          "mac_address": "0x12499920",
                          "customer": {
                            "id": "41f9b289-f3a0-4e8f-8f8a-b0bdf43e0e88",
                            "ref_id": "01k6d7sz6zzaj4e4hrdzjz7s85",
                            "company": "Brightdoor Systems"
                          },
                          "location": {
                            "id": "ffc8aa72-a7c9-4347-9908-5bb9de1a6f8d",
                            "ref_id": "01k6d7tn2dhvszt89hjme18pn8",
                            "name": "Riverside Maastricht"
                          },
                          "gateway": {
                            "id": "78ebf3df-a5f4-43da-ab2e-aa3f5f3f072a",
                            "label": "Bungalow 14",
                            "ref_id": "01k6d7twqsbyx2w2x21r3pfhqt",
                            "mac_address": "0s124d"
                          },
                          "device_type": "lock",
                          "state": {
                            "active": true,
                            "last_reported": "2025-09-30 11:45:29"
                          },
                          "sensors": {
                            "bat": 0,
                            "rssi": 0,
                            "temp": 0
                          },
                          "status": {
                            "online": false,
                            "active": true,
                            "battery": 0,
                            "rssi": 0,
                            "temperature": 0,
                            "action": "close",
                            "updated_at": "2025-09-30 11:45:29"
                          },
                          "capabilities": {
                            "open": "c70a5a66-7a78-49cf-9dae-2881badc5cc8",
                            "close": "7733462c-a76e-4a38-9b37-6a7cb29a966e",
                            "toggle": "ac06b722-4683-4482-b642-c3f70c0bf162",
                            "led": "28e9d909-2ced-47ee-ae21-b71c9d8d6367"
                          },
                          "actions": {
                            "open": "/v1/actions/dv-01k6d7v7p1r2v1rg0ygteky06p-open-lock",
                            "close": "/v1/actions/dv-01k6d7v7p1r2v1rg0ygteky06p-close-lock",
                            "toggle": "/v1/actions/dv-01k6d7v7p1r2v1rg0ygteky06p-toggle-lock",
                            "led": "/v1/actions/dv-01k6d7v7p1r2v1rg0ygteky06p-toggle-led"
                          },
                          "topic": "0s124d_0x12499920",
                          "custom": null
                        }
                      ],
                      "meta": {
                        "current_page": 1,
                        "prev_page": false,
                        "next_page": 2,
                        "last_page": 424,
                        "from": 1,
                        "to": 5,
                        "per_page": 50,
                        "limit": 50,
                        "total": 2117
                      },
                      "links": {
                        "first": "v1/search?page=1",
                        "last": "v1/search?page=424",
                        "next": "v1/search?page=2",
                        "prev": null
                      }
                    },
                    "gateways": {
                      "data": [
                        {
                          "id": "2daf7361-fa52-4ce0-ae0b-e417558b69ff",
                          "ref_id": "01jvvhhxpzy14nres1bxbct9a3",
                          "label": "Suite 401",
                          "state": [],
                          "mac_address": "0x123",
                          "customer": {
                            "id": "daf62a38-5a89-4944-b01f-7b6cc9e88f77",
                            "ref_id": "01eg1v6h2qt17etgwe17jd3fbh",
                            "company": "Polder Parks"
                          },
                          "location": {
                            "id": "bd7838dc-7368-4317-89e0-2272f8d9f068",
                            "ref_id": "01fkk6424dnmwq7egj0hy7varf",
                            "name": "Meadow Lodge Veluwe"
                          },
                          "device_type": "gateway",
                          "actions": {
                            "open": "/v1/actions/gw-01jvvhhxpzy14nres1bxbct9a3-open-gateway",
                            "close": "/v1/actions/gw-01jvvhhxpzy14nres1bxbct9a3-close-gateway"
                          },
                          "topic": "0x123_network",
                          "status": {
                            "online": true,
                            "battery": 0,
                            "rssi": 0,
                            "temperature": 0,
                            "action": "close",
                            "updated_at": "2025-05-22 07:31:40"
                          },
                          "monitoring": [],
                          "custom": null
                        },
                        {
                          "id": "9ad2b747-5a37-4131-8ea8-e7b6a8824ff0",
                          "ref_id": "01gvz1g7y6ypsw755hvyrma6af",
                          "label": "Spa door",
                          "state": [],
                          "mac_address": "0x01234567890",
                          "customer": {
                            "id": "d8548e65-6f2e-4a68-bea8-297a13a98131",
                            "ref_id": "01gvz1e90q1f8dnheadzv4pbxm",
                            "company": "Linden Hotels"
                          },
                          "location": {
                            "id": "4060486d-15f0-47d8-9b7a-a37d9466360b",
                            "ref_id": "01gvz1f6n7zt9fgzz2230pjw6t",
                            "name": "Meadow Lodge Veluwe"
                          },
                          "device_type": "gateway",
                          "actions": {
                            "open": "/v1/actions/gw-01gvz1g7y6ypsw755hvyrma6af-open-gateway",
                            "close": "/v1/actions/gw-01gvz1g7y6ypsw755hvyrma6af-close-gateway"
                          },
                          "topic": "0x01234567890_network",
                          "status": {
                            "online": true,
                            "battery": 0,
                            "rssi": 0,
                            "temperature": 0,
                            "action": "close",
                            "updated_at": "2023-03-20 07:22:45"
                          },
                          "monitoring": [],
                          "custom": null
                        },
                        {
                          "id": "d5be484e-f107-4251-85b2-6095a16679a4",
                          "ref_id": "01ghxvz56e8sb3bad09wbvhm9w",
                          "label": "Room 103",
                          "state": [],
                          "mac_address": "0x124b0026e85852",
                          "customer": {
                            "id": "daf62a38-5a89-4944-b01f-7b6cc9e88f77",
                            "ref_id": "01eg1v6h2qt17etgwe17jd3fbh",
                            "company": "Polder Parks"
                          },
                          "location": {
                            "id": "bd7838dc-7368-4317-89e0-2272f8d9f068",
                            "ref_id": "01fkk6424dnmwq7egj0hy7varf",
                            "name": "Meadow Lodge Veluwe"
                          },
                          "device_type": "gateway",
                          "actions": {
                            "open": "/v1/actions/gw-01ghxvz56e8sb3bad09wbvhm9w-open-gateway",
                            "close": "/v1/actions/gw-01ghxvz56e8sb3bad09wbvhm9w-close-gateway"
                          },
                          "topic": "0x124b0026e85852_network",
                          "status": {
                            "online": true,
                            "battery": 0,
                            "rssi": 0,
                            "temperature": 0,
                            "action": "close",
                            "updated_at": "2023-10-06 08:31:03"
                          },
                          "monitoring": [],
                          "custom": null
                        }
                      ],
                      "meta": {
                        "current_page": 1,
                        "prev_page": false,
                        "next_page": 2,
                        "last_page": 6,
                        "from": 1,
                        "to": 5,
                        "per_page": 50,
                        "limit": 50,
                        "total": 28
                      },
                      "links": {
                        "first": "v1/search?page=1",
                        "last": "v1/search?page=6",
                        "next": "v1/search?page=2",
                        "prev": null
                      }
                    },
                    "locations": {
                      "data": [
                        {
                          "id": "cf098ef1-bc66-4679-9da9-336ab5d1c561",
                          "ref_id": "01fkk63yt82hbs5h0gxjrexs43",
                          "name": "Grand Plaza Eindhoven",
                          "reference": "c2odemo89",
                          "customer": {
                            "id": "b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c",
                            "ref_id": null,
                            "company": null
                          }
                        },
                        {
                          "id": "ffc8aa72-a7c9-4347-9908-5bb9de1a6f8d",
                          "ref_id": "01k6d7tn2dhvszt89hjme18pn8",
                          "name": "Riverside Maastricht",
                          "reference": "12",
                          "customer": {
                            "id": "41f9b289-f3a0-4e8f-8f8a-b0bdf43e0e88",
                            "ref_id": null,
                            "company": null
                          }
                        },
                        {
                          "id": "701d919c-75ff-4912-8ae0-fdea75432669",
                          "ref_id": "01k94q63a6cj9shdm5yrdg66rx",
                          "name": "Northwind Rotterdam",
                          "reference": "134555",
                          "customer": {
                            "id": "8422ab96-d903-49ef-a7da-103eec7bd256",
                            "ref_id": null,
                            "company": null
                          }
                        }
                      ],
                      "meta": {
                        "current_page": 1,
                        "prev_page": false,
                        "next_page": 2,
                        "last_page": 5,
                        "from": 1,
                        "to": 5,
                        "per_page": 50,
                        "limit": 50,
                        "total": 22
                      },
                      "links": {
                        "first": "v1/search?page=1",
                        "last": "v1/search?page=5",
                        "next": "v1/search?page=2",
                        "prev": null
                      }
                    },
                    "customers": {
                      "data": [
                        {
                          "id": "b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c",
                          "ref_id": "01e31vwgfbfkcxfavhba7k682q",
                          "reference": "18996",
                          "company": "Seaside Resorts"
                        },
                        {
                          "id": "41f9b289-f3a0-4e8f-8f8a-b0bdf43e0e88",
                          "ref_id": "01k6d7sz6zzaj4e4hrdzjz7s85",
                          "reference": "0124",
                          "company": "Brightdoor Systems"
                        },
                        {
                          "id": "8422ab96-d903-49ef-a7da-103eec7bd256",
                          "ref_id": "01k94q5rzc3kqwmt5rh9secqck",
                          "reference": "12334",
                          "company": "Northwind Stays"
                        }
                      ],
                      "meta": {
                        "current_page": 1,
                        "prev_page": false,
                        "next_page": 2,
                        "last_page": 5,
                        "from": 1,
                        "to": 5,
                        "per_page": 50,
                        "limit": 50,
                        "total": 22
                      },
                      "links": {
                        "first": "v1/search?page=1",
                        "last": "v1/search?page=5",
                        "next": "v1/search?page=2",
                        "prev": null
                      }
                    },
                    "consumers": {
                      "data": [
                        {
                          "id": "01jsxhfkskntbhpxgdw1jbfn8b",
                          "ref_id": "01jsxhfkskntbhpxgdw1jbfn8b",
                          "name": "Sophie Bakker",
                          "email": "sophie.bakker@example.com",
                          "company": "Northwind Stays",
                          "role": "user"
                        },
                        {
                          "id": "01f7v1h2q2a5ckqj35ryksy7wj",
                          "ref_id": "01f7v1h2q2a5ckqj35ryksy7wj",
                          "name": "Max de Haan",
                          "email": "max.de.haan@example.com",
                          "company": "Tulip Inn Collective",
                          "role": "user"
                        },
                        {
                          "id": "01k94prsjstgkhqxedvc08pb8y",
                          "ref_id": "01k94prsjstgkhqxedvc08pb8y",
                          "name": "Liam Jansen",
                          "email": "liam.jansen@example.com",
                          "company": "Meadow Lodges",
                          "role": "user"
                        }
                      ],
                      "meta": {
                        "current_page": 1,
                        "prev_page": false,
                        "next_page": 2,
                        "last_page": 11,
                        "from": 1,
                        "to": 5,
                        "per_page": 50,
                        "limit": 50,
                        "total": 55
                      },
                      "links": {
                        "first": "v1/search?page=1",
                        "last": "v1/search?page=11",
                        "next": "v1/search?page=2",
                        "prev": null
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/search/consumers": {
      "get": {
        "operationId": "get-v1-search-consumers",
        "tags": [
          "Search"
        ],
        "summary": "Search consumers",
        "description": "Returns a page of consumers whose name or company matches, sorted by company.",
        "parameters": [
          {
            "name": "role",
            "in": "query",
            "required": false,
            "description": "Only consumers with this role. Example: `?role=user`",
            "schema": {
              "type": "string"
            },
            "example": "user"
          },
          {
            "name": "query",
            "in": "query",
            "required": false,
            "description": "Search term, matched in name and company. Empty matches all. Example: `?query=smith`",
            "schema": {
              "type": "string"
            },
            "example": "sm"
          },
          {
            "name": "fuzzy",
            "in": "query",
            "required": false,
            "description": "`fuzzy` matches the characters of the term in this order. Default: the term anywhere. Example: `?query=sm&fuzzy=fuzzy`",
            "schema": {
              "type": "string"
            },
            "example": "fuzzy"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1 to 50. Default 50. Example: `?limit=10`",
            "schema": {
              "type": "integer"
            },
            "example": 10
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, starting at 1. Example: `?limit=10&page=2`",
            "schema": {
              "type": "integer"
            },
            "example": 2
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "ref_id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "email": {
                            "type": "string"
                          },
                          "company": {
                            "type": "string"
                          },
                          "role": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "current_page": {
                          "type": "integer"
                        },
                        "prev_page": {
                          "type": "boolean"
                        },
                        "next_page": {
                          "type": "integer"
                        },
                        "last_page": {
                          "type": "integer"
                        },
                        "from": {
                          "type": "integer"
                        },
                        "to": {
                          "type": "integer"
                        },
                        "per_page": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "first": {
                          "type": "string"
                        },
                        "last": {
                          "type": "string"
                        },
                        "next": {
                          "type": "string"
                        },
                        "prev": {
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "01evxyxnqvj21md8w4mgeew5bd",
                      "ref_id": "01evxyxnqvj21md8w4mgeew5bd",
                      "name": "Daan Meijer",
                      "email": "daan.meijer@example.com",
                      "company": "Canal House Group",
                      "role": "user"
                    },
                    {
                      "id": "01hbqzvf6h7qnpmbffjh2tbqa3",
                      "ref_id": "01hbqzvf6h7qnpmbffjh2tbqa3",
                      "name": "Finn Bos",
                      "email": "finn.bos@example.com",
                      "company": "Urban Nest Hotels",
                      "role": "admin"
                    },
                    {
                      "id": "01k5b2w7dnde9xdah5kf0y9989",
                      "ref_id": "01k5b2w7dnde9xdah5kf0y9989",
                      "name": "Sem Mulder",
                      "email": "sem.mulder@example.com",
                      "company": "Polder Parks",
                      "role": "user"
                    }
                  ],
                  "meta": {
                    "current_page": 1,
                    "prev_page": false,
                    "next_page": 2,
                    "last_page": 2,
                    "from": 1,
                    "to": 50,
                    "per_page": 50,
                    "limit": 50,
                    "total": 55
                  },
                  "links": {
                    "first": "v1/search/consumers?page=1",
                    "last": "v1/search/consumers?page=2",
                    "next": "v1/search/consumers?page=2",
                    "prev": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/search/customers": {
      "get": {
        "operationId": "get-v1-search-customers",
        "tags": [
          "Search"
        ],
        "summary": "Search customers",
        "description": "Returns a page of customers whose company matches, sorted by company.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": false,
            "description": "Search term, matched in company. Empty matches all. Example: `?query=north`",
            "schema": {
              "type": "string"
            },
            "example": "north"
          },
          {
            "name": "fuzzy",
            "in": "query",
            "required": false,
            "description": "`fuzzy` matches the characters of the term in this order. Default: the term anywhere. Example: `?query=nrth&fuzzy=fuzzy`",
            "schema": {
              "type": "string"
            },
            "example": "fuzzy"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1 to 50. Default 50. Example: `?limit=10`",
            "schema": {
              "type": "integer"
            },
            "example": 10
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, starting at 1. Example: `?limit=10&page=2`",
            "schema": {
              "type": "integer"
            },
            "example": 2
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "ref_id": {
                            "type": "string"
                          },
                          "reference": {
                            "type": "string"
                          },
                          "company": {
                            "type": "string"
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "current_page": {
                          "type": "integer"
                        },
                        "prev_page": {
                          "type": "boolean"
                        },
                        "next_page": {
                          "type": "boolean"
                        },
                        "last_page": {
                          "type": "integer"
                        },
                        "from": {
                          "type": "integer"
                        },
                        "to": {
                          "type": "integer"
                        },
                        "per_page": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "first": {
                          "type": "string"
                        },
                        "last": {
                          "type": "string"
                        },
                        "next": {
                          "nullable": true
                        },
                        "prev": {
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c",
                      "ref_id": "01e31vwgfbfkcxfavhba7k682q",
                      "reference": "18996",
                      "company": "Seaside Resorts"
                    },
                    {
                      "id": "41f9b289-f3a0-4e8f-8f8a-b0bdf43e0e88",
                      "ref_id": "01k6d7sz6zzaj4e4hrdzjz7s85",
                      "reference": "0124",
                      "company": "Brightdoor Systems"
                    },
                    {
                      "id": "8422ab96-d903-49ef-a7da-103eec7bd256",
                      "ref_id": "01k94q5rzc3kqwmt5rh9secqck",
                      "reference": "12334",
                      "company": "Northwind Stays"
                    }
                  ],
                  "meta": {
                    "current_page": 1,
                    "prev_page": false,
                    "next_page": false,
                    "last_page": 1,
                    "from": 1,
                    "to": 22,
                    "per_page": 50,
                    "limit": 50,
                    "total": 22
                  },
                  "links": {
                    "first": "v1/search/customers?page=1",
                    "last": "v1/search/customers?page=1",
                    "next": null,
                    "prev": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/search/devices": {
      "get": {
        "operationId": "get-v1-search-devices",
        "tags": [
          "Search"
        ],
        "summary": "Search devices",
        "description": "Returns devices whose label or mac_address matches, sorted by label, 20 per page (limit is ignored).",
        "parameters": [
          {
            "name": "gateway",
            "in": "query",
            "required": false,
            "description": "Only devices of this gateway, by gateway id. Example: `?gateway={gateway id}&query=door`",
            "schema": {
              "type": "string"
            },
            "example": "6e304d0b-4313-466e-bd0d-7bd48be97df9"
          },
          {
            "name": "query",
            "in": "query",
            "required": false,
            "description": "Search term, matched in label and mac_address. Empty matches all. Example: `?query=door1`",
            "schema": {
              "type": "string"
            },
            "example": "door"
          },
          {
            "name": "fuzzy",
            "in": "query",
            "required": false,
            "description": "`fuzzy` matches the characters of the term in this order. Default: the term anywhere. Example: `?query=dr1&fuzzy=fuzzy`",
            "schema": {
              "type": "string"
            },
            "example": "fuzzy"
          },
          {
            "name": "direction",
            "in": "query",
            "required": false,
            "description": "Sort direction, `asc` or `desc`. Default `asc`. Example: `?query=door&direction=desc`",
            "schema": {
              "type": "string"
            },
            "example": "desc"
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, starting at 1; 20 devices per page. Example: `?query=door&page=2`",
            "schema": {
              "type": "integer"
            },
            "example": 2
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "ref_id": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          },
                          "mac_address": {
                            "type": "string"
                          },
                          "customer": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "company": {
                                "type": "string"
                              }
                            }
                          },
                          "location": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              }
                            }
                          },
                          "gateway": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "label": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "mac_address": {
                                "type": "string"
                              }
                            }
                          },
                          "device_type": {
                            "type": "string"
                          },
                          "state": {
                            "type": "object",
                            "properties": {
                              "active": {
                                "type": "boolean"
                              },
                              "last_reported": {
                                "type": "string",
                                "format": "date-time"
                              }
                            }
                          },
                          "sensors": {
                            "type": "object",
                            "properties": {
                              "bat": {
                                "type": "integer"
                              },
                              "rssi": {
                                "type": "integer"
                              },
                              "temp": {
                                "type": "integer"
                              }
                            }
                          },
                          "status": {
                            "type": "object",
                            "properties": {
                              "online": {
                                "type": "boolean"
                              },
                              "active": {
                                "type": "boolean"
                              },
                              "battery": {
                                "type": "integer"
                              },
                              "rssi": {
                                "type": "integer"
                              },
                              "temperature": {
                                "type": "integer"
                              },
                              "action": {
                                "type": "string"
                              },
                              "updated_at": {
                                "type": "string",
                                "format": "date-time"
                              }
                            }
                          },
                          "capabilities": {
                            "type": "object",
                            "properties": {
                              "open": {
                                "type": "string"
                              },
                              "close": {
                                "type": "string"
                              },
                              "toggle": {
                                "type": "string"
                              },
                              "led": {
                                "type": "string"
                              }
                            }
                          },
                          "actions": {
                            "type": "object",
                            "properties": {
                              "open": {
                                "type": "string"
                              },
                              "close": {
                                "type": "string"
                              },
                              "toggle": {
                                "type": "string"
                              },
                              "led": {
                                "type": "string"
                              }
                            }
                          },
                          "topic": {
                            "type": "string"
                          },
                          "custom": {
                            "nullable": true
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "current_page": {
                          "type": "integer"
                        },
                        "prev_page": {
                          "type": "boolean"
                        },
                        "next_page": {
                          "type": "integer"
                        },
                        "last_page": {
                          "type": "integer"
                        },
                        "from": {
                          "type": "integer"
                        },
                        "to": {
                          "type": "integer"
                        },
                        "per_page": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "first": {
                          "type": "string"
                        },
                        "last": {
                          "type": "string"
                        },
                        "next": {
                          "type": "string"
                        },
                        "prev": {
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "65fcb74b-92d9-40c6-8732-b30b9afa2488",
                      "ref_id": "01hzpjvzgjxm2qkwd9bw7dhc5h",
                      "label": "Staff entrance",
                      "mac_address": "asrfadf4",
                      "customer": {
                        "id": "eb88e4e7-c451-4112-9bb1-2124a0f5b48e",
                        "ref_id": "01hyfvr34329jb8gw1rft7sea7",
                        "company": "Keyless Labs"
                      },
                      "location": {
                        "id": "79fad71c-c6a8-41c0-b1cd-b579b11371df",
                        "ref_id": "01hyfvrp008ept70kak8ss9r5z",
                        "name": "Riverside Maastricht"
                      },
                      "gateway": {
                        "id": "83b30351-a4e0-46f0-af8b-0b054aecb7f5",
                        "label": "Lobby entrance",
                        "ref_id": "01hyfvsdpe1srnrtqdnbt45rm3",
                        "mac_address": "0x0123456789"
                      },
                      "device_type": "lock",
                      "state": {
                        "active": true,
                        "last_reported": "2024-06-06 10:38:48"
                      },
                      "sensors": {
                        "bat": 0,
                        "rssi": 0,
                        "temp": 0
                      },
                      "status": {
                        "online": true,
                        "active": true,
                        "battery": 0,
                        "rssi": 0,
                        "temperature": 0,
                        "action": "close",
                        "updated_at": "2024-06-06 10:38:48"
                      },
                      "capabilities": {
                        "open": "c70a5a66-7a78-49cf-9dae-2881badc5cc8",
                        "close": "7733462c-a76e-4a38-9b37-6a7cb29a966e",
                        "toggle": "ac06b722-4683-4482-b642-c3f70c0bf162",
                        "led": "28e9d909-2ced-47ee-ae21-b71c9d8d6367"
                      },
                      "actions": {
                        "open": "/v1/actions/dv-01hzpjvzgjxm2qkwd9bw7dhc5h-open-lock",
                        "close": "/v1/actions/dv-01hzpjvzgjxm2qkwd9bw7dhc5h-close-lock",
                        "toggle": "/v1/actions/dv-01hzpjvzgjxm2qkwd9bw7dhc5h-toggle-lock",
                        "led": "/v1/actions/dv-01hzpjvzgjxm2qkwd9bw7dhc5h-toggle-led"
                      },
                      "topic": "0x0123456789_asrfadf4",
                      "custom": null
                    },
                    {
                      "id": "aca19e7d-1ba4-4405-ab9f-065690a06ae3",
                      "ref_id": "01hzpk0fc10wbc6jdxh61q880t",
                      "label": "Bungalow 12",
                      "mac_address": "4565df4s6d54fs6d5f4",
                      "customer": {
                        "id": "eb88e4e7-c451-4112-9bb1-2124a0f5b48e",
                        "ref_id": "01hyfvr34329jb8gw1rft7sea7",
                        "company": "Keyless Labs"
                      },
                      "location": {
                        "id": "79fad71c-c6a8-41c0-b1cd-b579b11371df",
                        "ref_id": "01hyfvrp008ept70kak8ss9r5z",
                        "name": "Riverside Maastricht"
                      },
                      "gateway": {
                        "id": "83b30351-a4e0-46f0-af8b-0b054aecb7f5",
                        "label": "Lobby entrance",
                        "ref_id": "01hyfvsdpe1srnrtqdnbt45rm3",
                        "mac_address": "0x0123456789"
                      },
                      "device_type": "lock",
                      "state": {
                        "active": true,
                        "last_reported": "2024-06-06 10:40:53"
                      },
                      "sensors": {
                        "bat": 0,
                        "rssi": 0,
                        "temp": 0
                      },
                      "status": {
                        "online": true,
                        "active": true,
                        "battery": 0,
                        "rssi": 0,
                        "temperature": 0,
                        "action": "close",
                        "updated_at": "2024-06-06 10:40:53"
                      },
                      "capabilities": {
                        "open": "c70a5a66-7a78-49cf-9dae-2881badc5cc8",
                        "close": "7733462c-a76e-4a38-9b37-6a7cb29a966e",
                        "toggle": "ac06b722-4683-4482-b642-c3f70c0bf162",
                        "led": "28e9d909-2ced-47ee-ae21-b71c9d8d6367"
                      },
                      "actions": {
                        "open": "/v1/actions/dv-01hzpk0fc10wbc6jdxh61q880t-open-lock",
                        "close": "/v1/actions/dv-01hzpk0fc10wbc6jdxh61q880t-close-lock",
                        "toggle": "/v1/actions/dv-01hzpk0fc10wbc6jdxh61q880t-toggle-lock",
                        "led": "/v1/actions/dv-01hzpk0fc10wbc6jdxh61q880t-toggle-led"
                      },
                      "topic": "0x0123456789_4565df4s6d54fs6d5f4",
                      "custom": null
                    },
                    {
                      "id": "2217a217-dd84-400d-9f4a-90ff02fc5ff3",
                      "ref_id": "01k6d7v7p1r2v1rg0ygteky06p",
                      "label": "Suite 401",
                      "mac_address": "0x12499920",
                      "customer": {
                        "id": "41f9b289-f3a0-4e8f-8f8a-b0bdf43e0e88",
                        "ref_id": "01k6d7sz6zzaj4e4hrdzjz7s85",
                        "company": "Brightdoor Systems"
                      },
                      "location": {
                        "id": "ffc8aa72-a7c9-4347-9908-5bb9de1a6f8d",
                        "ref_id": "01k6d7tn2dhvszt89hjme18pn8",
                        "name": "Riverside Maastricht"
                      },
                      "gateway": {
                        "id": "78ebf3df-a5f4-43da-ab2e-aa3f5f3f072a",
                        "label": "Bungalow 14",
                        "ref_id": "01k6d7twqsbyx2w2x21r3pfhqt",
                        "mac_address": "0s124d"
                      },
                      "device_type": "lock",
                      "state": {
                        "active": true,
                        "last_reported": "2025-09-30 11:45:29"
                      },
                      "sensors": {
                        "bat": 0,
                        "rssi": 0,
                        "temp": 0
                      },
                      "status": {
                        "online": false,
                        "active": true,
                        "battery": 0,
                        "rssi": 0,
                        "temperature": 0,
                        "action": "close",
                        "updated_at": "2025-09-30 11:45:29"
                      },
                      "capabilities": {
                        "open": "c70a5a66-7a78-49cf-9dae-2881badc5cc8",
                        "close": "7733462c-a76e-4a38-9b37-6a7cb29a966e",
                        "toggle": "ac06b722-4683-4482-b642-c3f70c0bf162",
                        "led": "28e9d909-2ced-47ee-ae21-b71c9d8d6367"
                      },
                      "actions": {
                        "open": "/v1/actions/dv-01k6d7v7p1r2v1rg0ygteky06p-open-lock",
                        "close": "/v1/actions/dv-01k6d7v7p1r2v1rg0ygteky06p-close-lock",
                        "toggle": "/v1/actions/dv-01k6d7v7p1r2v1rg0ygteky06p-toggle-lock",
                        "led": "/v1/actions/dv-01k6d7v7p1r2v1rg0ygteky06p-toggle-led"
                      },
                      "topic": "0s124d_0x12499920",
                      "custom": null
                    }
                  ],
                  "meta": {
                    "current_page": 1,
                    "prev_page": false,
                    "next_page": 2,
                    "last_page": 106,
                    "from": 1,
                    "to": 20,
                    "per_page": 50,
                    "limit": 50,
                    "total": 2117
                  },
                  "links": {
                    "first": "v1/search/devices?page=1",
                    "last": "v1/search/devices?page=106",
                    "next": "v1/search/devices?page=2",
                    "prev": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/search/gateways": {
      "get": {
        "operationId": "get-v1-search-gateways",
        "tags": [
          "Search"
        ],
        "summary": "Search gateways",
        "description": "Returns a page of gateways whose label or mac_address matches, sorted by label.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": false,
            "description": "Search term, matched in label and mac_address. Empty matches all. Example: `?query=lobby`",
            "schema": {
              "type": "string"
            },
            "example": "lob"
          },
          {
            "name": "fuzzy",
            "in": "query",
            "required": false,
            "description": "`fuzzy` matches the characters of the term in this order. Default: the term anywhere. Example: `?query=lby&fuzzy=fuzzy`",
            "schema": {
              "type": "string"
            },
            "example": "fuzzy"
          },
          {
            "name": "direction",
            "in": "query",
            "required": false,
            "description": "Sort direction, `asc` or `desc`. Default `asc`. Example: `?direction=desc`",
            "schema": {
              "type": "string"
            },
            "example": "desc"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1 to 50. Default 50. Example: `?limit=10`",
            "schema": {
              "type": "integer"
            },
            "example": 10
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, starting at 1. Example: `?limit=10&page=2`",
            "schema": {
              "type": "integer"
            },
            "example": 2
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "ref_id": {
                            "type": "string"
                          },
                          "label": {
                            "type": "string"
                          },
                          "state": {
                            "type": "array",
                            "items": {}
                          },
                          "mac_address": {
                            "type": "string"
                          },
                          "customer": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "company": {
                                "type": "string"
                              }
                            }
                          },
                          "location": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "name": {
                                "type": "string"
                              }
                            }
                          },
                          "device_type": {
                            "type": "string"
                          },
                          "actions": {
                            "type": "object",
                            "properties": {
                              "open": {
                                "type": "string"
                              },
                              "close": {
                                "type": "string"
                              }
                            }
                          },
                          "topic": {
                            "type": "string"
                          },
                          "status": {
                            "type": "object",
                            "properties": {
                              "online": {
                                "type": "boolean"
                              },
                              "battery": {
                                "type": "integer"
                              },
                              "rssi": {
                                "type": "integer"
                              },
                              "temperature": {
                                "type": "integer"
                              },
                              "action": {
                                "type": "string"
                              },
                              "updated_at": {
                                "type": "string",
                                "format": "date-time"
                              }
                            }
                          },
                          "monitoring": {
                            "type": "array",
                            "items": {}
                          },
                          "custom": {
                            "nullable": true
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "current_page": {
                          "type": "integer"
                        },
                        "prev_page": {
                          "type": "boolean"
                        },
                        "next_page": {
                          "type": "boolean"
                        },
                        "last_page": {
                          "type": "integer"
                        },
                        "from": {
                          "type": "integer"
                        },
                        "to": {
                          "type": "integer"
                        },
                        "per_page": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "first": {
                          "type": "string"
                        },
                        "last": {
                          "type": "string"
                        },
                        "next": {
                          "nullable": true
                        },
                        "prev": {
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "2daf7361-fa52-4ce0-ae0b-e417558b69ff",
                      "ref_id": "01jvvhhxpzy14nres1bxbct9a3",
                      "label": "Suite 401",
                      "state": [],
                      "mac_address": "0x123",
                      "customer": {
                        "id": "daf62a38-5a89-4944-b01f-7b6cc9e88f77",
                        "ref_id": "01eg1v6h2qt17etgwe17jd3fbh",
                        "company": "Polder Parks"
                      },
                      "location": {
                        "id": "bd7838dc-7368-4317-89e0-2272f8d9f068",
                        "ref_id": "01fkk6424dnmwq7egj0hy7varf",
                        "name": "Meadow Lodge Veluwe"
                      },
                      "device_type": "gateway",
                      "actions": {
                        "open": "/v1/actions/gw-01jvvhhxpzy14nres1bxbct9a3-open-gateway",
                        "close": "/v1/actions/gw-01jvvhhxpzy14nres1bxbct9a3-close-gateway"
                      },
                      "topic": "0x123_network",
                      "status": {
                        "online": true,
                        "battery": 0,
                        "rssi": 0,
                        "temperature": 0,
                        "action": "close",
                        "updated_at": "2025-05-22 07:31:40"
                      },
                      "monitoring": [],
                      "custom": null
                    },
                    {
                      "id": "9ad2b747-5a37-4131-8ea8-e7b6a8824ff0",
                      "ref_id": "01gvz1g7y6ypsw755hvyrma6af",
                      "label": "Spa door",
                      "state": [],
                      "mac_address": "0x01234567890",
                      "customer": {
                        "id": "d8548e65-6f2e-4a68-bea8-297a13a98131",
                        "ref_id": "01gvz1e90q1f8dnheadzv4pbxm",
                        "company": "Linden Hotels"
                      },
                      "location": {
                        "id": "4060486d-15f0-47d8-9b7a-a37d9466360b",
                        "ref_id": "01gvz1f6n7zt9fgzz2230pjw6t",
                        "name": "Meadow Lodge Veluwe"
                      },
                      "device_type": "gateway",
                      "actions": {
                        "open": "/v1/actions/gw-01gvz1g7y6ypsw755hvyrma6af-open-gateway",
                        "close": "/v1/actions/gw-01gvz1g7y6ypsw755hvyrma6af-close-gateway"
                      },
                      "topic": "0x01234567890_network",
                      "status": {
                        "online": true,
                        "battery": 0,
                        "rssi": 0,
                        "temperature": 0,
                        "action": "close",
                        "updated_at": "2023-03-20 07:22:45"
                      },
                      "monitoring": [],
                      "custom": null
                    },
                    {
                      "id": "d5be484e-f107-4251-85b2-6095a16679a4",
                      "ref_id": "01ghxvz56e8sb3bad09wbvhm9w",
                      "label": "Room 103",
                      "state": [],
                      "mac_address": "0x124b0026e85852",
                      "customer": {
                        "id": "daf62a38-5a89-4944-b01f-7b6cc9e88f77",
                        "ref_id": "01eg1v6h2qt17etgwe17jd3fbh",
                        "company": "Polder Parks"
                      },
                      "location": {
                        "id": "bd7838dc-7368-4317-89e0-2272f8d9f068",
                        "ref_id": "01fkk6424dnmwq7egj0hy7varf",
                        "name": "Meadow Lodge Veluwe"
                      },
                      "device_type": "gateway",
                      "actions": {
                        "open": "/v1/actions/gw-01ghxvz56e8sb3bad09wbvhm9w-open-gateway",
                        "close": "/v1/actions/gw-01ghxvz56e8sb3bad09wbvhm9w-close-gateway"
                      },
                      "topic": "0x124b0026e85852_network",
                      "status": {
                        "online": true,
                        "battery": 0,
                        "rssi": 0,
                        "temperature": 0,
                        "action": "close",
                        "updated_at": "2023-10-06 08:31:03"
                      },
                      "monitoring": [],
                      "custom": null
                    }
                  ],
                  "meta": {
                    "current_page": 1,
                    "prev_page": false,
                    "next_page": false,
                    "last_page": 1,
                    "from": 1,
                    "to": 28,
                    "per_page": 50,
                    "limit": 50,
                    "total": 28
                  },
                  "links": {
                    "first": "v1/search/gateways?page=1",
                    "last": "v1/search/gateways?page=1",
                    "next": null,
                    "prev": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/search/locations": {
      "get": {
        "operationId": "get-v1-search-locations",
        "tags": [
          "Search"
        ],
        "summary": "Search locations",
        "description": "Returns a page of locations whose name matches, sorted by name.",
        "parameters": [
          {
            "name": "query",
            "in": "query",
            "required": false,
            "description": "Search term, matched in name. Empty matches all. Example: `?query=USA`",
            "schema": {
              "type": "string"
            },
            "example": "USA"
          },
          {
            "name": "fuzzy",
            "in": "query",
            "required": false,
            "description": "`fuzzy` matches the characters of the term in this order. Default: the term anywhere. Example: `?query=nwyrk&fuzzy=fuzzy`",
            "schema": {
              "type": "string"
            },
            "example": "fuzzy"
          },
          {
            "name": "direction",
            "in": "query",
            "required": false,
            "description": "Sort direction, `asc` or `desc`. Default `asc`. Example: `?direction=desc`",
            "schema": {
              "type": "string"
            },
            "example": "desc"
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Items per page, 1 to 50. Default 50. Example: `?limit=10`",
            "schema": {
              "type": "integer"
            },
            "example": 10
          },
          {
            "name": "page",
            "in": "query",
            "required": false,
            "description": "Page number, starting at 1. Example: `?limit=10&page=2`",
            "schema": {
              "type": "integer"
            },
            "example": 2
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "ref_id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "reference": {
                            "type": "string"
                          },
                          "customer": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string"
                              },
                              "ref_id": {
                                "type": "string"
                              },
                              "company": {
                                "type": "string"
                              }
                            }
                          }
                        }
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "current_page": {
                          "type": "integer"
                        },
                        "prev_page": {
                          "type": "boolean"
                        },
                        "next_page": {
                          "type": "boolean"
                        },
                        "last_page": {
                          "type": "integer"
                        },
                        "from": {
                          "type": "integer"
                        },
                        "to": {
                          "type": "integer"
                        },
                        "per_page": {
                          "type": "integer"
                        },
                        "limit": {
                          "type": "integer"
                        },
                        "total": {
                          "type": "integer"
                        }
                      }
                    },
                    "links": {
                      "type": "object",
                      "properties": {
                        "first": {
                          "type": "string"
                        },
                        "last": {
                          "type": "string"
                        },
                        "next": {
                          "nullable": true
                        },
                        "prev": {
                          "nullable": true
                        }
                      }
                    }
                  }
                },
                "example": {
                  "data": [
                    {
                      "id": "cf098ef1-bc66-4679-9da9-336ab5d1c561",
                      "ref_id": "01fkk63yt82hbs5h0gxjrexs43",
                      "name": "Grand Plaza Eindhoven",
                      "reference": "c2odemo89",
                      "customer": {
                        "id": "b5bdbb8a-7fac-469e-80d1-789dcf9f3d8c",
                        "ref_id": "01e31vwgfbfkcxfavhba7k682q",
                        "company": "Seaside Resorts"
                      }
                    },
                    {
                      "id": "ffc8aa72-a7c9-4347-9908-5bb9de1a6f8d",
                      "ref_id": "01k6d7tn2dhvszt89hjme18pn8",
                      "name": "Riverside Maastricht",
                      "reference": "12",
                      "customer": {
                        "id": "41f9b289-f3a0-4e8f-8f8a-b0bdf43e0e88",
                        "ref_id": "01k6d7sz6zzaj4e4hrdzjz7s85",
                        "company": "Brightdoor Systems"
                      }
                    },
                    {
                      "id": "701d919c-75ff-4912-8ae0-fdea75432669",
                      "ref_id": "01k94q63a6cj9shdm5yrdg66rx",
                      "name": "Northwind Rotterdam",
                      "reference": "134555",
                      "customer": {
                        "id": "8422ab96-d903-49ef-a7da-103eec7bd256",
                        "ref_id": "01k94q5rzc3kqwmt5rh9secqck",
                        "company": "Northwind Stays"
                      }
                    }
                  ],
                  "meta": {
                    "current_page": 1,
                    "prev_page": false,
                    "next_page": false,
                    "last_page": 1,
                    "from": 1,
                    "to": 22,
                    "per_page": 50,
                    "limit": 50,
                    "total": 22
                  },
                  "links": {
                    "first": "v1/search/locations?page=1",
                    "last": "v1/search/locations?page=1",
                    "next": null,
                    "prev": null
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/token/logout": {
      "get": {
        "operationId": "get-v1-token-logout",
        "tags": [
          "Auth"
        ],
        "summary": "Revoke the current token",
        "description": "Deletes the bearer token used for the request. Responds with HTTP 401 and an Unauthorized error body even when the token was revoked.",
        "responses": {
          "200": {
            "description": "OK"
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    },
    "/v1/token/renew": {
      "get": {
        "operationId": "get-v1-token-renew",
        "tags": [
          "Auth"
        ],
        "summary": "Renew the master token",
        "description": "Generates a new token and deletes all existing tokens of the consumer, including the one used for this request. Store the returned token before the next request; the old one stops working at once. Tokens do not expire.",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "links": {
                      "type": "object",
                      "properties": {
                        "self": {
                          "type": "string"
                        }
                      }
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "token": {
                          "type": "string"
                        }
                      }
                    }
                  }
                },
                "example": {
                  "links": {
                    "self": "/v1/token/renew"
                  },
                  "data": {
                    "token": "1288|ocJ2isAjIhKtJ0RlgLKOmxgJTeKdNnFRIBXuDL7D3b8b4480"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthenticated"
          }
        },
        "security": [
          {
            "bearer": []
          }
        ]
      }
    }
  }
}
