{
 "openapi": "3.0.3",
 "info": {
  "title": "Bramble HR API",
  "version": "2026-11-13",
  "description": "Bramble HR: the people directory and org chart, time off (requests, approvals, balances, adjustments and dated allowance changes), documents with acknowledgements, and onboarding and leaver checklists. HR policy, leave types and checklist templates are in the [Admin Centre API](/apps/admin/api/hr).\n"
 },
 "servers": [
  {
   "url": "https://{org}.brambleit.cloud/hr",
   "variables": {
    "org": {
     "default": "your-org"
    }
   }
  }
 ],
 "components": {
  "securitySchemes": {
   "apiKey": {
    "type": "apiKey",
    "in": "header",
    "name": "X-API-Key"
   },
   "session": {
    "type": "apiKey",
    "in": "cookie",
    "name": "sso_session"
   },
   "bearer": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "JWT"
   }
  }
 },
 "tags": [
  {
   "name": "People",
   "description": "The directory, one person's record, new starters, removing people, and emergency contacts."
  },
  {
   "name": "Time off",
   "description": "Balances, requests and approvals, previews (how many days a request would use), the team calendar, adjustments, and dated allowance changes.\n"
  },
  {
   "name": "Documents",
   "description": "A person's documents (contracts, right-to-work…) and company documents people must acknowledge. Files are stored encrypted in Bramble.\n"
  },
  {
   "name": "Checklists",
   "description": "Onboarding and leaver checklists made from templates, their tasks, and your own open tasks."
  }
 ],
 "paths": {
  "/api/me": {
   "get": {
    "tags": [
     "People"
    ],
    "summary": "Who you are: the signed-in person and what they can do here",
    "operationId": "get-api-me",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "user": {
           "type": "object",
           "properties": {
            "id": {
             "type": "integer"
            },
            "name": {
             "type": "string"
            },
            "first_name": {
             "type": "string"
            },
            "email": {
             "type": "string"
            }
           }
          },
          "me": {},
          "is_admin": {
           "type": "boolean"
          },
          "is_manager": {
           "type": "boolean"
          },
          "team_size": {
           "type": "integer"
          },
          "settings": {
           "type": "object",
           "properties": {
            "year_start_month": {},
            "bank_holidays": {
             "type": "array",
             "items": {}
            },
            "region": {},
            "region_name": {
             "type": "string"
            },
            "half_days": {
             "type": "boolean"
            },
            "show_leave_types": {
             "type": "boolean"
            },
            "default_allowance": {},
            "carry_over_max": {},
            "overlap_mode": {}
           }
          },
          "leave_types": {
           "type": "array",
           "items": {}
          },
          "counts": {
           "type": "object",
           "properties": {
            "approvals": {
             "type": "integer"
            },
            "tasks": {
             "type": "integer"
            },
            "to_ack": {}
           }
          },
          "today": {}
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/people": {
   "get": {
    "tags": [
     "People"
    ],
    "summary": "The directory",
    "operationId": "get-api-people",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "people": {
           "type": "array",
           "items": {}
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "post": {
    "tags": [
     "People"
    ],
    "summary": "New starter (before their account exists) — HR admins only",
    "operationId": "post-api-people",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [],
    "responses": {
     "201": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "id": {
           "type": "integer"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Give their first and last name"
     },
     "403": {
      "description": "Only HR admins can add people"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "first_name": {
          "type": "string"
         },
         "last_name": {
          "type": "string"
         },
         "work_email": {
          "type": "string"
         },
         "manager_id": {
          "type": "number"
         },
         "personal_email": {
          "type": "string"
         },
         "job_title": {
          "type": "string"
         },
         "department": {
          "type": "string"
         },
         "location": {
          "type": "string"
         },
         "start_date": {
          "type": "string",
          "format": "date"
         },
         "employment_type": {
          "type": "string"
         },
         "contract_type": {
          "type": "string"
         },
         "work_days": {
          "type": "integer"
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/people/{id}": {
   "get": {
    "tags": [
     "People"
    ],
    "summary": "Get a person's HR record",
    "operationId": "get-api-people-id",
    "description": "What you see depends on who you are — HR admins see everything, managers see their reports' work details, everyone sees the directory card.\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {}
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "patch": {
    "tags": [
     "People"
    ],
    "summary": "Update a person's HR record",
    "operationId": "patch-api-people-id",
    "description": "Send only the fields to change. People can change their own `preferred_name`, `pronouns`, `personal_email`, `personal_phone`, `work_phone`, `date_of_birth`, `address`, `ni_number` and `bio`. HR admins can also change `first_name`, `last_name`, `work_email`, `job_title`, `department`, `location`, `manager_id`, `employee_number`, `start_date`, `end_date`, `leaving_reason`, `probation_end`, `employment_type`, `contract_type`, `work_days`, `hours_per_week` and `hr_notes`. Allowances change through `POST /api/leave/allowance-changes`.\n\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "That … isn't valid"
     },
     "403": {
      "description": "You can't change this person's details"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "k": {}
        }
       }
      }
     }
    }
   },
   "delete": {
    "tags": [
     "People"
    ],
    "summary": "Remove someone from HR (a mistake, a duplicate, a service account)",
    "operationId": "delete-api-people-id",
    "description": "Remove someone from HR (a mistake, a duplicate, a service account). Their account isn't touched and the sync won't add them back; BRM-Admin → HR can. Leavers should get a last day instead, which keeps them listed.\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "You can't remove yourself from HR"
     },
     "403": {
      "description": "Only HR admins can remove people"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/people/{id}/contacts": {
   "post": {
    "tags": [
     "People"
    ],
    "summary": "Add an emergency contact",
    "operationId": "post-api-people-id-contacts",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "201": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "id": {
           "type": "integer"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Give their name"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "name": {
          "type": "string"
         },
         "phone": {
          "type": "string"
         },
         "email": {
          "type": "string"
         },
         "relationship": {
          "type": "string"
         }
        },
        "required": [
         "phone",
         "email"
        ]
       }
      }
     }
    }
   }
  },
  "/api/people/{id}/contacts/{cid}": {
   "put": {
    "tags": [
     "People"
    ],
    "summary": "Update an emergency contact",
    "operationId": "put-api-people-id-contacts-cid",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "cid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Give their name"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "name": {
          "type": "string"
         },
         "relationship": {
          "type": "string"
         },
         "phone": {
          "type": "string"
         },
         "email": {
          "type": "string"
         }
        }
       }
      }
     }
    }
   },
   "delete": {
    "tags": [
     "People"
    ],
    "summary": "Remove an emergency contact",
    "operationId": "delete-api-people-id-contacts-cid",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "cid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/activity": {
   "get": {
    "tags": [
     "People"
    ],
    "summary": "Recent HR activity",
    "operationId": "get-api-activity",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "activity": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "employee_id": {},
             "actor_name": {},
             "action": {
              "type": "string"
             },
             "detail": {
              "type": "string",
              "nullable": true
             },
             "created_at": {
              "type": "string",
              "format": "date-time"
             }
            }
           }
          }
         }
        }
       }
      }
     },
     "403": {
      "description": "HR admins only"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/leave/balance": {
   "get": {
    "tags": [
     "Time off"
    ],
    "summary": "A person's time-off balance",
    "operationId": "get-api-leave-balance",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [
     {
      "name": "employee",
      "in": "query",
      "required": false,
      "schema": {},
      "description": "The person (default you)."
     },
     {
      "name": "date",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "format": "date"
      },
      "description": "The leave year containing this date (default today)."
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "balance": {}
         }
        }
       }
      }
     },
     "403": {
      "description": "You can't see this person's time off"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/leave/requests": {
   "get": {
    "tags": [
     "Time off"
    ],
    "summary": "List time-off requests",
    "operationId": "get-api-leave-requests",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [
     {
      "name": "scope",
      "in": "query",
      "required": false,
      "schema": {},
      "description": "`mine` (default), `approvals` (waiting for you to decide), or a person's with `employee`."
     },
     {
      "name": "employee",
      "in": "query",
      "required": false,
      "schema": {},
      "description": "The person."
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "requests": {
           "type": "array",
           "items": {}
          }
         }
        }
       }
      }
     },
     "403": {
      "description": "You can't see this person's time off"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "post": {
    "tags": [
     "Time off"
    ],
    "summary": "Request time off",
    "operationId": "post-api-leave-requests",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [],
    "responses": {
     "201": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "id": {
           "type": "integer"
          },
          "status": {
           "type": "string"
          },
          "days": {
           "type": "array",
           "items": {}
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Choose the type of time off"
     },
     "403": {
      "description": "You can't book time off for this person"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "employee_id": {
          "type": "integer",
          "description": "Who it's for (default you; HR and managers can book for others)."
         },
         "type_id": {
          "type": "integer",
          "description": "The leave type."
         },
         "note": {
          "type": "string",
          "description": "A note for the approver."
         },
         "start_date": {
          "description": "First day."
         },
         "end_date": {
          "description": "Last day."
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/leave/preview": {
   "post": {
    "tags": [
     "Time off"
    ],
    "summary": "How many days a request would use",
    "operationId": "post-api-leave-preview",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {}
       }
      }
     },
     "400": {
      "description": "Choose the type of time off"
     },
     "403": {
      "description": "You can't book time off for this person"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "employee_id": {
          "type": "integer"
         },
         "type_id": {
          "type": "integer"
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/leave/requests/{id}/decide": {
   "post": {
    "tags": [
     "Time off"
    ],
    "summary": "Approve or decline time off",
    "operationId": "post-api-leave-requests-id-decide",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "This request has already been …"
     },
     "403": {
      "description": "You can't approve this person's time off"
     },
     "409": {
      "description": "Approving this would take … to … days in …. Approve anyway?"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "approve": {
          "description": "`true` to approve, `false` to decline."
         },
         "note": {
          "description": "A note for the person."
         },
         "override": {
          "description": "Approve even though it goes over their balance."
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/leave/requests/{id}/cancel": {
   "post": {
    "tags": [
     "Time off"
    ],
    "summary": "Cancel time off",
    "operationId": "post-api-leave-requests-id-cancel",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "This request is already …"
     },
     "403": {
      "description": "You can't cancel this person's time off"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/leave/adjustments": {
   "post": {
    "tags": [
     "Time off"
    ],
    "summary": "Add or take away days",
    "operationId": "post-api-leave-adjustments",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [],
    "responses": {
     "201": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Give a number of days (use a minus for fewer)"
     },
     "403": {
      "description": "Only HR admins can adjust allowances"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "employee_id": {
          "type": "integer",
          "description": "The person."
         },
         "days": {
          "type": "number",
          "description": "Days to add (negative to take away)."
         },
         "reason": {
          "type": "string",
          "description": "Why."
         },
         "date": {
          "type": "string",
          "format": "date",
          "description": "Which leave year it counts in."
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/leave/adjustments/{id}": {
   "delete": {
    "tags": [
     "Time off"
    ],
    "summary": "Remove an adjustment",
    "operationId": "delete-api-leave-adjustments-id",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "403": {
      "description": "Only HR admins can adjust allowances"
     },
     "404": {
      "description": "Adjustment not found"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/leave/allowance-changes": {
   "post": {
    "tags": [
     "Time off"
    ],
    "summary": "From a leave year on, someone's allowance is `days` a year ('set') or `days` on top of the policy ('extra')",
    "operationId": "post-api-leave-allowance-changes",
    "description": "From a leave year on, someone's allowance is `days` a year ('set') or `days` on top of the policy ('extra'). One change per person per year: saving another for the same year replaces it.\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [],
    "responses": {
     "201": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Give a number of days"
     },
     "403": {
      "description": "Only HR admins can change allowances"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "employee_id": {
          "type": "integer"
         },
         "kind": {
          "type": "string"
         },
         "days": {
          "type": "number"
         },
         "from": {
          "type": "string",
          "format": "date"
         },
         "reason": {
          "type": "string"
         }
        },
        "required": [
         "days",
         "from"
        ]
       }
      }
     }
    }
   }
  },
  "/api/leave/allowance-changes/{id}": {
   "delete": {
    "tags": [
     "Time off"
    ],
    "summary": "Remove an allowance change",
    "operationId": "delete-api-leave-allowance-changes-id",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "403": {
      "description": "Only HR admins can change allowances"
     },
     "404": {
      "description": "Allowance change not found"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/leave/calendar": {
   "get": {
    "tags": [
     "Time off"
    ],
    "summary": "Who's off when",
    "operationId": "get-api-leave-calendar",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [
     {
      "name": "from",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "format": "date"
      },
      "description": "First date."
     },
     {
      "name": "to",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string",
       "format": "date"
      },
      "description": "Last date."
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "from": {},
          "to": {},
          "days": {
           "type": "array",
           "items": {}
          },
          "entries": {
           "type": "array",
           "items": {}
          },
          "people": {
           "type": "array",
           "items": {}
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/leave/types": {
   "get": {
    "tags": [
     "Time off"
    ],
    "summary": "Leave types",
    "operationId": "get-api-leave-types",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "types": {
           "type": "array",
           "items": {}
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/documents": {
   "get": {
    "tags": [
     "Documents"
    ],
    "summary": "List documents",
    "operationId": "get-api-documents",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [
     {
      "name": "employee",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "A person's documents (leave out for company documents)."
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {}
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "post": {
    "tags": [
     "Documents"
    ],
    "summary": "Upload a document",
    "operationId": "post-api-documents",
    "description": "`multipart/form-data` with the file and the fields below.\n\nRequires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [],
    "responses": {
     "201": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "id": {
           "type": "integer"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Choose a file"
     },
     "403": {
      "description": "Only HR admins can add company documents"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "multipart/form-data": {
       "schema": {
        "type": "object",
        "properties": {
         "employee_id": {
          "type": "string",
          "description": "The person (leave out for a company document)."
         },
         "category": {
          "description": "Its category."
         },
         "title": {
          "type": "string",
          "description": "Its title."
         },
         "visible_to_employee": {
          "type": "string",
          "description": "Let the person see it."
         },
         "requires_ack": {
          "type": "string",
          "description": "People must acknowledge they've read it."
         },
         "expires_on": {
          "type": "string",
          "format": "date",
          "description": "When it expires (e.g. a visa)."
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/documents/expiring": {
   "get": {
    "tags": [
     "Documents"
    ],
    "summary": "HR: documents expiring in the next 60 days or already expired",
    "operationId": "get-api-documents-expiring",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "documents": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "employee_name": {
              "type": "string"
             }
            }
           }
          }
         }
        }
       }
      }
     },
     "403": {
      "description": "HR admins only"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/documents/{id}/file": {
   "get": {
    "tags": [
     "Documents"
    ],
    "summary": "Download a document",
    "operationId": "get-api-documents-id-file",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     },
     {
      "name": "download",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/documents/{id}": {
   "patch": {
    "tags": [
     "Documents"
    ],
    "summary": "Update a document's details",
    "operationId": "patch-api-documents-id",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Give it a title"
     },
     "403": {
      "description": "Only HR admins can change documents"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "title": {
          "type": "string"
         },
         "category": {},
         "visible_to_employee": {},
         "requires_ack": {},
         "expires_on": {
          "type": "string",
          "format": "date"
         }
        }
       }
      }
     }
    }
   },
   "delete": {
    "tags": [
     "Documents"
    ],
    "summary": "Delete a document",
    "operationId": "delete-api-documents-id",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "403": {
      "description": "You can't delete this document"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/documents/{id}/ack": {
   "post": {
    "tags": [
     "Documents"
    ],
    "summary": "Acknowledge a document",
    "operationId": "post-api-documents-id-ack",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "You don't have an HR record yet"
     },
     "403": {
      "description": "This is not your document"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/documents/{id}/acks": {
   "get": {
    "tags": [
     "Documents"
    ],
    "summary": "HR: who has and hasn't acknowledged a company document",
    "operationId": "get-api-documents-id-acks",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "people": {
           "type": "array",
           "items": {}
          }
         }
        }
       }
      }
     },
     "403": {
      "description": "HR admins only"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/checklists": {
   "get": {
    "tags": [
     "Checklists"
    ],
    "summary": "List checklists",
    "operationId": "get-api-checklists",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [
     {
      "name": "employee",
      "in": "query",
      "required": false,
      "schema": {
       "type": "number"
      },
      "description": "A person's checklists."
     },
     {
      "name": "include",
      "in": "query",
      "required": false,
      "schema": {
       "type": "string"
      },
      "description": "`closed` to include finished and cancelled ones."
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "checklists": {
           "type": "array",
           "items": {}
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "post": {
    "tags": [
     "Checklists"
    ],
    "summary": "Start a checklist",
    "operationId": "post-api-checklists",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [],
    "responses": {
     "201": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "id": {
           "type": "integer"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Choose a checklist"
     },
     "403": {
      "description": "Only HR admins can start checklists"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "employee_id": {
          "type": "integer",
          "description": "The person."
         },
         "template_id": {
          "type": "number",
          "description": "The template."
         },
         "anchor_date": {
          "type": "string",
          "format": "date",
          "description": "The date tasks' due dates count from (start or leaving date)."
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/checklists/tasks/mine": {
   "get": {
    "tags": [
     "Checklists"
    ],
    "summary": "Open tasks that are the viewer's to do, across every checklist",
    "operationId": "get-api-checklists-tasks-mine",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "tasks": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "id": {
              "type": "integer",
              "nullable": true
             },
             "tenant_id": {
              "type": "integer"
             },
             "checklist_id": {
              "type": "integer"
             },
             "title": {
              "type": "string"
             },
             "details": {
              "type": "string",
              "nullable": true
             },
             "assignee": {
              "type": "string",
              "enum": [
               "hr",
               "manager",
               "employee"
              ]
             },
             "assignee_employee_id": {
              "type": "integer",
              "nullable": true
             },
             "done_at": {
              "type": "string",
              "format": "date-time",
              "nullable": true
             },
             "done_by": {
              "type": "integer",
              "nullable": true
             },
             "done_by_name": {
              "type": "string",
              "nullable": true
             },
             "sort": {
              "type": "integer"
             },
             "employee_id": {
              "type": "integer"
             },
             "kind": {
              "type": "string",
              "enum": [
               "onboarding",
               "offboarding"
              ]
             },
             "checklist_name": {
              "type": "string"
             },
             "employee_name": {
              "type": "string"
             }
            }
           }
          }
         }
        }
       }
      }
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/checklists/templates": {
   "get": {
    "tags": [
     "Checklists"
    ],
    "summary": "Checklist templates",
    "operationId": "get-api-checklists-templates",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "templates": {
           "type": "array",
           "items": {
            "type": "object",
            "properties": {
             "id": {
              "type": "integer",
              "nullable": true
             },
             "kind": {
              "type": "string",
              "enum": [
               "onboarding",
               "offboarding"
              ]
             },
             "name": {
              "type": "string"
             },
             "description": {
              "type": "string",
              "nullable": true
             },
             "tasks": {
              "type": "boolean"
             }
            }
           }
          }
         }
        }
       }
      }
     },
     "403": {
      "description": "HR admins only"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/checklists/{id}": {
   "get": {
    "tags": [
     "Checklists"
    ],
    "summary": "Get a checklist",
    "operationId": "get-api-checklists-id",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "checklist": {
           "type": "array",
           "items": {}
          },
          "tasks": {
           "type": "array",
           "items": {}
          }
         }
        }
       }
      }
     },
     "404": {
      "description": "Checklist not found"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   },
   "delete": {
    "tags": [
     "Checklists"
    ],
    "summary": "Cancel a checklist",
    "operationId": "delete-api-checklists-id",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "403": {
      "description": "Only HR admins can cancel checklists"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  },
  "/api/checklists/{id}/tasks": {
   "post": {
    "tags": [
     "Checklists"
    ],
    "summary": "Add a task",
    "operationId": "post-api-checklists-id-tasks",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "integer"
      }
     }
    ],
    "responses": {
     "201": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "400": {
      "description": "Give the task a title"
     },
     "403": {
      "description": "Only HR admins can add tasks"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "title": {
          "type": "string"
         },
         "assignee": {
          "description": "Who does it (HR, the manager, the person, IT…)."
         },
         "details": {
          "type": "string"
         },
         "due_date": {
          "type": "string",
          "format": "date",
          "description": "When it's due."
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/checklists/tasks/{tid}/toggle": {
   "post": {
    "tags": [
     "Checklists"
    ],
    "summary": "Tick or untick a task",
    "operationId": "post-api-checklists-tasks-tid-toggle",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [
     {
      "name": "tid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          },
          "complete": {}
         }
        }
       }
      }
     },
     "400": {
      "description": "This checklist was cancelled"
     },
     "403": {
      "description": "This task isn't yours to tick off"
     },
     "404": {
      "description": "Task not found"
     }
    },
    "security": [
     {
      "session": []
     }
    ],
    "requestBody": {
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "properties": {
         "done": {
          "type": "boolean",
          "description": "`true` or `false`."
         }
        }
       }
      }
     }
    }
   }
  },
  "/api/checklists/tasks/{tid}": {
   "delete": {
    "tags": [
     "Checklists"
    ],
    "summary": "Delete a task",
    "operationId": "delete-api-checklists-tasks-tid",
    "description": "Requires: Signed-in browser session (the `sso_session` / `session_id` cookies from Bramble sign-in). Licence: HR.",
    "parameters": [
     {
      "name": "tid",
      "in": "path",
      "required": true,
      "schema": {
       "type": "number"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Success",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "ok": {
           "type": "boolean"
          }
         }
        }
       }
      }
     },
     "403": {
      "description": "Only HR admins can remove tasks"
     },
     "404": {
      "description": "Task not found"
     }
    },
    "security": [
     {
      "session": []
     }
    ]
   }
  }
 }
}