swagger: "2.0"
openapi: 3.0.3
theme:

info:
  title: RiskBase API
  description: |
    # API

    The RiskBase API allows you to directly consume data in RiskBase. If you're interested in using the API or need any help, get in touch at support@riskbase.uk

    ## Authentication

    To start using the API, you first need to get an API token for your organisation from Settings in the RiskBase app. This token should be sent with all requests as a Bearer token in the Authorization HTTP header.

    ```shell
    GET /properties
    Host: api3.riskbase.uk
    Authorization: Bearer 5d2e9eff0e253e3ef4544...
    ```

    ## Responses

    All API responses are formatted as JSON. Successful requests return a ``2xx`` HTTP status code. Each endpoint's payload and response is detailed later in this documentation.

    ## Error Responses

    ``401 Unauthorized``
    Authentication is required and has failed.
    ```json
    {
      code: Unauthorized
      error: Authentication required
    }
    ```

    ``403 Forbidden``
    The API understood the request but is refusing the connection. This is usually due to the account not having the necessary permissions
    ```json
    {
      code: Forbidden
      error: No access
    }
    ```

    ``501 Not Implemented``
    This endpoint is planned but has not yet been released.
    ```json
    {
      code: NotImplemented
      error: Not implemented
    }
    ```

    # Changelog

    | Date | By | Description |
    | ---------- | -------- | ------- |
    | 25/02/2026 | RC | Added `properties` filter to `GET /properties/assets` |
    | 25/02/2026 | RC | Added `POST /properties/{propertyId}/assets` and `PATCH /properties/{propertyId}/assets/{assetId}` endpoints |
    | 04/01/2026 | BW | Added `/properties/assets` endpoints and deprecated `/elements` endpoints |
    | 11/12/2025 | RC | Added `scheduleCustomReference` to `GET /assessments` endpoint |
    | 06/10/2025 | BW | Added `POST /users` endpoint |
    | 16/07/2025 | RC | Update webhooks to include `property` and `propertygroup` events and remove `asset` and `assetgroup` events |
    | 16/07/2025 | RC | New `/properties` endpoints replace the `/assets` endpoints. The old `/assets` endpoints still exist but are deprecated; they will remain available but should be avoided |
    | 14/05/2025 | RC | Improved field descriptions for `GET /elements` and `GET /elements/types` |
    | 09/05/2025 | RC | Fixed `POST /assets` endpoint (was incorrectly listed as `POST /assets/tree`) |
    | 05/03/2025 | RC | Added `customreference` query filter to `GET assets` |
    | 05/03/2025 | RC | Added assessment `flags` to response of `GET assessments` and added `includeflags` query parameter to enable it |
    | 05/03/2025 | RC | Introduced changelog to documentation |

    # Rate Limits

    The API implements a "sliding window" rate limiter with the following limits:

    - `60 requests per 1 minute`
    - `10 requests per 10 seconds`

    All rate limited endpoints return HTTP headers describing the limit and how many requests remain:

    ```shell
    X-Rate-Limit-Minute-Limit: 60
    X-Rate-Limit-Minute-Remaining: 59
    X-Rate-Limit-10Second-Limit: 10
    X-Rate-Limit-10Second-Remaining: 9
    ```

    These are the limits at the time of writing but they may change. Your integration should gracefully manage changes to these limits.

    ## Exceeding Rate Limits
    Exceeding the rate limit will result in an HTTP 429 (Too Many Requests) response and include the `Retry-After` HTTP header:

    ```shell
    # Pause requests for the number of seconds specified
    Retry-After: 32
    ```

    Continuing to make requests while you are rate limited may result in your user being banned.

    ## Avoiding Rate Limits

    When building your integration, waiting a second between requests should keep you under the rate limit. Making requests serially (instead of concurrently) or queuing requests can help respect rate limit HTTP headers.

    Subscribe to webhook events instead of polling the API for data.

    # Webhooks

    Webhooks let you subscribe to events happening in RiskBase; enabling you to receive notifications as they happen, as opposed to polling the API to see if data has changed.

    RiskBase will send an HTTP request to a URL of your choice with basic data about each event. You should store this in your application and then separately request more information about the resource (property, task, assessment, etc) via the RiskBase API.

    ## Setup

    To get started, setup a webhook for your organisation in Settings in the RiskBase app. Each webhook requires only an HTTPS URL but you can also enter a secret.

    ## Failed Requests

    Your server should respond to webhook requests with a `2xx` response within 4 seconds. If your server takes longer than 4 seconds, RiskBase will terminate the connection and consider the request a failure. In order to respond within the timeout, we recommend simply storing the request's payload and returning `2xx`; dealing with the payload should be queued to run as a separate job.

    On a failure, RiskBase will retry 4 more times:

    + if the first attempt fails, RiskBase will retry 2 minutes later
    + if the second attempt fails, RiskBase will retry 4 minutes later
    + if the third attempt fails, RiskBase will retry 8 minutes later
    + if the fourth attempt fails, RiskBase will retry 10 minutes later

    ## Validating Webhook Requests with Secrets

    To ensure your server only processes webhook requests sent by RiskBase and to ensure the payload was not tampered with, you should validate the webhook signature before processing the webhook request further.

    To use this feature, enter a secret token of your choice when setting up (or updating) your webhook. Your secret should be a random string of text with high entropy.

    ### Validating Webhook Requests

    RiskBase uses your secret token and the request's payload to create a hash signature. The hash signature will appear in each request as the HTTP header:

    ```json
    {
      'X-RB-Signature-256': '{hash signature}'
    }
    ```

    In your code that handles webhook requests, you should calculate a hash using your secret token. Then, compare the hash that RiskBase sent with the expected hash that you calculated, and ensure they match.

    RiskBase uses an HMAC hex digest to compute the hash. Instead of using a basic string comparison, use a method like crypto.timingSafeEqual, used to determine whether two variables are equal without exposing timing information that may allow an attacker to guess one of the values.

    ### Example Code

    ```typescript
    import * as crypto from "crypto";

    const WEBHOOK_SECRET: string = process.env.WEBHOOK_SECRET;

    const verify_signature = (req: Request) => {
      const signature = crypto
        .createHmac("sha256", WEBHOOK_SECRET)
        .update(JSON.stringify(req.body))
        .digest("hex");
      const trusted = Buffer.from(signature, 'ascii');
      const untrusted =  Buffer.from(req.headers.get("x-rb-signature-256"), 'ascii');
      return crypto.timingSafeEqual(trusted, untrusted);
    };

    const handleWebhook = (req: Request, res: Response) => {
      if (!verify_signature(req)) {
        res.status(401).send("Unauthorized");
        return;
      }
      // Continue processing webhook request...
    };
    ```

    ## Event Types

    Webhooks are queued and sent within a few minutes of an event. A webhook request includes an array of one or more events, each with a `type`. Most events also have an `id` but this is not always true; see below for details about each event.

    ```json
    [
      {"type":"property", "id":"cksq4ybpq104zwgwh2gd1vvha"},
      {"type":"property", "id":"kw4ooco04cog8sooow0ogcgg"},
      {"type":"task", "id":"cle72jm2q0001pxwhqnf5qfoc"},
      {"type":"assessment", "id":"cllks38mw000131wh9ukgjc4g"},
      {"type":"assessmentschedule", "propertyId":"cllks38mw000131wh9ukgjc4g", "typeId":"cm65bkfml00kpyjwh84eword", "assetId":"cllks38mw000131wh9ukgjc4g"},
      ...
    ]
    ```

    ### Property Event `property`

    - Property is created or deleted,
    - Property's name, address, or tree position is updated.

    ```
    { "type": "property", "id": "{UID}" }
    ```

    Note: When a `property` event is received an `asset` event will be included; this is for backward compatibility but should be ignored.

    ```
    { "type": "asset", "id": "{UID}" }
    ```

    ### Property Group Event `propertygroup`

    - Property group is created or deleted,
    - Property group's name or tree position is updated.


    ```
    { "type": "propertygroup", "id": "{UID}" }
    ```

    Note: When a `propertygroup` event is received an `assetgroup` event will be included; this is for backward compatibility but should be ignored.

    ```
    { "type": "assetgroup", "id": "{UID}" }
    ```

    ### Task Event `task`

    - Task is updated.

    ```
    { "type": "task", "id": "{UID}" }
    ```

    ### Assessment Event `assessment`

    - Assessment is created, submitted, approved, unapproved, or deleted.

    ```
    { "type": "assessment", "id": "{UID}" }
    ```

    ### Assessment Schedule Event `assessmentschedule`

    - Assessment schedule is created or deleted,
    - Assessment schedule is updated.

    ```
    { "type": "assessmentschedule", "propertyId": "{UID}", "typeId":"{UID}", "assetId": "{UID}" }
    ```

    Note: The `assetId` included in this event is for backward compatibility and should be ignored.

    ### User Event `user`

    - User is added or removed from your organisation,
    - User name or email is updated.

    ```
    { "type": "user", "id": "{UID}" }
    ```

    ### Team Event `team`

    - Team is created or deleted,
    - Team's name or description is updated,
    - Team's members are changed.

    ```
    { "type": "team", "id": "{UID}" }
    ```
  _termsOfService: https://riskbase.uk/terms
  _contact:
    email: support@riskbase.uk
  x-logo:
    url: "/assets/RiskBaseLogo.svg"
    altText: RiskBase
    href: https://riskbase.uk
servers:
  - url: https://api3.riskbase.uk
tags:
  - name: General
    description: ""
  - name: Users & Teams
    description: ""
  - name: Properties
    description: ""
  - name: "Property Assets"
    description: ""
  - name: Assessments
    description: ""
  - name: Tasks
    description: ""
  - name: Plans
    description: ""
  - name: Files
    description: ""
  - name: Assets
    description: ""
  - name: Elements
    description: ""
schemes:
  - https
security:
  - Bearer Authentication: []
