{
  "openapi": "3.1.0",
  "info": {
    "title": "Latchkey API",
    "version": "2026-10-14",
    "description": "Bookings, arrivals, guest requests and messages for your Latchkey properties."
  },
  "servers": [
    {
      "url": "https://latchkey.omsestates.uk/api/public/v1"
    }
  ],
  "components": {
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "A Latchkey API key (lk_…), from Settings → API & MCP."
      }
    }
  },
  "paths": {
    "/properties": {
      "get": {
        "operationId": "list_properties",
        "summary": "List properties",
        "description": "Every property in your business, with its short link and check-in times.",
        "security": [
          {
            "bearer": []
          }
        ],
        "x-latchkey-scope": "read",
        "parameters": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "data": [
                    {
                      "id": "6f1c…",
                      "name": "The Hill Suites",
                      "short_code": "hill",
                      "check_in_from": "15:00",
                      "check_out_by": "11:00"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong API key"
          },
          "403": {
            "description": "Key can't do this, or the API isn't on your plan"
          },
          "429": {
            "description": "Monthly request allowance used up"
          }
        }
      }
    },
    "/properties/{property_id}/rooms": {
      "get": {
        "operationId": "list_rooms",
        "summary": "List rooms",
        "description": "The rooms in a property, with how many people each sleeps.",
        "security": [
          {
            "bearer": []
          }
        ],
        "x-latchkey-scope": "read",
        "parameters": [
          {
            "name": "property_id",
            "in": "path",
            "required": true,
            "description": "The property's id from List properties.",
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "The property's id from List properties."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "data": [
                    {
                      "id": "2a9b…",
                      "name": "Suite 1",
                      "sleeps": 2,
                      "children_allowed": true
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong API key"
          },
          "403": {
            "description": "Key can't do this, or the API isn't on your plan"
          },
          "429": {
            "description": "Monthly request allowance used up"
          }
        }
      }
    },
    "/bookings": {
      "get": {
        "operationId": "list_bookings",
        "summary": "List bookings",
        "description": "Stays overlapping a date range, newest arrival first. Defaults to the next 30 days.",
        "security": [
          {
            "bearer": []
          }
        ],
        "x-latchkey-scope": "read",
        "parameters": [
          {
            "name": "property_id",
            "in": "query",
            "required": false,
            "description": "Only this property.",
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Only this property."
            }
          },
          {
            "name": "from",
            "in": "query",
            "required": false,
            "description": "First night to include (YYYY-MM-DD). Default: today.",
            "schema": {
              "type": "string",
              "format": "date",
              "description": "First night to include (YYYY-MM-DD). Default: today."
            }
          },
          {
            "name": "to",
            "in": "query",
            "required": false,
            "description": "Last night to include (YYYY-MM-DD). Default: 30 days on.",
            "schema": {
              "type": "string",
              "format": "date",
              "description": "Last night to include (YYYY-MM-DD). Default: 30 days on."
            }
          },
          {
            "name": "status",
            "in": "query",
            "required": false,
            "description": "Only stays with this status.",
            "schema": {
              "type": "string",
              "description": "Only stays with this status.",
              "enum": [
                "needs_details",
                "upcoming",
                "checked_in",
                "checked_out",
                "cancelled",
                "flagged",
                "blocked"
              ]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Up to 200. Default 50.",
            "schema": {
              "type": "integer",
              "description": "Up to 200. Default 50."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "data": [
                    {
                      "id": "b81e…",
                      "property_id": "6f1c…",
                      "room": "Suite 1",
                      "guest_name": "Priya Shah",
                      "check_in": "2026-10-16",
                      "check_out": "2026-10-18",
                      "nights": 2,
                      "guests": 2,
                      "status": "upcoming",
                      "booked_on": "airbnb",
                      "reference": "HM4K2P"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong API key"
          },
          "403": {
            "description": "Key can't do this, or the API isn't on your plan"
          },
          "429": {
            "description": "Monthly request allowance used up"
          }
        }
      },
      "post": {
        "operationId": "create_booking",
        "summary": "Add a direct booking",
        "description": "Adds a stay booked directly with you (not through a booking site).",
        "security": [
          {
            "bearer": []
          }
        ],
        "x-latchkey-scope": "write",
        "parameters": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "property_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Which property."
                  },
                  "room_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Which room (from List rooms)."
                  },
                  "guest_name": {
                    "type": "string",
                    "description": "The guest's full name."
                  },
                  "check_in": {
                    "type": "string",
                    "format": "date",
                    "description": "Arrival date (YYYY-MM-DD)."
                  },
                  "check_out": {
                    "type": "string",
                    "format": "date",
                    "description": "Departure date (YYYY-MM-DD)."
                  },
                  "guests": {
                    "type": "integer",
                    "description": "How many people. Default 1."
                  },
                  "email": {
                    "type": "string",
                    "description": "The guest's email, used to confirm who they are at check-in."
                  },
                  "amount": {
                    "type": "number",
                    "description": "What the guest paid, in your currency (e.g. 180.00). Used for invoices."
                  },
                  "notes": {
                    "type": "string",
                    "description": "Anything to remember about the stay."
                  }
                },
                "required": [
                  "property_id",
                  "guest_name",
                  "check_in",
                  "check_out"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "id": "c2d4…",
                    "status": "upcoming"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong API key"
          },
          "403": {
            "description": "Key can't do this, or the API isn't on your plan"
          },
          "429": {
            "description": "Monthly request allowance used up"
          }
        }
      }
    },
    "/bookings/{booking_id}": {
      "get": {
        "operationId": "get_booking",
        "summary": "Get a booking",
        "description": "One stay in full, including who's staying and whether they've checked in.",
        "security": [
          {
            "bearer": []
          }
        ],
        "x-latchkey-scope": "read",
        "parameters": [
          {
            "name": "booking_id",
            "in": "path",
            "required": true,
            "description": "The booking's id.",
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "The booking's id."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "id": "b81e…",
                    "guest_name": "Priya Shah",
                    "status": "checked_in",
                    "checked_in_at": "2026-10-16T15:42:00Z",
                    "adults": 2,
                    "children": 0
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong API key"
          },
          "403": {
            "description": "Key can't do this, or the API isn't on your plan"
          },
          "429": {
            "description": "Monthly request allowance used up"
          }
        }
      },
      "patch": {
        "operationId": "update_booking",
        "summary": "Change a booking",
        "description": "Changes a stay's guest details, room, status or notes. Only what you send is changed.",
        "security": [
          {
            "bearer": []
          }
        ],
        "x-latchkey-scope": "write",
        "parameters": [
          {
            "name": "booking_id",
            "in": "path",
            "required": true,
            "description": "The booking's id.",
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "The booking's id."
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "guest_name": {
                    "type": "string",
                    "description": "The guest's full name."
                  },
                  "email": {
                    "type": "string",
                    "description": "The guest's email."
                  },
                  "room_id": {
                    "type": "string",
                    "format": "uuid",
                    "description": "Move to this room."
                  },
                  "status": {
                    "type": "string",
                    "description": "New status.",
                    "enum": [
                      "upcoming",
                      "checked_in",
                      "checked_out",
                      "cancelled"
                    ]
                  },
                  "notes": {
                    "type": "string",
                    "description": "Replaces the stay's notes."
                  }
                },
                "required": [],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "id": "c2d4…",
                    "status": "upcoming"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong API key"
          },
          "403": {
            "description": "Key can't do this, or the API isn't on your plan"
          },
          "429": {
            "description": "Monthly request allowance used up"
          }
        }
      }
    },
    "/arrivals": {
      "get": {
        "operationId": "todays_arrivals",
        "summary": "Today at a glance",
        "description": "Who arrives, who leaves and who's staying on a given day (default today, in each property's time zone).",
        "security": [
          {
            "bearer": []
          }
        ],
        "x-latchkey-scope": "read",
        "parameters": [
          {
            "name": "date",
            "in": "query",
            "required": false,
            "description": "The day (YYYY-MM-DD). Default: today.",
            "schema": {
              "type": "string",
              "format": "date",
              "description": "The day (YYYY-MM-DD). Default: today."
            }
          },
          {
            "name": "property_id",
            "in": "query",
            "required": false,
            "description": "Only this property.",
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "Only this property."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "date": "2026-10-14",
                    "arriving": [
                      {
                        "guest_name": "Jean Dupont",
                        "room": "Garden Room"
                      }
                    ],
                    "leaving": [],
                    "staying": []
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong API key"
          },
          "403": {
            "description": "Key can't do this, or the API isn't on your plan"
          },
          "429": {
            "description": "Monthly request allowance used up"
          }
        }
      }
    },
    "/requests": {
      "get": {
        "operationId": "list_requests",
        "summary": "Guest requests",
        "description": "Extras and problems guests have asked about, newest first.",
        "security": [
          {
            "bearer": []
          }
        ],
        "x-latchkey-scope": "read",
        "parameters": [
          {
            "name": "open_only",
            "in": "query",
            "required": false,
            "description": "Only ones still waiting on you. Default true.",
            "schema": {
              "type": "boolean",
              "description": "Only ones still waiting on you. Default true."
            }
          },
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "description": "Up to 100. Default 30.",
            "schema": {
              "type": "integer",
              "description": "Up to 100. Default 30."
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "data": [
                    {
                      "id": "9e…",
                      "kind": "extras",
                      "guest_name": "Priya Shah",
                      "what": "2 × Fresh towels",
                      "status": "new",
                      "created_at": "2026-10-14T09:12:00Z"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong API key"
          },
          "403": {
            "description": "Key can't do this, or the API isn't on your plan"
          },
          "429": {
            "description": "Monthly request allowance used up"
          }
        }
      }
    },
    "/bookings/{booking_id}/messages": {
      "post": {
        "operationId": "send_guest_message",
        "summary": "Message a guest",
        "description": "Sends a message to the guest's stay page, as you.",
        "security": [
          {
            "bearer": []
          }
        ],
        "x-latchkey-scope": "write",
        "parameters": [
          {
            "name": "booking_id",
            "in": "path",
            "required": true,
            "description": "The booking's id.",
            "schema": {
              "type": "string",
              "format": "uuid",
              "description": "The booking's id."
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "message": {
                    "type": "string",
                    "description": "What to say (up to 2,000 characters)."
                  }
                },
                "required": [
                  "message"
                ],
                "additionalProperties": false
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "id": "m1…",
                    "sent_at": "2026-10-14T10:03:00Z"
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong API key"
          },
          "403": {
            "description": "Key can't do this, or the API isn't on your plan"
          },
          "429": {
            "description": "Monthly request allowance used up"
          }
        }
      }
    },
    "/usage": {
      "get": {
        "operationId": "get_usage",
        "summary": "Your API usage",
        "description": "Requests made this month and how many your plan includes.",
        "security": [
          {
            "bearer": []
          }
        ],
        "x-latchkey-scope": "read",
        "parameters": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "example": {
                  "data": {
                    "month": "2026-10",
                    "requests": 1240,
                    "included": 10000
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing or wrong API key"
          },
          "403": {
            "description": "Key can't do this, or the API isn't on your plan"
          },
          "429": {
            "description": "Monthly request allowance used up"
          }
        }
      }
    }
  }
}