components:
  securitySchemes:
    Bearer Authentication:
      type: http
      scheme: bearer
      description: "`Authorization: Bearer {AuthorizationToken}`"
    None / Bearer Authentication:
      type: http
      scheme: none / bearer
      description:
        "This endpoint will return even when no bearer is provided.<br>`Authorization:
        Bearer {AuthorizationToken}`"
  schemas:
    elements:
      types:
        type: array
        items:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            nameSingular:
              type: string
            fields:
              type: array
              items:
                discriminator:
                  propertyName: type
                oneOf:
                  - $ref: "#/components/schemas/fieldTypes/text"
                  - $ref: "#/components/schemas/fieldTypes/number"
                  - $ref: "#/components/schemas/fieldTypes/image"
                  - $ref: "#/components/schemas/fieldTypes/file"
                  - $ref: "#/components/schemas/fieldTypes/option"
                  - $ref: "#/components/schemas/fieldTypes/pin"
                  - $ref: "#/components/schemas/fieldTypes/qr"
    propertyassets:
      types:
        type: array
        items:
          type: object
          properties:
            id:
              type: string
            name:
              type: string
            nameSingular:
              type: string
            fields:
              type: array
              items:
                discriminator:
                  propertyName: type
                oneOf:
                  - $ref: "#/components/schemas/fieldTypes/text"
                  - $ref: "#/components/schemas/fieldTypes/number"
                  - $ref: "#/components/schemas/fieldTypes/image"
                  - $ref: "#/components/schemas/fieldTypes/file"
                  - $ref: "#/components/schemas/fieldTypes/option"
                  - $ref: "#/components/schemas/fieldTypes/pin"
                  - $ref: "#/components/schemas/fieldTypes/qr"
    fieldTypes:
      text:
        type: object
        properties:
          id:
            type: string
            format: UID
          identifier:
            type: string
          name:
            type: string
          type:
            type: string
          config:
            type: object
      number:
        type: object
        properties:
          id:
            type: string
            format: UID
          identifier:
            type: string
          name:
            type: string
          type:
            type: string
          config:
            type: object
      image:
        type: object
        properties:
          id:
            type: string
            format: UID
          identifier:
            type: string
          name:
            type: string
          type:
            type: string
          config:
            type: object
            properties:
              multi:
                type: boolean
      file:
        type: object
        properties:
          id:
            type: string
            format: UID
          identifier:
            type: string
          name:
            type: string
          type:
            type: string
          config:
            type: object
            properties:
              multi:
                type: boolean
      option:
        type: object
        properties:
          id:
            type: string
            format: UID
          identifier:
            type: string
          name:
            type: string
          type:
            type: string
          config:
            type: object
            properties:
              multi:
                type: boolean
              options:
                type: array
                items:
                  type: object
                  properties:
                    id:
                      type: string
                      format: UID
                    value:
                      type: string
      pin:
        type: object
        properties:
          id:
            type: string
            format: UID
          identifier:
            type: string
          name:
            type: string
          type:
            type: string
          config:
            type: object
      qr:
        type: object
        properties:
          id:
            type: string
            format: UID
          identifier:
            type: string
          name:
            type: string
          type:
            type: string
          config:
            type: object
    fieldResults:
      text:
        type: object
        properties:
          id:
            type: string
            format: UID
            description: ID of field
          identifier:
            type: string
            description: Identifier of field
          type:
            type: string
            description: type of field
          result:
            type: object
            properties:
              value:
                type: string
      number:
        type: object
        properties:
          id:
            type: string
            format: UID
            description: ID of field
          identifier:
            type: string
            description: Identifier of field
          type:
            type: string
            description: type of field
          result:
            type: object
            properties:
              value:
                type: integer
      date:
        type: object
        properties:
          id:
            type: string
            format: UID
            description: ID of field
          identifier:
            type: string
            description: Identifier of field
          type:
            type: string
            description: type of field
          result:
            type: object
            properties:
              value:
                type: string
                format: Y-m-d
      time:
        type: object
        properties:
          id:
            type: string
            format: UID
            description: ID of field
          identifier:
            type: string
            description: Identifier of field
          type:
            type: string
            description: type of field
          result:
            type: object
            properties:
              value:
                type: time
                format: H:i
      image:
        type: object
        properties:
          id:
            type: string
            format: UID
            description: ID of field
          identifier:
            type: string
            description: Identifier of field
          type:
            type: string
            description: type of field
          result:
            type: object
            properties:
              ids:
                type: array
                items:
                  type: string
                  format: UID
                  description: File IDs
      file:
        type: object
        properties:
          id:
            type: string
            format: UID
            description: ID of field
          identifier:
            type: string
            description: Identifier of field
          type:
            type: string
            description: type of field
          result:
            type: object
            properties:
              ids:
                type: array
                items:
                  type: string
                  format: UID
                  description: File IDs
      option:
        type: object
        properties:
          id:
            type: string
            format: UID
            description: ID of field
          identifier:
            type: string
            description: Identifier of field
          type:
            type: string
            description: type of field
          result:
            type: object
            properties:
              ids:
                type: array
                items:
                  type: string
                  format: UID
              values:
                type: array
                items:
                  type: string
      pin:
        type: object
        properties:
          id:
            type: string
            format: UID
            description: ID of field
          identifier:
            type: string
            description: Identifier of field
          type:
            type: string
            description: type of field
          result:
            type: object
            properties:
              planId:
                type: string
                format: UID
              percentageFromLeft:
                type: string
                format: decimal
              percentageFromTop:
                type: string
                format: decimal
      qr:
        type: object
        properties:
          id:
            type: string
            format: UID
            description: ID of field
          identifier:
            type: string
            description: Identifier of field
          type:
            type: string
            description: type of field
          result:
            type: object
            properties:
              value:
                type: string
    planTypeGroup:
      svg:
        type: object
        properties:
          type:
            type: string
          format:
            type: string
            enum: [svg]
          width:
            type: int
          height:
            type: int
      pdf:
        type: object
        properties:
          type:
            type: string
          format:
            type: string
            enum: [pdf]
          width:
            type: int
          height:
            type: int
      image:
        type: object
        properties:
          type:
            type: string
          format:
            type: string
            enum: [jpeg]
          width:
            type: int
          height:
            type: int
    planTypeGroupWithContent:
      svg:
        type: object
        properties:
          type:
            type: string
          format:
            type: string
            enum: [svg]
          width:
            type: int
          height:
            type: int
          base64Content:
            type: string
            format: byte
      pdf:
        type: object
        properties:
          type:
            type: string
          format:
            type: string
            enum: [pdf]
          width:
            type: int
          height:
            type: int
          base64Content:
            type: string
            format: byte
      image:
        type: object
        properties:
          type:
            type: string
          format:
            type: string
            enum: [jpeg]
          width:
            type: int
          height:
            type: int
          base64Content:
            type: string
            format: byte
  examples:
    elements:
      list:
        elements:
          - id: cksq3o1qn00j20hs0ayi7qagu
            property: cksq39rno02kj0ns0qcqi1sz1
            asset: cksq39rno02kj0ns0qcqi1sz1
            type: cksq3ocb600mu0hs0qhachlip
            fields:
              - id: cksq3ocb600mu0hs0qhachlip
                identifier: flatNumber
                type: text
                result:
                  value: Flat 1A
              - id: eowcg4w4w84sk4o4w440k8k0
                identifier:
                type: file
                result:
                  ids:
                    - x480ws4sks0kskc0wssogkg4
                    - uwcwsoo00g0swosg4w00oc4g
                    - d8kswcsk8k08c4g8k4cc8044
              - id: i0sg4o4c0sgkkogsg4wsgwco
                identifier:
                type: image
                result:
                  ids:
                    - e80wo0k4oks0gs4ks404s4k4
              - id: cksq3oc5y004i0hs0ff0cbyk3
                identifier: occupancyType
                type: option
                result:
                  ids:
                    - cloirzzkg00058usq5r0kbhbw
                    - cloirzzkp00068usqc2as5d93
                  values:
                    - Residential
                    - Business
              - id: cksq3ocb800n00hs0249bbds3
                identifier: pin
                type: pin
                result:
                  planId: vs8wco44wosgssscww4o880c
                  percentageFromLeft: "87.666666666666"
                  percentageFromTop: "17.777777777778"
        types:
          - id: cksq3o1qn00j20hs0ayi7qagu
            name: Flat Entrance Doors
            nameSingular: Flat Entrance Door
            fields:
              - id: cksq3ocb600mu0hs0qhachlip
                identifier: flatNumber
                name: Flat Number
                type: text
                config: {}
              - id: eowcg4w4w84sk4o4w440k8k0
                identifier:
                name: File Attachments
                type: file
                config:
                  multi: true
              - id: i0sg4o4c0sgkkogsg4wsgwco
                identifier:
                name: Main Image
                type: image
                config:
                  multi: false
              - id: cksq3oc5y004i0hs0ff0cbyk3
                identifier: occupancyType
                name: Type of Occupant
                type: option
                config:
                  multi: true
                  options:
                    - id: cloirzzkg00058usq5r0kbhbw
                      value: Residential
                    - id: cloirzzkp00068usqc2as5d93
                      value: Business
                    - id: cloirzzky00078usqha9i4o2u
                      value: Educational
              - id: cksq3ocb800n00hs0249bbds3
                identifier: pin
                name: Pin
                type: pin
                config: {}
      types:
        types:
          - id: cksq3o1qn00j20hs0ayi7qagu
            name: Flat Entrance Doors
            nameSingular: Flat Entrance Door
            fields:
              - id: cksq3ocb600mu0hs0qhachlip
                identifier: flatNumber
                name: Flat Number
                type: text
                config: {}
              - id: eowcg4w4w84sk4o4w440k8k0
                identifier:
                name: File Attachments
                type: file
                config:
                  multi: true
              - id: i0sg4o4c0sgkkogsg4wsgwco
                identifier:
                name: Main Image
                type: image
                config:
                  multi: false
              - id: cksq3oc5y004i0hs0ff0cbyk3
                identifier: occupancyType
                name: Type of Occupant
                type: option
                config:
                  multi: true
                  options:
                    - id: cloirzzkg00058usq5r0kbhbw
                      value: Residential
                    - id: cloirzzkp00068usqc2as5d93
                      value: Business
                    - id: cloirzzky00078usqha9i4o2u
                      value: Educational
              - id: cksq3ocb800n00hs0249bbds3
                identifier: pin
                name: Pin
                type: pin
                config: {}
    propertyassets:
      list:
        assets:
          - id: cksq3o1qn00j20hs0ayi7qagu
            property: cksq39rno02kj0ns0qcqi1sz1
            type: cksq3ocb600mu0hs0qhachlip
            fields:
              - id: cksq3ocb600mu0hs0qhachlip
                identifier: flatNumber
                type: text
                result:
                  value: Flat 1A
              - id: eowcg4w4w84sk4o4w440k8k0
                identifier:
                type: file
                result:
                  ids:
                    - x480ws4sks0kskc0wssogkg4
                    - uwcwsoo00g0swosg4w00oc4g
                    - d8kswcsk8k08c4g8k4cc8044
              - id: i0sg4o4c0sgkkogsg4wsgwco
                identifier:
                type: image
                result:
                  ids:
                    - e80wo0k4oks0gs4ks404s4k4
              - id: cksq3oc5y004i0hs0ff0cbyk3
                identifier: occupancyType
                type: option
                result:
                  ids:
                    - cloirzzkg00058usq5r0kbhbw
                    - cloirzzkp00068usqc2as5d93
                  values:
                    - Residential
                    - Business
              - id: cksq3ocb800n00hs0249bbds3
                identifier: pin
                type: pin
                result:
                  planId: vs8wco44wosgssscww4o880c
                  percentageFromLeft: "87.666666666666"
                  percentageFromTop: "17.777777777778"
        types:
          - id: cksq3o1qn00j20hs0ayi7qagu
            name: Flat Entrance Doors
            nameSingular: Flat Entrance Door
            fields:
              - id: cksq3ocb600mu0hs0qhachlip
                identifier: flatNumber
                name: Flat Number
                type: text
                config: {}
              - id: eowcg4w4w84sk4o4w440k8k0
                identifier:
                name: File Attachments
                type: file
                config:
                  multi: true
              - id: i0sg4o4c0sgkkogsg4wsgwco
                identifier:
                name: Main Image
                type: image
                config:
                  multi: false
              - id: cksq3oc5y004i0hs0ff0cbyk3
                identifier: occupancyType
                name: Type of Occupant
                type: option
                config:
                  multi: true
                  options:
                    - id: cloirzzkg00058usq5r0kbhbw
                      value: Residential
                    - id: cloirzzkp00068usqc2as5d93
                      value: Business
                    - id: cloirzzky00078usqha9i4o2u
                      value: Educational
              - id: cksq3ocb800n00hs0249bbds3
                identifier: pin
                name: Pin
                type: pin
                config: {}
              - id: rw080wwgko08wckkgc88s4o0
                identifier: "fireRating"
                name: Fire Rating
                type: option
                config: {
                  multi: false,
                  options: [
                    {
                      id: "clfawx3z300018psqf8mv6x22",
                      value: "FD30"
                    },
                    {
                      id: "clfawx3zc00028psqf9830q5x",
                      value: "FD30S"
                    },
                    {
                      id: "clfawx3zc00028psqf9830q5x",
                      value: "FD60"
                    }
                  ]
                }
      types:
        types:
          - id: cksq3o1qn00j20hs0ayi7qagu
            name: Flat Entrance Doors
            nameSingular: Flat Entrance Door
            fields:
              - id: cksq3ocb600mu0hs0qhachlip
                identifier: flatNumber
                name: Flat Number
                type: text
                config: {}
              - id: eowcg4w4w84sk4o4w440k8k0
                identifier:
                name: File Attachments
                type: file
                config:
                  multi: true
              - id: i0sg4o4c0sgkkogsg4wsgwco
                identifier:
                name: Main Image
                type: image
                config:
                  multi: false
              - id: cksq3oc5y004i0hs0ff0cbyk3
                identifier: occupancyType
                name: Type of Occupant
                type: option
                config:
                  multi: true
                  options:
                    - id: cloirzzkg00058usq5r0kbhbw
                      value: Residential
                    - id: cloirzzkp00068usqc2as5d93
                      value: Business
                    - id: cloirzzky00078usqha9i4o2u
                      value: Educational
              - id: cksq3ocb800n00hs0249bbds3
                identifier: pin
                name: Pin
                type: pin
                config: {}
              - id: rw080wwgko08wckkgc88s4o0
                identifier: "fireRating"
                name: Fire Rating
                type: option
                config: {
                  multi: true,
                  options: [
                    {
                      id: "clfawx3z300018psqf8mv6x22",
                      value: "FD30"
                    },
                    {
                      id: "clfawx3zc00028psqf9830q5x",
                      value: "FD30S"
                    },
                    {
                      id: "clfawx3zc00028psqf9830q5x",
                      value: "FD60"
                    }
                  ]
                }
paths:
  "/ping":
    get:
      tags:
        - General
      summary: Ping RiskBase
      description: Check RiskBase availability and your authentication
      consumes:
        - application/json
      produces:
        - application/json
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  authenticated:
                    type: boolean
                    example: true
                  apiUserName:
                    type: string
                    nullable: true
                    example: true
                example:
                  authenticated: true
                  apiUserName: Name of Your API User
      security:
        - None / Bearer Authentication: []
  "/users":
    get:
      tags:
        - Users & Teams
      summary: Get Users
      # description: Get a list of users in your organisation
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 1000
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: account
          schema:
            type: string
            format: UID
            example: ckweru5xg000142qyx3m0sds
          description: Comma separated user IDs
        - in: query
          name: email
          schema:
            type: string
            format: email
            example: ben.kenney@example.com
          description: Comma separated emails
        - in: query
          name: reference
          schema:
            type: string
            format: string
            example: RB-YNAVYJ
          description: Comma separated RiskBase references
        - in: query
          name: customReference
          schema:
            type: string
            format: string
            example: your-stored-custom-reference
          description: Comma separated RiskBase custom references
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  total:
                    type: integer
                  users:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: UID
                        email:
                          type: email
                        forename:
                          type: string
                        surname:
                          type: string
                        teams:
                          type: array
                          description: An array of team IDs the user is a member of
                          items:
                            type: string
                            format: UID
                        provisionType:
                          type: enum
                          enum: [riskbase, scim]
                          description: Describes whether the account was provisioned via RiskBase (riskbase) or the SCIM API (scim)
                example:
                  total: 2
                  users:
                    - id: cksq4xkxh012173wh9agrq0iz
                      forename: Ben
                      surname: Kenney
                      email: ben.kenney@example.com
                      teams:
                        [cksq5ee6607bwedwhkb6ra827, cksq5ee7m07mtedwhhqwwbdpw]
                      provisionType: riskbase
                    - id: cksq4xgao07ctwgwhkn2ovl45
                      forname: Brandon
                      surname: Boyd
                      email: brandon.kenney@example.com
                      teams: []
                      provisionType: riskbase
    post:
      tags:
        - Users & Teams
      summary: Create or Link User
      description: |
        This POST request is used to create a new user. If a user already exists, they will be added to the organisation. The authentication type will be set to passwordless by default.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - email
                - forename
                - surname
              properties:
                email:
                  type: string
                  format: email
                  description: The user's email address
                  example: ben.boyd@riskbase.uk
                forename:
                  type: string
                  example: Ben
                surname:
                  type: string
                  example: Boyd
                customReference:
                  type: string
                  example: custom-reference
                roles:
                  type: array
                  items:
                    type: object
                    properties:
                      value:
                        type: string
                active:
                  type: boolean
                  default: false
                  example: true
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: string
                    format: UID
                    example: yok0w80s0sckwwgo0c8sko4o
                  usercreated:
                    type: boolean
                    example: true
                    description: Indicates whether the operation created a new user within an organisation.
                  userLinked:
                    type: boolean
                    example: false
                    description: Indicates whether the operation linked an existing user to the organisation rather than creating a new user.
        "400":
          content:
            application/json:
              schema:
                oneOf:
                  - title: UserCreateFailedToLink
                    properties:
                      code:
                        type: string
                        enum: [UserCreateFailedToLink]
                        example: UserCreateFailedToLink
                  - title: UserCreateEmailRequired
                    properties:
                      code:
                        type: string
                        enum: [UserCreateEmailRequired]
                        example: UserCreateEmailRequired
                  - title: UserCreateEmailFormatInvalid
                    properties:
                      code:
                        type: string
                        enum: [UserCreateEmailFormatInvalid]
                        example: UserCreateEmailFormatInvalid
                  - title: UserCreateFailed
                    properties:
                      code:
                        type: string
                        enum: [UserCreateFailed]
                        example: UserCreateFailed

  "/teams":
    get:
      tags:
        - Users & Teams
      summary: Get Teams
      # description: Get a list of teams in your organisation
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 1000
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: team
          schema:
            type: string
            format: UID
            example: ckweru5xg000142qyx3m0sds
          description: Comma separated teams IDs
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  total:
                    type: integer
                  teams:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: UID
                        name:
                          type: string
                        users:
                          type: array
                          description: An array of member user IDs
                          items:
                            type: string
                            format: UID
                example:
                  total: 10
                  teams:
                    - id: cksq5ee6607bwedwhkb6ra827
                      name: Remedial Works
                      description: Users responsible for actioning remedial works
                      users: [cksq4xkxh012173wh9agrq0iz]
                    - id: cksq5ee7m07mtedwhhqwwbdpw
                      name: Assessors
                      description: ""
                      users:
                        [
                          cksq50h7g0638hywhasfzw7cd,
                          cksq4xg9g073gwgwh269ug5vb,
                          cl1djtphd0001b0wh11hgfazk,
                        ]
  "/teams/{teamId}/users/add":
    patch:
      tags:
        - Users & Teams
      summary: Add Users to Team
      description: |
        Add users to a team
        - Invalid user IDs are silently ignored.
        - Triggers the `team` webhook.
      parameters:
        - in: path
          name: teamId
          required: true
          schema:
            type: string
            format: UID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - users
              properties:
                users:
                  type: array
                  description: User IDs to add to the team
                  items:
                    type: string
                    format: UID
                skipWebhook:
                  type: boolean
                  default: false
              example:
                users: [cksq50h7g0638hywhasfzw7cd, cksq4xg9g073gwgwh269ug5vb]
      responses:
        "204":
          content: application/json
  "/teams/{teamId}/users/remove":
    patch:
      tags:
        - Users & Teams
      summary: Remove Users from Team
      description: |
        Remove users from a team.
        - Users are also removed as responsible for the team. (See `Get Property Team Users`.)
        - Invalid user IDs are silently ignored.
        - Triggers the `team` webhook.
      parameters:
        - in: path
          name: teamId
          required: true
          schema:
            type: string
            format: UID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - users
              properties:
                users:
                  type: array
                  description: User IDs to remove from the team
                  items:
                    type: string
                    format: UID
                skipWebhook:
                  type: boolean
                  default: false
              example:
                users: [cksq50h7g0638hywhasfzw7cd, cksq4xg9g073gwgwh269ug5vb]
      responses:
        "204":
          content: application/json

  # Properties

  "/properties/groups":
    get:
      tags:
        - Properties
      summary: Get Property Groups
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 1000
        - in: query
          name: page
          schema:
            type: integer
            default: 1
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  total:
                    type: integer
                    example: 50
                  propertyGroups:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: UID
                        name:
                          type: string
                        reference:
                          type: string
                        customReference:
                          type: string
                    example:
                      - id: cksq39rnv02vf0ns0t3o834uv
                        name: London South
                        reference: RB-Z0LMKJ
                        customReference:
  "/properties":
    get:
      tags:
        - Properties
      summary: Get Properties
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 1000
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: property
          schema:
            type: string
            example: cksq4ybpq104zwgwh2gd1vvha
          description: Comma separated property IDs
        - in: query
          name: customreference
          schema:
            type: string
            example: CustomReference1,CustomReference2
          description: Comma separated property custom references
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  total:
                    type: integer
                    example: 9250
                  properties:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        reference:
                          type: string
                        customReference:
                          type: string
                        photoId:
                          nullable: true
                          type: string
                        address:
                          type: object
                          properties:
                            line1:
                              type: string
                            line2:
                              type: string
                            city:
                              type: string
                            county:
                              type: string
                            postcode:
                              type: string
                    example:
                      - id: cksq4ybpq104zwgwh2gd1vvha
                        name: Demo Property
                        reference: RB-ABC123
                        customReference: MyUprn0001
                        photoId: cksq3jhl500ga0ls0oiibt7q2,
                        address:
                          line1: 33 Magnolia Avenue
                          line2: ""
                          city: London
                          county: ""
                          postcode: SW10 2BT
    post:
      tags:
        - Properties
      summary: Create Property
      description: |
        - Triggers the `property` webhook.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  required: true
                parent:
                  type: string
                  nullable: true,
                  format: UID
                  description: Parent property or property group ID. If null is provided, the property will be created in a property group called "Created by API"
                customReference:
                  type: string
                address:
                  type: object
                  properties:
                    line1:
                      type: string
                    line2:
                      type: string
                    city:
                      type: string
                    county:
                      type: string
                    postcode:
                      type: string
                skipWebhook:
                  type: boolean
                  default: false
              example:
                parent: u400ko8sk848gc40kss400sg
                name: Building 1
                customReference: B000001
                address:
                  line1: 101 Wood Lane
                  city: London
                  postcode: W12 7FA
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: string
                    format: UID
                    example: yok0w80s0sckwwgo0c8sko4o
        "400":
          content:
            application/json:
              schema:
                oneOf:
                  - title: PropertyCreateNameRequired
                    properties:
                      code:
                        type: PropertyCreateNameRequired
                        example: PropertyCreateNameRequired
                  - title: PropertyCreateInvalidParent
                    properties:
                      code:
                        type: PropertyCreateInvalidParent
                        example: PropertyCreateInvalidParent
  "/properties/tree":
    get:
      tags:
        - Properties
      summary: Get Property Tree
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  tree:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        type:
                          type: enum
                          enum: [Organisation, Property Group, Property]
                        children:
                          type: array
                          description: Recurring tree
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              name:
                                type: string
                              type:
                                type: enum
                                enum: [Organisation, Property Group, Property]
                              children:
                                type: array
                                description: Recurring tree
                                items:
                                  type: object
                    example:
                      tree:
                        - id: cl8br0oe40001kkwhdglcu74r
                          name: Fox Residential
                          type: Organisation
                          children:
                            - id: cl8br1p900001mgwhcpbhopcp
                              name: Manchester
                              type: Property Group
                              children:
                                - id: cl8br4pnc0001opwhfidszqwt
                                  name: Blonde Retreat
                                  type: Property
                                  children: []
                                - id: cl8br4pph0003opwhouu2j0ew
                                  name: The Blade Building
                                  type: Property
                                  children: []
  "/properties/{propertyId}":
    patch:
      tags:
        - Properties
      summary: Update Property
      description: |
        Update a property's name and address.
        - Triggers the `property` webhook.
      parameters:
        - in: path
          name: propertyId
          required: true
          schema:
            type: string
            format: UID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                customReference:
                  type: string
                address:
                  type: object
                  properties:
                    line1:
                      type: string
                    line2:
                      type: string
                    city:
                      type: string
                    county:
                      type: string
                    postcode:
                      type: string
                skipWebhook:
                  type: boolean
                  default: false
              example:
                parent: u400ko8sk848gc40kss400sg
                name: Building 1
                customReference: B000001
                address:
                  line1: 101 Wood Lane
                  city: London
                  postcode: W12 7FA
      responses:
        "204":
          content: application/json
        "400":
          content:
            application/json:
              schema:
                oneOf:
                  - title: PropertyNotFound
                    properties:
                      code:
                        type: PropertyNotFound
                        example: PropertyNotFound
  "/properties/{propertyId}/parent":
    patch:
      tags:
        - Properties
      summary: Move Property
      description: |
        Move a property to a different position in the property tree; either below a property group or another property.
        - Triggers the `property` webhook.
      parameters:
        - in: path
          name: propertyId
          required: true
          schema:
            type: string
            format: UID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - parent
              properties:
                parent:
                  type: string
                  format: UID
                  description: Parent property or property group ID
                skipWebhook:
                  type: boolean
                  default: false
              example:
                parent: u400ko8sk848gc40kss400sg
      responses:
        "204":
          content: application/json
        "400":
          content:
            application/json:
              schema:
                oneOf:
                  - title: PropertyNotFound
                    properties:
                      code:
                        type: PropertyNotFound
                        example: PropertyNotFound
                  - title: PropertyParentNotFound
                    properties:
                      code:
                        type: PropertyParentNotFound
                        example: PropertyParentNotFound
                  - title: PropertyMoveParentIsChild
                    properties:
                      code:
                        type: PropertyMoveParentIsChild
                        example: PropertyMoveParentIsChild
                      error:
                        type: Parent property is currently a child of the property being moved
                        example: Parent property is currently a child of the property being moved
                  - title: PropertyMoveInvalidParentPropertyGroup
                    properties:
                      code:
                        type: PropertyMoveInvalidParentPropertyGroup
                        example: PropertyMoveInvalidParentPropertyGroup
                      error:
                        type: Property groups can only exist under an organisation or another property group
                        example: Property groups can only exist under an organisation or another property group
                  - title: PropertyMoveInvalidParentProperty
                    properties:
                      code:
                        type: PropertyMoveInvalidParentProperty
                        example: PropertyMoveInvalidParentProperty
                      error:
                        type: Property can only exist under a property group or another property
                        example: Property can only exist under a property group or another property
  "/properties/teamusers":
    get:
      tags:
        - Properties
      summary: Get Property Team Users
      description: |
        Get a list of users responsible for teams for all properties in your organisation.
        - Responsible users are auto-assigned to tasks that are assigned to their team.
        - Users are automatically given access to properties they are responsible for.
      parameters:
        - in: query
          name: property
          schema:
            type: string
            format: UID
            example: cksq4ybpq104zwgwh2gd1vvha
          description: Comma separated property IDs
        - in: query
          name: user
          schema:
            type: string
            format: UID
            example: cksq4xkxh012173wh9agrq0iz
          description: Comma separated user IDs
        - in: query
          name: includeinherited
          schema:
            type: boolean
            default: false
            example: true
          description: Responsibility is inherited down the property tree. By default this endpoint will list responsbility which has been set explicitly. Set this to true to include inherited responsibility.
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  properties:
                    type: object
                    properties:
                      propertyId:
                        type: object
                        properties:
                          teamId:
                            type: array
                            items:
                              type: string
                              format: UID
                example:
                  properties:
                    cksq4ofmx07arhowhtzzdqwxa:
                      cksq5ee6p07fxedwh1pfowuxc: [cksq4xga4078iwgwhn6dwvm2q]
                      cksq5ee5j0776edwhh347ruab:
                        [
                          cksq4y6f700iswjwhhwdsb9mo,
                          cksq4xga4078iwgwhn6dwvm2q,
                          cksq5ev5f00ylw9whbmkwku7z,
                        ]
                    cksq4p0aa070mhowhbw5gomri:
                      cksq5ee6p07fxedwh1pfowuxc: [cksq4xga4078iwgwhn6dwvm2q]
  "/properties/{propertyId}/teamusers/add":
    patch:
      tags:
        - Properties
      summary: Add Property Team Users
      description: |
        Set which users are responsible for teams at this property.
        - Users are added as members of the team if they aren't already. Triggers the team webhook if users are added to the team.
        - Invalid user IDs are silently ignored.
      parameters:
        - in: path
          name: propertyId
          required: true
          schema:
            type: string
            format: UID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - team
                - users
              properties:
                team:
                  type: string
                  format: UID
                users:
                  type: array
                  items:
                    type: string
                    format: UID
                skipWebhook:
                  type: boolean
                  default: false
              example:
                team: cksq5ee6607bwedwhkb6ra827
                users: [cksq50h7g0638hywhasfzw7cd]
      responses:
        "204":
          content: application/json
        "400":
          content:
            application/json:
              schema:
                oneOf:
                  - title: PropertyNotFound
                    properties:
                      code:
                        type: PropertyNotFound
                        example: PropertyNotFound
                  - title: TeamNotFound
                    properties:
                      code:
                        type: TeamNotFound
                        example: TeamNotFound
  "/properties/{propertyId}/teamusers/remove":
    patch:
      tags:
        - Properties
      summary: Remove Property Team Users
      description: |
        Remove users as responsible for teams at this property.
        - Users are unassigned from any tasks they were auto-assigned to.
        - Invalid user IDs are silently ignored.
        - Users are not removed as members of the team.
      parameters:
        - in: path
          name: propertyId
          required: true
          schema:
            type: string
            format: UID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - team
                - users
              properties:
                team:
                  type: string
                  format: UID
                users:
                  type: array
                  items:
                    type: string
                    format: UID
              example:
                team: cksq5ee6607bwedwhkb6ra827
                users: [cksq50h7g0638hywhasfzw7cd]
      responses:
        "204":
          content: application/json
        "400":
          content:
            application/json:
              schema:
                oneOf:
                  - title: PropertyNotFound
                    properties:
                      code:
                        type: PropertyNotFound
                        example: PropertyNotFound
                  - title: TeamNotFound
                    properties:
                      code:
                        type: TeamNotFound
                        example: TeamNotFound

  "/assessments":
    get:
      tags:
        - Assessments
      summary: Get Assessments
      description: |
        Get a list of assessments produced for your organisation or produced by your organisation.
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 1000
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: assessment
          schema:
            type: string
            example: cllks38mw000131wh9ukgjc4g
          description: Comma separated assessment IDs
        - in: query
          name: property
          schema:
            type: string
            example: cksq4ybpq104zwgwh2gd1vvha
          description: Comma separated property IDs
        - in: query
          name: type
          schema:
            type: string
          description: Comma separated assessment types<br>See `GET /assessments/types`
          example: cm65bkfml00kpyjwh84eword,cm65bkfml00koyjwhqz38xwa
        - in: query
          name: performed
          schema:
            type: string
            default: For,By
          example: For
          description: |
            ```For```: list assessments produced **for** your organisation. ```By```: list assessments produced **by** your organisation
        - in: query
          name: status
          schema:
            type: string
            default: approved
          example: inprogress,submitted,approved
          description: |
            Comma separated assessment statuses
        - in: query
          name: includeflags
          schema:
            type: boolean
            default: false
          description: Include assessment flags and their history
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  total:
                    type: integer
                    example: 9231
                  assessments:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        property:
                          type: string
                          description: ID of property this assessment belongs to
                        asset:
                          type: string
                          deprecated: true
                          description: Use `property` instead
                        forOrganisation:
                          type: string
                          description: ID of organisation the assessment was created for
                        byOrganisation:
                          type: string
                          description: ID of organisation that created the assessment
                        reference:
                          type: string
                        customReference:
                          type: string
                        type:
                          type: string
                          description: See `GET /assessments/types`
                        status:
                          type: string
                          enum: [inprogress, submitted, approved]
                        assessedDate:
                          type: date
                          format: Y-m-d
                        approvedDate:
                          type: date
                          format: Y-m-d
                        expiryDate:
                          type: date
                          format: Y-m-d
                        flags:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              name:
                                type: string
                              currentState:
                                type: object
                                nullable: true
                                properties:
                                  isSet:
                                    type: boolean
                                  user:
                                    type: string
                                    format: UID
                                  comment:
                                    type: string
                                  timestamp:
                                    type: timestamp
                                    format: Y-m-d H:i:s
                              history:
                                type: array
                                items:
                                  type: object
                                  properties:
                                    isSet:
                                      type: boolean
                                    user:
                                      type: string
                                      format: UID
                                    comment:
                                      type: string
                                    timestamp:
                                      type: timestamp
                                      format: Y-m-d H:i:s
                    example:
                      - id: cllks38mw000131wh9ukgjc4g
                        property: cksq4ybpq104zwgwh2gd1vvha
                        asset: cksq4ybpq104zwgwh2gd1vvha
                        forOrganisation: clkjwoavd00hj99whnsg8prog
                        byOrganisation: clhracytd002243whodg03shv
                        reference: RB-ABC123
                        customReference: MyAseRef0001
                        type: cm65bkfml00kpyjwh84eword
                        status: inprogress
                        assessedDate: 2024-01-01
                        approvedDate: 2024-01-03
                        expiryDate: 2025-01-01
                        scheduleCustomReference: MyAseSchRef0001
                        flags:
                          [
                            {
                              id: gg00k4cccsokgggggko4scg0,
                              name: Onsite Visit Completed,
                              currentState:
                                {
                                  isSet: true,
                                  user: cksq391qt04f60ns0rplhdmpj,
                                  comment: I've fully completed the visit now,
                                  timestamp: 2025-03-05 12:13:00,
                                },
                              history:
                                [
                                  {
                                    isSet: true,
                                    user: cksq391qt04f60ns0rplhdmpj,
                                    comment: "",
                                    timestamp: 2025-03-05 10:01:25,
                                  },
                                  {
                                    isSet: false,
                                    user: cksq391qt04f60ns0rplhdmpj,
                                    comment: Need to go back for another photo,
                                    timestamp: 2025-03-05 11:25:01,
                                  },
                                  {
                                    isSet: true,
                                    user: cksq391qt04f60ns0rplhdmpj,
                                    comment: I've fully completed the visit now,
                                    timestamp: 2025-03-05 12:13:53,
                                  },
                                ],
                            },
                            {
                              id: i4ssoswwgocggggocgkc4kss,
                              name: Spelling Check,
                              currentState: null,
                              history: [],
                            },
                          ]
                  organisations:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        address:
                          type: object
                          properties:
                            line1:
                              type: string
                            line2:
                              type: string
                            city:
                              type: string
                            county:
                              type: string
                            postcode:
                              type: string
                      example:
                        - id: clkjwoavd00hj99whnsg8prog
                          name: Kenney Housing
                          address:
                            line1: 9 Plant Lane
                            line2: ""
                            city: London
                            county: ""
                            postcode: TW8 1PL
                        - id: clhracytd002243whodg03shv
                          name: Brandon Fire Safety
                          address:
                            line1: ""
                            line2: ""
                            city: ""
                            county: ""
                            postcode: ""
  "/assessments/types":
    get:
      tags:
        - Assessments
      summary: Get Assessment Types
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  types:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        isDeleted:
                          type: boolean
                    example:
                      - id: cm65bkfml00koyjwhqz38xwa
                        name: External Wall Engineer Report
                        isDeleted: false
                      - id: cm65bkfml00kpyjwh84eword
                        name: Fire Risk Assessment
                        isDeleted: false
  "/assessments/{assessmentId}/report.pdf":
    get:
      tags:
        - Assessments
      summary: Get Assessment Report PDF
      description: Get an assessment's report PDF
      parameters:
        - in: path
          name: assessmentId
          required: true
          schema:
            type: string
            format: UID
      responses:
        "200":
          content:
            application/pdf:
              schema:
                type: string
                format: binary
  "/assessments/{assessmentId}/bundle.zip":
    get:
      tags:
        - Assessments
      produces:
        - application/zip
      summary: Get Assessment Bundle ZIP
      description: |
        Get an assessment's bundle ZIP. This bundle contains:<br>
        • Report PDF
        • CSVs of actions, controls, and elements
        • Assessment attachments
        • Images and files for actions, controls, and elements
      parameters:
        - in: path
          name: assessmentId
          required: true
          schema:
            type: string
            format: UID
      responses:
        "200":
          content:
            application/zip:
              schema:
                type: string
                format: binary
  "/assessments/schedules":
    get:
      tags:
        - Assessments
      summary: Get Assessment Schedules
      description: |
        Get a list of assessment schedules
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 1000
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: property
          schema:
            type: string
            format: UID
            example: cksq4ybpq104zwgwh2gd1vvha
          description: Comma separated property IDs
        - in: query
          name: asset
          deprecated: true
          schema:
            type: string
          description: Use `property` instead
        - in: query
          name: type
          schema:
            type: string
            format: UID
          description: Comma separated assessment types<br>See `GET /assessments/types`
          example: cm65bkfml00kpyjwh84eword,cm65bkfml00koyjwhqz38xwa
        - in: query
          name: status
          schema:
            type: string
            enum: [notstarted, inprogress]
            default: notstarted,inprogress
          example: notstarted
          description: Comma separated schedule statuses
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  total:
                    type: integer
                    example: 1
                  schedules:
                    type: array
                    items:
                      type: object
                      properties:
                        property:
                          type: string
                          format: UID
                          description: ID of property this schedule belongs to
                        asset:
                          type: string
                          format: UID
                          deprecated: true
                          description: Use `property` instead
                        type:
                          type: string
                          format: UID
                          description: See `GET /assessments/types`
                        status:
                          type: string
                          enum: [notstarted, inprogress]
                        dueDate:
                          type: date
                          format: Y-m-d
                        description:
                          type: string
                        customReference:
                          type: string
                        assignedUsers:
                          type: array
                          items:
                            type: string
                            format: UID
                    example:
                      - property: cksq4ybpq104zwgwh2gd1vvha
                        asset: cksq4ybpq104zwgwh2gd1vvha
                        type: cm65bkfml00kpyjwh84eword
                        status: notstarted
                        dueDate: "2025-06-01"
                        description: Information for assessment author
                        customReference: MyAseSchRef0001
                        assignedUsers: [cksq4xkxh012173wh9agrq0iz]
  "/assessments/schedules/{property}/{type}":
    get:
      tags:
        - Assessments
      summary: Get Assessment Schedule
      description: Get a property's assessment schedule for a particular assessment type
      parameters:
        - in: path
          name: property
          description: The schedule's property ID
          required: true
          schema:
            type: string
            format: UID
        - in: path
          name: type
          description: The schedule's assessment type ID
          required: true
          schema:
            type: string
            format: UID
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  property:
                    type: string
                    format: UID
                    description: ID of property this schedule belongs to
                  asset:
                    type: string
                    format: UID
                    deprecated: true
                    description: Use `property` instead
                  type:
                    type: string
                    format: UID
                    description: See `GET /assessments/types`
                  status:
                    type: string
                    enum: [notstarted, inprogress]
                  dueDate:
                    type: date
                    format: Y-m-d
                  description:
                    type: string
                  customReference:
                    type: string
                  assignedUsers:
                    type: array
                    items:
                      type: string
                      format: UID
                example:
                  property: cksq4ybpq104zwgwh2gd1vvha
                  asset: cksq4ybpq104zwgwh2gd1vvha
                  type: cm65bkfml00kpyjwh84eword
                  status: notstarted
                  dueDate: "2025-06-01"
                  description: Information for assessment author
                  customReference: MyAseSchRef0001
                  assignedUsers: [cksq4xkxh012173wh9agrq0iz]
        "400":
          content:
            application/json:
              schema:
                oneOf:
                  - title: PropertyNotFound
                    properties:
                      code:
                        type: PropertyNotFound
                        example: PropertyNotFound
                  - title: AssessmentTypeNotFound
                    properties:
                      code:
                        type: AssessmentTypeNotFound
                        example: AssessmentTypeNotFound
        "404":
          content: application/json
          description: No schedule found
    put:
      tags:
        - Assessments
      summary: Create/Update Assessment Schedule
      description: Update a property's assessment schedule if it exists, otherwise create it
      parameters:
        - in: path
          name: property
          description: The schedule's property ID
          required: true
          schema:
            type: string
            format: UID
        - in: path
          name: type
          description: The schedule's assessment type ID
          required: true
          schema:
            type: string
            format: UID
      requestBody:
        content:
          application/json:
            schema:
              required:
                - status
              properties:
                dueDate:
                  type: date
                  format: Y-m-d
                  example: "2025-06-01"
                description:
                  type: string
                  example: Information for assessment author
                customReference:
                  type: string
                  example: MyAseSchRef0001
                  description: |
                    The schedule's custom reference will appear on the assessment as `scheduleCustomReference` in `GET /assessments`
                assignedUsers:
                  type: array
                  items:
                    type: string
                    format: UID
                  example: ["cksq4xkxh012173wh9agrq0iz"]
      responses:
        "204":
          content: application/json
        "400":
          content:
            application/json:
              schema:
                oneOf:
                  - title: PropertyNotFound
                    properties:
                      code:
                        type: PropertyNotFound
                        example: PropertyNotFound
                  - title: AssessmentTypeNotFound
                    properties:
                      code:
                        type: AssessmentTypeNotFound
                        example: AssessmentTypeNotFound
                  - title: UserNotFound
                    properties:
                      code:
                        type: UserNotFound
                        example: UserNotFound
                      error:
                        type: Invalid assigned users [...]
                        example: Invalid assigned users [...]
                  - title: DateInvalid
                    properties:
                      code:
                        type: DateInvalid
                        example: DateInvalid
                      error:
                        type: Invalid due date
                        example: Invalid due date
    delete:
      tags:
        - Assessments
      summary: Delete Assessment Schedule
      description: Delete a property's assessment schedule
      parameters:
        - in: path
          name: property
          description: The schedule's property ID
          required: true
          schema:
            type: string
            format: UID
        - in: path
          name: type
          description: The schedule's assessment type ID
          required: true
          schema:
            type: string
            format: UID
      responses:
        "204":
          content: application/json
        "400":
          content:
            application/json:
              schema:
                oneOf:
                  - title: PropertyNotFound
                    properties:
                      code:
                        type: PropertyNotFound
                        example: PropertyNotFound
                  - title: AssessmentTypeNotFound
                    properties:
                      code:
                        type: AssessmentTypeNotFound
                        example: AssessmentTypeNotFound
  "/tasks":
    get:
      tags:
        - Tasks
      summary: Get Tasks
      description: Returns a list of “Remedial Action“ tasks. Other types, such as “Create Assessment”, are not included.
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 1000
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: task
          schema:
            type: string
            example: cle72jm2q0001pxwhqnf5qfoc
          description: Comma separated task IDs
        - in: query
          name: status
          schema:
            type: string
            default: notstarted,inprogress
          description: Comma separated status IDs<br>See `GET /tasks/statuses`
        - in: query
          name: property
          schema:
            type: string
            example: cksq4ybpq104zwgwh2gd1vvha
          description: Comma separated property IDs
        - in: query
          name: asset
          deprecated: true
          schema:
            type: string
          description: Use `property` instead
        - in: query
          name: includeusers
          schema:
            type: boolean
            default: false
          description: Include names and emails of assigned users
        - in: query
          name: includeteams
          schema:
            type: boolean
            default: false
          description: Include names of assigned teams
        - in: query
          name: includecategories
          schema:
            type: boolean
            default: false
          description: Include names of categories
        - in: query
          name: includeseverities
          schema:
            type: boolean
            default: false
          description: Include names of severities
        - in: query
          name: includetimescales
          schema:
            type: boolean
            default: false
          description: Include names of timescales
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  total:
                    type: integer
                    example: 30341
                  tasks:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: UID
                        property:
                          type: string
                          format: UID
                          description: ID of property this task belongs to
                        asset:
                          type: string
                          format: UID
                          deprecated: true
                          description: Use `property` instead
                        element:
                          type: string
                          nullable: true
                          description: ID of element this task is linked to
                          format: UID
                        reference:
                          type: string
                          format: RB-XXXXXX
                        customReference:
                          type: string
                        status:
                          type: string
                          description: See ``GET /tasks/statuses``
                        what:
                          type: string
                        why:
                          type: string
                        location:
                          type: string
                        dueDate:
                          nullable: true
                          type: date
                          format: Y-m-d
                        category:
                          type: string
                          nullable: true
                          format: UID
                        severity:
                          type: string
                          nullable: true
                          format: UID
                        timescale:
                          type: string
                          nullable: true
                          format: UID
                        assignedTeams:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              manual:
                                type: boolean
                                description: Team manually assigned
                              auto:
                                type: boolean
                                description: Team automatically assigned by category
                        assignedUsers:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              manual:
                                type: boolean
                                description: User manually assigned
                              auto:
                                type: boolean
                                description: User automatically assigned by team
                        photoIds:
                          type: array
                          items:
                            type: string
                            format: UID
                    example:
                      - id: cle72jm2q0001pxwhqnf5qfoc
                        property: cksq4ybpq104zwgwh2gd1vvha
                        asset: cksq4ybpq104zwgwh2gd1vvha
                        element: clo4al25g0004e4wh1j8v2adq
                        reference: RB-ABC123
                        customReference: MyTaskRef0001
                        status: inprogress
                        what: Description of task
                        why: Why the task is required
                        location: Location of task
                        dueDate: "2024-01-01"
                        category: ckuqwxk32011i11oooozx3vc2
                        severity: dkgcscowkkwcwsw0c40c4gcs
                        timescale: scc4o0wc80800gkwg0cc4sk8
                        assignedTeams:
                          - id: cksq3a5ux03nx0ns0jntekwfm
                            manual: true
                            auto: false
                        assignedUsers:
                          - id: cliylzuy600010nl44ox1hsqf
                            manual: false
                            auto: true
                        photoIds:
                          - cksq3jhl500ga0ls0oiibt7q2
                          - cksq3j7tz006v0ls0bn0zeuq8
                  users:
                    type: array
                    description: Present if `includeusers=1`
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: UID
                        email:
                          type: string
                          format: email
                        name:
                          type: string
                  teams:
                    type: array
                    description: Present if `includeteams=1`
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: UID
                        name:
                          type: string
                  categories:
                    type: array
                    description: Present if `includecategories=1`
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: UID
                        name:
                          type: string
                  severities:
                    type: array
                    description: Present if `includeseverities=1`
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: UID
                        name:
                          type: string
                  timescales:
                    type: array
                    description: Present if `includetimescales=1`
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: UID
                        name:
                          type: string
  "/tasks/{task}/status":
    patch:
      tags:
        - Tasks
      summary: Update Task Status
      description: |
        Update a task's status
        - Triggers the `task` webhook.
      parameters:
        - in: path
          name: task
          required: true
          schema:
            type: string
            format: UID
      requestBody:
        content:
          application/json:
            schema:
              required:
                - status
              properties:
                status:
                  description: See ``GET /tasks/statuses``
                  type: string
                  required: true
                  example: "completed"
                user:
                  type: string
                  nullable: true
                  description: Email or ID of the user who performed the change. If not provided or not recognised the update will be applied but the API user will be used instead
                  example: "user.name@example.com"
                comment:
                  type: string
                  nullable: true
                  example: "Combustibles have been removed"
                skipWebhook:
                  type: boolean
                  default: false
      responses:
        "204":
          content: application/json
        "400":
          content:
            application/json:
              schema:
                oneOf:
                  - title: TaskNotFound
                    properties:
                      code:
                        type: TaskNotFound
                        example: TaskNotFound
                      error:
                        type: Task Not Found
                        example: Task Not Found
                  - title: TaskStatusInvalid
                    properties:
                      code:
                        type: TaskStatusInvalid
                        example: TaskStatusInvalid
                      error:
                        type: Task Status Invalid
                        example: Task Status Invalid
    post:
      tags:
        - Tasks
      summary: Update Task Status
      description: |
        See `PATCH: Update Task Status`
      deprecated: true
  "/tasks/statuses":
    get:
      tags:
        - Tasks
      summary: Get Task Statuses
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  statuses:
                    type: array
                    items:
                      type: object
                      properties:
                        name:
                          type: string
                        isIncomplete:
                          type: boolean
                    example:
                      - id: notstarted
                        name: Not Started
                        isIncomplete: true
                      - id: inprogress
                        name: In Progress
                        isIncomplete: true
                      - id: completed
                        name: Completed
                        isIncomplete: false
                      - id: cancelled
                        name: Cancelled
                        isIncomplete: false
  "/properties/assets/types":
    get:
      tags:
        - "Property Assets"
      summary: Get Property Asset Types
      responses:
        "200":
          content:
            application/json:
              schema:
                type: object
                properties:
                  type:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: UID
                        name:
                          type: string
                        nameSingular:
                          type: string
                        fields:
                          type: array
                          items:
                            discriminator:
                              propertyName: type
                            oneOf:
                              - $ref: "#/components/schemas/fieldTypes/text"
                              - $ref: "#/components/schemas/fieldTypes/number"
                              - $ref: "#/components/schemas/fieldTypes/image"
                              - $ref: "#/components/schemas/fieldTypes/file"
                              - $ref: "#/components/schemas/fieldTypes/option"
                              - $ref: "#/components/schemas/fieldTypes/pin"
                              - $ref: "#/components/schemas/fieldTypes/qr"
                example:
                  $ref: "#/components/examples/propertyassets/types"
  "/properties/assets":
    get:
      tags:
        - "Property Assets"
      summary: Get Property Assets
      # description: Get a list of property assets
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 1000
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: type
          schema:
            type: string
            example: Flat Entrance Door,firedoors,cksq3o1qn00j20hs0ayi7qagu
            format: "Comma-Separated: ID or name"
          description: |
            Limit list by asset type. See `GET /properties/assets/types`
        - in: query
          name: id
          schema:
            type: string
            example: cksq3o1qn00j10hs07j31i9l1
            format: "Comma-Separated: ID"
          description: Limit list by assets
        - in: query
          name: property
          schema:
            type: string
            example: cksq4ybpq104zwgwh2gd1vvha
            format: "Comma-Separated: ID"
          description: Limit list by properties
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  total:
                    type: integer
                    example: 1288
                  assets:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: UID
                        property:
                          type: string
                          description: ID of property this element is linked to
                          format: UID
                        type:
                          type: string
                          description: ID of element type
                          format: UID
                        fields:
                          type: array
                          items:
                            discriminator:
                              propertyName: type
                            oneOf:
                              - $ref: "#/components/schemas/fieldResults/text"
                              - $ref: "#/components/schemas/fieldResults/number"
                              - $ref: "#/components/schemas/fieldResults/date"
                              - $ref: "#/components/schemas/fieldResults/time"
                              - $ref: "#/components/schemas/fieldResults/image"
                              - $ref: "#/components/schemas/fieldResults/file"
                              - $ref: "#/components/schemas/fieldResults/option"
                              - $ref: "#/components/schemas/fieldResults/pin"
                              - $ref: "#/components/schemas/fieldResults/qr"
                  types:
                    $ref: "#/components/schemas/propertyassets/types"
                example:
                  $ref: "#/components/examples/propertyassets/list"
  "/properties/{propertyId}/assets":
    post:
      tags:
        - "Property Assets"
      summary: Create Property Asset
      parameters:
        - in: path
          name: propertyId
          required: true
          schema:
            type: string
            format: UID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - type
              properties:
                type:
                  type: string
                  format: UID
                  description: ID of property asset type<br>See `GET /properties/assets/types` for types
                values:
                  type: object
                  description: |
                    Values are not required when creating an asset.

                    Values keyed by field ID<br>See `GET /properties/assets/types` for available fields

                    ```
                    { fieldId1: value, fieldId2: value }
                    ```

                    - **Text Field**<br>
                    `string` or `null` to remove value

                    - **Number Field**<br>
                    `number` or `null` to remove value

                    - **Option Field**<br>
                    `array of option IDs` or `null` to remove value

                    - **Date Field**<br>
                    `string<Y-m-d>` like `2026-02-25` or `null` to remove value

                    - **Time Field**<br>
                    `string<H:i>` like `14:02` or `null` to remove value

                    - **QR Field**<br>
                    `string` or `null` to remove value
            example:
              type: cksq3o1qn00j20hs0ayi7qagu
              values:
                cksq3ocb600mu0hs0qhachlip: Flat 1A
                cksq3oc5y004i0hs0ff0cbyk3:
                  - cloirzzkg00058usq5r0kbhbw
                cksq3ocb900n10hs0249bbdt4: 1
                cksq3ocd0004i0hs0ff0cbyk9: null
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: string
                    format: UID
                    example: yok0w80s0sckwwgo0c8sko4o
        "400":
          content:
            application/json:
              schema:
                oneOf:
                  - title: PropertyIdRequired
                    properties:
                      code:
                        type: PropertyIdRequired
                        example: PropertyIdRequired
                  - title: AssetTypeIdRequired
                    properties:
                      code:
                        type: AssetTypeIdRequired
                        example: AssetTypeIdRequired
                  - title: PropertyAssetValuesInvalidFormat
                    properties:
                      code:
                        type: PropertyAssetValuesInvalidFormat
                        example: PropertyAssetValuesInvalidFormat
                  - title: PropertyNotFound
                    properties:
                      code:
                        type: PropertyNotFound
                        example: PropertyNotFound
                  - title: AssetTypeNotFound
                    properties:
                      code:
                        type: AssetTypeNotFound
                        example: AssetTypeNotFound
                  - title: FieldInvalidNotSupported
                    properties:
                      code:
                        type: FieldInvalidNotSupported
                        example: FieldInvalidNotSupported
                  - title: PropertyAssetValuesInvalid
                    properties:
                      code:
                        type: PropertyAssetValuesInvalid
                        example: PropertyAssetValuesInvalid
  "/properties/{propertyId}/assets/{assetId}":
    patch:
      tags:
        - "Property Assets"
      summary: Update Property Asset
      parameters:
        - in: path
          name: propertyId
          required: true
          schema:
            type: string
            format: UID
        - in: path
          name: assetId
          required: true
          schema:
            type: string
            format: UID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - values
              properties:
                values:
                  type: object
                  description: |
                    Values keyed by field ID<br>See `GET /properties/assets/types` for available fields

                    ```
                    { fieldId1: value, fieldId2: value }
                    ```

                    - **Text Field**<br>
                    `string` or `null` to remove value

                    - **Number Field**<br>
                    `number` or `null` to remove value

                    - **Option Field**<br>
                    `array of option IDs` or `null` to remove value

                    - **Date Field**<br>
                    `string<Y-m-d>` like `2026-02-25` or `null` to remove value

                    - **Time Field**<br>
                    `string<H:i>` like `14:02` or `null` to remove value

                    - **QR Field**<br>
                    `string` or `null` to remove value
            example:
              values:
                cksq3ocb600mu0hs0qhachlip: Flat 1B
                cksq3oc5y004i0hs0ff0cbyk3:
                  - cloirzzkp00068usqc2as5d93
                cksq3ocb900n10hs0249bbdt4: 0
      responses:
        "204":
          content: application/json
        "400":
          content:
            application/json:
              schema:
                oneOf:
                  - title: PropertyIdRequired
                    properties:
                      code:
                        type: PropertyIdRequired
                        example: PropertyIdRequired
                  - title: PropertyAssetIdRequired
                    properties:
                      code:
                        type: PropertyAssetIdRequired
                        example: PropertyAssetIdRequired
                  - title: PropertyAssetValuesInvalidFormat
                    properties:
                      code:
                        type: PropertyAssetValuesInvalidFormat
                        example: PropertyAssetValuesInvalidFormat
                  - title: PropertyNotFound
                    properties:
                      code:
                        type: PropertyNotFound
                        example: PropertyNotFound
                  - title: PropertyAssetNotFound
                    properties:
                      code:
                        type: PropertyAssetNotFound
                        example: PropertyAssetNotFound
                  - title: FieldInvalidNotSupported
                    properties:
                      code:
                        type: FieldInvalidNotSupported
                        example: FieldInvalidNotSupported
                  - title: PropertyAssetValuesInvalid
                    properties:
                      code:
                        type: PropertyAssetValuesInvalid
                        example: PropertyAssetValuesInvalid
  "/plans":
    get:
      tags:
        - Plans
      summary: Get Plans
      description: |
        To get a plan's file, use the `GET: Get Plan` endpoint.
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 1000
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: property
          schema:
            type: string
            example: cksq4ybpq104zwgwh2gd1vvha
          description: Comma separated property IDs
        - in: query
          name: asset
          deprecated: true
          schema:
            type: string
          description: Use `property` instead
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  total:
                    type: integer
                    example: 130
                  plans:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: UID
                        property:
                          type: string
                          description: ID of property this plan is linked to
                          format: UID
                        asset:
                          type: string
                          deprecated: true
                          description: Use `property` instead
                          format: UID
                        name:
                          type: string
                        description:
                          type: string
                        type:
                          type: string
                          enum: [floor, elevation, environs]
                        data:
                          discriminator:
                            propertyName: type
                          oneOf:
                            - $ref: "#/components/schemas/planTypeGroup/svg"
                            - $ref: "#/components/schemas/planTypeGroup/pdf"
                            - $ref: "#/components/schemas/planTypeGroup/image"
                    example:
                      - id: vs8wco44wosgssscww4o880c
                        property: cksq4ybpq104zwgwh2gd1vvha
                        asset: cksq4ybpq104zwgwh2gd1vvha
                        name: Ground Floor
                        description: This plan shows the ground floor of the building
                        type: floor
                        data:
                          type: image
                          format: jpeg
                          width: 1920
                          height: 1080
  "/plans/{plan}":
    get:
      tags:
        - Plans
      summary: Get Plan
      description: Get plan info and file (PDF, SVG, Image)
      parameters:
        - in: path
          name: plan
          required: true
          schema:
            type: string
            format: UID
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: string
                    format: UID
                  property:
                    type: string
                    description: ID of property this plan is linked to
                    format: UID
                  asset:
                    type: string
                    description: Use `property` instead
                    deprecated: true
                    format: UID
                  name:
                    type: string
                  description:
                    type: string
                  type:
                    type: string
                    enum: [floor, elevation, environs]
                  data:
                    discriminator:
                      propertyName: type
                    oneOf:
                      - $ref: "#/components/schemas/planTypeGroupWithContent/svg"
                      - $ref: "#/components/schemas/planTypeGroupWithContent/pdf"
                      - $ref: "#/components/schemas/planTypeGroupWithContent/image"
              example:
                - id: vs8wco44wosgssscww4o880c
                  property: cksq4ybpq104zwgwh2gd1vvha
                  asset: cksq4ybpq104zwgwh2gd1vvha
                  name: Ground Floor
                  description: This plan shows the ground floor of the building
                  type: floor
                  data:
                    type: image
                    format: jpeg
                    width: 1920
                    height: 1080
                    base64Content: "..."
  "/files/{fileId}":
    get:
      tags:
        - Files
      summary: Get File
      description: Get info and Base64 content of a file
      parameters:
        - in: path
          name: fileId
          required: true
          schema:
            type: string
            format: UID
        - in: query
          name: includeBase64
          description: Include Base64 encoded content
          schema:
            type: boolean
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  title:
                    type: string
                  size:
                    type: integer
                  width:
                    type: integer
                  height:
                    type: integer
                  mime:
                    type: string
                    enum:
                      [
                        "application/acad",
                        "application/msword",
                        "application/octet-stream",
                        "application/pdf",
                        "application/postscript",
                        "application/vnd.ms-excel",
                        "application/vnd.ms-excel.sheet.macroEnabled.12",
                        "application/vnd.ms-outlook",
                        "application/vnd.ms-powerpoint",
                        "application/vnd.openxmlformats-officedocument.presentationml.presentation",
                        "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
                        "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
                        "application/x-rar-compressed",
                        "application/zip",
                        "image/bmp",
                        "image/gif",
                        "image/heic",
                        "image/jpeg",
                        "image/png",
                        "image/svg+xml",
                        "image/tiff",
                        "message/rfc822",
                        "text/csv; charset=utf-8",
                        "text/plain",
                        "text/rtf",
                        "text/xml",
                        "video/mp4",
                        "video/mpeg",
                        "video/quicktime",
                        "video/webm",
                        "...",
                      ]
                  extension:
                    type: string
                    enum:
                      [
                        "bmp",
                        "csv",
                        "doc",
                        "docx",
                        "dwg",
                        "eml",
                        "file",
                        "gif",
                        "heic",
                        "jpeg",
                        "mov",
                        "mp4",
                        "mpeg",
                        "msg",
                        "pdf",
                        "png",
                        "ppt",
                        "pptx",
                        "ps",
                        "rar",
                        "rtf",
                        "svg",
                        "tiff",
                        "txt",
                        "webm",
                        "xls",
                        "xlsm",
                        "xlsx",
                        "xml",
                        "zip",
                        "...",
                      ]
                  base64Content:
                    type: string
                    format: byte
              example:
                - title: "File Name.jpeg"
                  size: 108357
                  width: 1024
                  height: 768
                  mime: "image/jpeg"
                  extension: "jpeg"
                  base64Content: "..."
  "/files/{fileId}/binary":
    get:
      tags:
        - Files
      summary: Get File Binary
      description: Get the binary of a file
      parameters:
        - in: path
          name: fileId
          required: true
          schema:
            type: string
            format: UID
      responses:
        "200":
          content:
            mime/type:
              schema:
                type: string
                format: binary
  "/elements":
    get:
      deprecated: true
      tags:
        - Elements
      summary: Get Elements
      # description: Get a list of elements
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 1000
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: type
          schema:
            type: string
            example: Flat Entrance Door,firedoors,cksq3o1qn00j20hs0ayi7qagu
            format: "Comma-Separated: ID or name"
          description: |
            Limit list by property asset type. See `GET /properties/assets/types`
        - in: query
          name: id
          schema:
            type: string
            example: cksq3o1qn00j10hs07j31i9l1
            format: "Comma-Separated: ID"
          description: Limit list by elements
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  total:
                    type: integer
                    example: 1288
                  elements:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: UID
                        property:
                          type: string
                          description: ID of property this element is linked to
                          format: UID
                        asset:
                          type: string
                          deprecated: true
                          description: Use `property` instead
                          format: UID
                        type:
                          type: string
                          description: ID of element type
                          format: UID
                        fields:
                          type: array
                          items:
                            discriminator:
                              propertyName: type
                            oneOf:
                              - $ref: "#/components/schemas/fieldResults/text"
                              - $ref: "#/components/schemas/fieldResults/number"
                              - $ref: "#/components/schemas/fieldResults/date"
                              - $ref: "#/components/schemas/fieldResults/time"
                              - $ref: "#/components/schemas/fieldResults/image"
                              - $ref: "#/components/schemas/fieldResults/file"
                              - $ref: "#/components/schemas/fieldResults/option"
                              - $ref: "#/components/schemas/fieldResults/pin"
                              - $ref: "#/components/schemas/fieldResults/qr"
                  types:
                    $ref: "#/components/schemas/elements/types"
                example:
                  $ref: "#/components/examples/elements/list"
  "/elements/types":
    get:
      deprecated: true
      tags:
        - Elements
      summary: Get Element Types
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  types:
                    $ref: "#/components/schemas/elements/types"
                example:
                  $ref: "#/components/examples/elements/types"

  # OLD ASSETS

  "/assets/groups":
    get:
      deprecated: true
      tags:
        - Assets
      summary: Get Asset Groups
      # description: Get a list of asset groups
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 1000
        - in: query
          name: page
          schema:
            type: integer
            default: 1
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  total:
                    type: integer
                    example: 50
                  assetGroups:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: UID
                        name:
                          type: string
                        reference:
                          type: string
                        customReference:
                          type: string
                    example:
                      - id: cksq39rnv02vf0ns0t3o834uv
                        name: London South
                        reference: RB-Z0LMKJ
                        customReference:
  "/assets":
    get:
      deprecated: true
      tags:
        - Assets
      summary: Get Assets
      # description: Get a list of assets
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 1000
        - in: query
          name: page
          schema:
            type: integer
            default: 1
        - in: query
          name: asset
          schema:
            type: string
            example: cksq4ybpq104zwgwh2gd1vvha
          description: Comma separated asset IDs
        - in: query
          name: customreference
          schema:
            type: string
            example: CustomReference1,CustomReference2
          description: Comma separated asset custom references
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  total:
                    type: integer
                    example: 9250
                  assets:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        reference:
                          type: string
                        customReference:
                          type: string
                        photoId:
                          nullable: true
                          type: string
                        address:
                          type: object
                          properties:
                            line1:
                              type: string
                            line2:
                              type: string
                            city:
                              type: string
                            county:
                              type: string
                            postcode:
                              type: string
                    example:
                      - id: cksq4ybpq104zwgwh2gd1vvha
                        name: Demo Asset
                        reference: RB-ABC123
                        customReference: YourUprn0001
                        photoId: cksq3jhl500ga0ls0oiibt7q2,
                        address:
                          line1: 33 Magnolia Avenue
                          line2: ""
                          city: London
                          county: ""
                          postcode: SW10 2BT
    post:
      deprecated: true
      tags:
        - Assets
      summary: Create Asset
      description: |
        - Triggers the `asset` webhook.
      # description: Create an asset
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  required: true
                parentAsset:
                  type: string
                  nullable: true,
                  format: UID
                  description: Parent asset or asset group ID. If null is provided, the asset will be created in an asset group called "Created by API"
                customReference:
                  type: string
                address:
                  type: object
                  properties:
                    line1:
                      type: string
                    line2:
                      type: string
                    city:
                      type: string
                    county:
                      type: string
                    postcode:
                      type: string
                skipWebhook:
                  type: boolean
                  default: false
              example:
                parentAsset: u400ko8sk848gc40kss400sg
                name: Building 1
                customReference: B000001
                address:
                  line1: 101 Wood Lane
                  city: London
                  postcode: W12 7FA
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: string
                    format: UID
                    example: yok0w80s0sckwwgo0c8sko4o
        "400":
          content:
            application/json:
              schema:
                oneOf:
                  - title: AssetCreateNameRequired
                    properties:
                      code:
                        type: AssetCreateNameRequired
                        example: AssetCreateNameRequired
                  - title: AssetCreateInvalidParent
                    properties:
                      code:
                        type: AssetCreateInvalidParent
                        example: AssetCreateInvalidParent
  "/assets/tree":
    get:
      deprecated: true
      tags:
        - Assets
      summary: Get Asset Tree
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  tree:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        name:
                          type: string
                        type:
                          type: enum
                          enum: [Organisation, Asset Group, Asset]
                        children:
                          type: array
                          description: Recurring tree
                          items:
                            type: object
                            properties:
                              id:
                                type: string
                              name:
                                type: string
                              type:
                                type: enum
                                enum: [Organisation, Asset Group, Asset]
                              children:
                                type: array
                                description: Recurring tree
                                items:
                                  type: object
                    example:
                      tree:
                        - id: cl8br0oe40001kkwhdglcu74r
                          name: Fox Residential
                          type: Organisation
                          children:
                            - id: cl8br1p900001mgwhcpbhopcp
                              name: Manchester
                              type: Asset Group
                              children:
                                - id: cl8br4pnc0001opwhfidszqwt
                                  name: Blonde Retreat
                                  type: Asset
                                  children: []
                                - id: cl8br4pph0003opwhouu2j0ew
                                  name: The Blade Building
                                  type: Asset
                                  children: []
  "/assets/{assetId}":
    patch:
      deprecated: true
      tags:
        - Assets
      summary: Update Asset
      description: |
        Update an asset's name and address.
        - Triggers the `asset` webhook.
      parameters:
        - in: path
          name: assetId
          required: true
          schema:
            type: string
            format: UID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                customReference:
                  type: string
                address:
                  type: object
                  properties:
                    line1:
                      type: string
                    line2:
                      type: string
                    city:
                      type: string
                    county:
                      type: string
                    postcode:
                      type: string
                skipWebhook:
                  type: boolean
                  default: false
              example:
                parentAsset: u400ko8sk848gc40kss400sg
                name: Building 1
                customReference: B000001
                address:
                  line1: 101 Wood Lane
                  city: London
                  postcode: W12 7FA
      responses:
        "204":
          content: application/json
        "400":
          content:
            application/json:
              schema:
                oneOf:
                  - title: AssetNotFound
                    properties:
                      code:
                        type: AssetNotFound
                        example: AssetNotFound
  "/assets/{assetId}/parent":
    patch:
      deprecated: true
      tags:
        - Assets
      summary: Move Asset
      description: |
        Move an asset to a different position in the asset tree; either below an asset group or another asset.
        - Triggers the `asset` webhook.
      parameters:
        - in: path
          name: assetId
          required: true
          schema:
            type: string
            format: UID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - parentAsset
              properties:
                parentAsset:
                  type: string
                  format: UID
                skipWebhook:
                  type: boolean
                  default: false
              example:
                parentAsset: u400ko8sk848gc40kss400sg
      responses:
        "204":
          content: application/json
        "400":
          content:
            application/json:
              schema:
                oneOf:
                  - title: PropertyNotFound
                    properties:
                      code:
                        type: PropertyNotFound
                        example: PropertyNotFound
                  - title: PropertyParentNotFound
                    properties:
                      code:
                        type: PropertyParentNotFound
                        example: PropertyParentNotFound
                  - title: PropertyMoveParentIsChild
                    properties:
                      code:
                        type: PropertyMoveParentIsChild
                        example: PropertyMoveParentIsChild
                      error:
                        type: Parent property is currently a child of the property being moved
                        example: Parent property is currently a child of the property being moved
                  - title: PropertyMoveInvalidParentPropertyGroup
                    properties:
                      code:
                        type: PropertyMoveInvalidParentPropertyGroup
                        example: PropertyMoveInvalidParentPropertyGroup
                      error:
                        type: Property groups can only exist under an organisation or another property group
                        example: Property groups can only exist under an organisation or another property group
                  - title: PropertyMoveInvalidParentProperty
                    properties:
                      code:
                        type: PropertyMoveInvalidParentProperty
                        example: PropertyMoveInvalidParentProperty
                      error:
                        type: Property can only exist under a property group or another property
                        example: Property can only exist under a property group or another property
  "/assets/teamusers":
    get:
      deprecated: true
      tags:
        - Assets
      summary: Get Asset Team Users
      description: |
        Get a list of users responsible for teams for all assets in your organisation.
        - Responsible users are auto-assigned to tasks that are assigned to their team.
        - Users are automatically given access to assets they are responsible for.
      parameters:
        - in: query
          name: asset
          schema:
            type: string
            format: UID
            example: cksq4ybpq104zwgwh2gd1vvha
          description: Comma separated asset IDs
        - in: query
          name: user
          schema:
            type: string
            format: UID
            example: cksq4xkxh012173wh9agrq0iz
          description: Comma separated user IDs
        - in: query
          name: includeinherited
          schema:
            type: boolean
            default: false
            example: true
          description: Responsibility is inherited down the asset tree. By default this endpoint will list responsbility which has been set explicitly. Set this to true to include inherited responsibility.
      responses:
        "200":
          content:
            application/json:
              schema:
                properties:
                  assets:
                    type: object
                    properties:
                      assetId:
                        type: object
                        properties:
                          teamId:
                            type: array
                            items:
                              type: string
                              format: UID
                example:
                  assets:
                    cksq4ofmx07arhowhtzzdqwxa:
                      cksq5ee6p07fxedwh1pfowuxc: [cksq4xga4078iwgwhn6dwvm2q]
                      cksq5ee5j0776edwhh347ruab:
                        [
                          cksq4y6f700iswjwhhwdsb9mo,
                          cksq4xga4078iwgwhn6dwvm2q,
                          cksq5ev5f00ylw9whbmkwku7z,
                        ]
                    cksq4p0aa070mhowhbw5gomri:
                      cksq5ee6p07fxedwh1pfowuxc: [cksq4xga4078iwgwhn6dwvm2q]
  "/assets/{assetId}/teamusers/add":
    patch:
      deprecated: true
      tags:
        - Assets
      summary: Add Asset Team Users
      description: |
        Set which users are responsible for teams at this asset.
        - Users are added as members of the team if they aren't already. Triggers the team webhook if users are added to the team.
        - Invalid user IDs are silently ignored.
      parameters:
        - in: path
          name: assetId
          required: true
          schema:
            type: string
            format: UID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - team
                - users
              properties:
                team:
                  type: string
                  format: UID
                users:
                  type: array
                  items:
                    type: string
                    format: UID
                skipWebhook:
                  type: boolean
                  default: false
              example:
                team: cksq5ee6607bwedwhkb6ra827
                users: [cksq50h7g0638hywhasfzw7cd]
      responses:
        "204":
          content: application/json
        "400":
          content:
            application/json:
              schema:
                oneOf:
                  - title: AssetNotFound
                    properties:
                      code:
                        type: AssetNotFound
                        example: AssetNotFound
                  - title: TeamNotFound
                    properties:
                      code:
                        type: TeamNotFound
                        example: TeamNotFound
  "/assets/{assetId}/teamusers/remove":
    patch:
      deprecated: true
      tags:
        - Assets
      summary: Remove Asset Team Users
      description: |
        Remove users as responsible for teams at this asset.
        - Users are unassigned from any tasks they were auto-assigned to.
        - Invalid user IDs are silently ignored.
        - Users are not removed as members of the team.
      parameters:
        - in: path
          name: assetId
          required: true
          schema:
            type: string
            format: UID
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - team
                - users
              properties:
                team:
                  type: string
                  format: UID
                users:
                  type: array
                  items:
                    type: string
                    format: UID
              example:
                team: cksq5ee6607bwedwhkb6ra827
                users: [cksq50h7g0638hywhasfzw7cd]
      responses:
        "204":
          content: application/json
        "400":
          content:
            application/json:
              schema:
                oneOf:
                  - title: AssetNotFound
                    properties:
                      code:
                        type: AssetNotFound
                        example: AssetNotFound
                  - title: TeamNotFound
                    properties:
                      code:
                        type: TeamNotFound
                        example: TeamNotFound

definitions:
  Category:
    type: object
    properties:
      id:
        type: integer
        format: int64
      name:
        type: string
    xml:
      name: Category
