{
  "openapi": "3.1.0",
  "info": {
    "title": "RentorStay Customer API",
    "version": "1.0.0",
    "description": "Customer-owned, expiring API credentials. Permissions are checked against current account access on every request. Keys never authorize billing, security settings, access grants, contract signatures or deletion. Store credentials in your integration secret manager, never in chat prompts. Mutation retries must reuse the same Idempotency-Key and body."
  },
  "servers": [
    {
      "url": "https://vzqtfobsqqqcijsbwesm.supabase.co/functions/v1/customer-api/v1"
    }
  ],
  "security": [
    {
      "ApiKey": []
    }
  ],
  "components": {
    "securitySchemes": {
      "ApiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "RentorStay API key"
      }
    }
  },
  "paths": {
    "/me": {
      "get": {
        "operationId": "getConnection",
        "summary": "Verify the key and inspect granted permissions",
        "responses": {
          "200": {
            "description": "Connection identity and scopes"
          },
          "401": {
            "description": "Invalid, expired or revoked key"
          }
        }
      }
    },
    "/actions": {
      "post": {
        "operationId": "executeRentorStayAction",
        "summary": "Run an authorized RentorStay operation",
        "parameters": [
          {
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9_-]{8,100}$"
            },
            "description": "Required for writes. Use a new value for each intended change and reuse it for retries."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "operation",
                      "payload"
                    ],
                    "properties": {
                      "operation": {
                        "type": "string",
                        "const": "properties.list"
                      },
                      "payload": {
                        "type": "object",
                        "properties": {},
                        "required": [],
                        "additionalProperties": false
                      }
                    },
                    "description": "List properties available to this account. Required scope: properties:read."
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "operation",
                      "payload"
                    ],
                    "properties": {
                      "operation": {
                        "type": "string",
                        "const": "inventory.list"
                      },
                      "payload": {
                        "type": "object",
                        "properties": {
                          "property_id": {
                            "type": "string",
                            "format": "uuid"
                          }
                        },
                        "required": [
                          "property_id"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "description": "Read materials, tools and locations for one authorized property. Required scope: inventory:read."
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "operation",
                      "payload"
                    ],
                    "properties": {
                      "operation": {
                        "type": "string",
                        "const": "inventory.save"
                      },
                      "payload": {
                        "oneOf": [
                          {
                            "type": "object",
                            "properties": {
                              "property_id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "action": {
                                "type": "string",
                                "const": "create"
                              },
                              "data": {
                                "type": "object",
                                "properties": {
                                  "name": {
                                    "type": "string",
                                    "minLength": 1,
                                    "maxLength": 120
                                  },
                                  "description": {
                                    "type": "string"
                                  },
                                  "category": {
                                    "type": "string"
                                  },
                                  "unit": {
                                    "type": "string"
                                  },
                                  "purchased_from": {
                                    "type": "string"
                                  },
                                  "purchase_date": {
                                    "type": "string",
                                    "format": "date"
                                  },
                                  "serial_number": {
                                    "type": "string"
                                  },
                                  "asset_tag": {
                                    "type": "string"
                                  },
                                  "condition": {
                                    "type": "string",
                                    "enum": [
                                      "new",
                                      "good",
                                      "fair",
                                      "damaged",
                                      "needs_repair"
                                    ]
                                  },
                                  "photo_document_id": {
                                    "type": "string",
                                    "format": "uuid",
                                    "description": "Existing authorized image uploaded by this account through the app."
                                  },
                                  "remove_photo": {
                                    "type": "boolean"
                                  },
                                  "item_type": {
                                    "type": "string",
                                    "enum": [
                                      "material",
                                      "tool"
                                    ]
                                  },
                                  "quantity": {
                                    "type": "number",
                                    "minimum": 0
                                  },
                                  "location_id": {
                                    "type": "string",
                                    "format": "uuid"
                                  },
                                  "new_location_name": {
                                    "type": "string",
                                    "description": "Required only when location_id is omitted. Use inventory.list to find an existing location."
                                  }
                                },
                                "required": [
                                  "name",
                                  "item_type"
                                ],
                                "additionalProperties": false
                              }
                            },
                            "required": [
                              "property_id",
                              "action",
                              "data"
                            ],
                            "additionalProperties": false
                          },
                          {
                            "type": "object",
                            "properties": {
                              "property_id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "action": {
                                "type": "string",
                                "const": "update"
                              },
                              "data": {
                                "type": "object",
                                "properties": {
                                  "name": {
                                    "type": "string",
                                    "minLength": 1,
                                    "maxLength": 120
                                  },
                                  "description": {
                                    "type": "string"
                                  },
                                  "category": {
                                    "type": "string"
                                  },
                                  "unit": {
                                    "type": "string"
                                  },
                                  "purchased_from": {
                                    "type": "string"
                                  },
                                  "purchase_date": {
                                    "type": "string",
                                    "format": "date"
                                  },
                                  "serial_number": {
                                    "type": "string"
                                  },
                                  "asset_tag": {
                                    "type": "string"
                                  },
                                  "condition": {
                                    "type": "string",
                                    "enum": [
                                      "new",
                                      "good",
                                      "fair",
                                      "damaged",
                                      "needs_repair"
                                    ]
                                  },
                                  "photo_document_id": {
                                    "type": "string",
                                    "format": "uuid",
                                    "description": "Existing authorized image uploaded by this account through the app."
                                  },
                                  "remove_photo": {
                                    "type": "boolean"
                                  },
                                  "item_id": {
                                    "type": "string",
                                    "format": "uuid"
                                  },
                                  "location_id": {
                                    "type": "string",
                                    "format": "uuid"
                                  }
                                },
                                "required": [
                                  "item_id",
                                  "name"
                                ],
                                "additionalProperties": false
                              }
                            },
                            "required": [
                              "property_id",
                              "action",
                              "data"
                            ],
                            "additionalProperties": false
                          },
                          {
                            "type": "object",
                            "properties": {
                              "property_id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "action": {
                                "type": "string",
                                "const": "count"
                              },
                              "data": {
                                "type": "object",
                                "properties": {
                                  "item_id": {
                                    "type": "string",
                                    "format": "uuid"
                                  },
                                  "location_id": {
                                    "type": "string",
                                    "format": "uuid"
                                  },
                                  "quantity": {
                                    "type": "number",
                                    "minimum": 0
                                  },
                                  "note": {
                                    "type": "string",
                                    "minLength": 1
                                  }
                                },
                                "required": [
                                  "item_id",
                                  "location_id",
                                  "quantity",
                                  "note"
                                ],
                                "additionalProperties": false
                              }
                            },
                            "required": [
                              "property_id",
                              "action",
                              "data"
                            ],
                            "additionalProperties": false
                          },
                          {
                            "type": "object",
                            "properties": {
                              "property_id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "action": {
                                "type": "string",
                                "const": "location_create"
                              },
                              "data": {
                                "type": "object",
                                "properties": {
                                  "name": {
                                    "type": "string"
                                  }
                                },
                                "required": [
                                  "name"
                                ],
                                "additionalProperties": false
                              }
                            },
                            "required": [
                              "property_id",
                              "action",
                              "data"
                            ],
                            "additionalProperties": false
                          }
                        ],
                        "description": "Read inventory.list before editing. Updates replace description/category, so preserve those fields from the existing record. Tool quantity is one per asset."
                      }
                    },
                    "description": "Create or edit a material/tool, adjust a count, or create a location. Existing property edit permission is required. Required scope: inventory:write; changes data."
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "operation",
                      "payload"
                    ],
                    "properties": {
                      "operation": {
                        "type": "string",
                        "const": "vehicles.list"
                      },
                      "payload": {
                        "type": "object",
                        "properties": {},
                        "required": [],
                        "additionalProperties": false
                      }
                    },
                    "description": "List authorized work vehicles. Required scope: vehicles:read."
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "operation",
                      "payload"
                    ],
                    "properties": {
                      "operation": {
                        "type": "string",
                        "const": "vehicles.save"
                      },
                      "payload": {
                        "oneOf": [
                          {
                            "type": "object",
                            "properties": {
                              "property_id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "action": {
                                "type": "string",
                                "const": "create"
                              },
                              "data": {
                                "type": "object",
                                "properties": {
                                  "name": {
                                    "type": "string"
                                  },
                                  "license_plate": {
                                    "type": "string"
                                  },
                                  "license_region": {
                                    "type": "string"
                                  },
                                  "make": {
                                    "type": "string"
                                  },
                                  "model": {
                                    "type": "string"
                                  },
                                  "model_year": {
                                    "type": "integer"
                                  },
                                  "color": {
                                    "type": "string"
                                  },
                                  "odometer_unit": {
                                    "type": "string",
                                    "enum": [
                                      "mile",
                                      "km"
                                    ]
                                  },
                                  "initial_odometer": {
                                    "type": "number",
                                    "minimum": 0
                                  },
                                  "notes": {
                                    "type": "string"
                                  },
                                  "photo_document_id": {
                                    "type": "string",
                                    "format": "uuid"
                                  },
                                  "remove_photo": {
                                    "type": "boolean"
                                  }
                                },
                                "required": [
                                  "name",
                                  "license_plate",
                                  "odometer_unit",
                                  "initial_odometer"
                                ],
                                "additionalProperties": false
                              }
                            },
                            "required": [
                              "property_id",
                              "action",
                              "data"
                            ],
                            "additionalProperties": false
                          },
                          {
                            "type": "object",
                            "properties": {
                              "property_id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "action": {
                                "type": "string",
                                "const": "update"
                              },
                              "data": {
                                "type": "object",
                                "properties": {
                                  "name": {
                                    "type": "string"
                                  },
                                  "license_plate": {
                                    "type": "string"
                                  },
                                  "license_region": {
                                    "type": "string"
                                  },
                                  "make": {
                                    "type": "string"
                                  },
                                  "model": {
                                    "type": "string"
                                  },
                                  "model_year": {
                                    "type": "integer"
                                  },
                                  "color": {
                                    "type": "string"
                                  },
                                  "odometer_unit": {
                                    "type": "string",
                                    "enum": [
                                      "mile",
                                      "km"
                                    ]
                                  },
                                  "initial_odometer": {
                                    "type": "number",
                                    "minimum": 0
                                  },
                                  "notes": {
                                    "type": "string"
                                  },
                                  "photo_document_id": {
                                    "type": "string",
                                    "format": "uuid"
                                  },
                                  "remove_photo": {
                                    "type": "boolean"
                                  },
                                  "vehicle_id": {
                                    "type": "string",
                                    "format": "uuid"
                                  }
                                },
                                "required": [
                                  "vehicle_id",
                                  "name",
                                  "license_plate",
                                  "odometer_unit",
                                  "initial_odometer"
                                ],
                                "additionalProperties": false
                              }
                            },
                            "required": [
                              "property_id",
                              "action",
                              "data"
                            ],
                            "additionalProperties": false
                          }
                        ],
                        "description": "Read vehicles.list and preserve fields when updating. Odometer baseline/unit cannot change once mileage is recorded."
                      }
                    },
                    "description": "Create or update a work vehicle. Required scope: vehicles:write; changes data."
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "operation",
                      "payload"
                    ],
                    "properties": {
                      "operation": {
                        "type": "string",
                        "const": "notes.list"
                      },
                      "payload": {
                        "type": "object",
                        "properties": {},
                        "required": [],
                        "additionalProperties": false
                      }
                    },
                    "description": "Read owner notes or the notes explicitly shared with this vendor. Required scope: notes:read."
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "operation",
                      "payload"
                    ],
                    "properties": {
                      "operation": {
                        "type": "string",
                        "const": "notes.create"
                      },
                      "payload": {
                        "type": "object",
                        "properties": {
                          "property_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "subject": {
                            "type": "string"
                          },
                          "body": {
                            "type": "string"
                          },
                          "entity_type": {
                            "type": "string"
                          },
                          "entity_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "anchor_key": {
                            "type": "string"
                          },
                          "visibility": {
                            "type": "string",
                            "enum": [
                              "owner_private",
                              "management_shared"
                            ],
                            "description": "Defaults to owner_private. Use only a sharing option explicitly requested by the account owner."
                          },
                          "vendor_id": {
                            "type": "string",
                            "format": "uuid"
                          }
                        },
                        "required": [
                          "property_id",
                          "subject",
                          "body"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "description": "Owner: add a private or explicitly shared contextual note. Required scope: notes:write; changes data."
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "operation",
                      "payload"
                    ],
                    "properties": {
                      "operation": {
                        "type": "string",
                        "const": "notes.progress"
                      },
                      "payload": {
                        "type": "object",
                        "properties": {
                          "note_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "status": {
                            "type": "string",
                            "enum": [
                              "in_progress",
                              "done"
                            ]
                          },
                          "note": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "note_id",
                          "status"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "description": "Vendor: update an assigned note. Required scope: notes:write; changes data."
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "operation",
                      "payload"
                    ],
                    "properties": {
                      "operation": {
                        "type": "string",
                        "const": "owner.summary"
                      },
                      "payload": {
                        "type": "object",
                        "properties": {},
                        "required": [],
                        "additionalProperties": false
                      }
                    },
                    "description": "Owner: read your portfolio summary within current financial and property permissions. Required scope: owner:read."
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "operation",
                      "payload"
                    ],
                    "properties": {
                      "operation": {
                        "type": "string",
                        "const": "resident.summary"
                      },
                      "payload": {
                        "type": "object",
                        "properties": {},
                        "required": [],
                        "additionalProperties": false
                      }
                    },
                    "description": "Resident: read your rent, lease and maintenance summary. Required scope: resident:read."
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "operation",
                      "payload"
                    ],
                    "properties": {
                      "operation": {
                        "type": "string",
                        "const": "maintenance.list"
                      },
                      "payload": {
                        "type": "object",
                        "properties": {},
                        "required": [],
                        "additionalProperties": false
                      }
                    },
                    "description": "Vendor: read your assigned work and current operational summary. Required scope: maintenance:read."
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "operation",
                      "payload"
                    ],
                    "properties": {
                      "operation": {
                        "type": "string",
                        "const": "maintenance.progress"
                      },
                      "payload": {
                        "type": "object",
                        "properties": {
                          "work_order_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "action": {
                            "type": "string",
                            "enum": [
                              "en_route",
                              "arrived",
                              "no_access"
                            ]
                          },
                          "note": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "work_order_id",
                          "action"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "description": "Vendor: update assigned work using the normal acceptance and evidence rules. Required scope: maintenance:write; changes data."
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "operation",
                      "payload"
                    ],
                    "properties": {
                      "operation": {
                        "type": "string",
                        "const": "messages.list"
                      },
                      "payload": {
                        "type": "object",
                        "properties": {},
                        "required": [],
                        "additionalProperties": false
                      }
                    },
                    "description": "List authorized property conversation threads (latest 100). Required scope: messages:read."
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "operation",
                      "payload"
                    ],
                    "properties": {
                      "operation": {
                        "type": "string",
                        "const": "messages.read"
                      },
                      "payload": {
                        "type": "object",
                        "properties": {
                          "thread_id": {
                            "type": "string",
                            "format": "uuid"
                          }
                        },
                        "required": [
                          "thread_id"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "description": "Read one authorized property conversation. Required scope: messages:read."
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "operation",
                      "payload"
                    ],
                    "properties": {
                      "operation": {
                        "type": "string",
                        "const": "messages.send"
                      },
                      "payload": {
                        "type": "object",
                        "properties": {
                          "thread_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "body": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "thread_id",
                          "body"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "description": "Send an in-app message in a thread where your account may write. Existing approvals still apply. Required scope: messages:write; changes data."
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "operation",
                      "payload"
                    ],
                    "properties": {
                      "operation": {
                        "type": "string",
                        "const": "tasks.list"
                      },
                      "payload": {
                        "type": "object",
                        "properties": {},
                        "required": [],
                        "additionalProperties": false
                      }
                    },
                    "description": "Manager: list authorized operational tasks (latest 100). Required scope: tasks:read."
                  },
                  {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "operation",
                      "payload"
                    ],
                    "properties": {
                      "operation": {
                        "type": "string",
                        "const": "tasks.create"
                      },
                      "payload": {
                        "type": "object",
                        "properties": {
                          "title": {
                            "type": "string"
                          },
                          "description": {
                            "type": "string"
                          },
                          "property_id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "due_at": {
                            "type": "string",
                            "format": "date-time"
                          },
                          "priority": {
                            "type": "string",
                            "enum": [
                              "low",
                              "normal",
                              "high",
                              "urgent"
                            ]
                          }
                        },
                        "required": [
                          "title"
                        ],
                        "additionalProperties": false
                      }
                    },
                    "description": "Manager: create an operational task. Required scope: tasks:write; changes data."
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Successful operation; data and request_id"
          },
          "400": {
            "description": "Invalid request or operation rejected"
          },
          "401": {
            "description": "Invalid key"
          },
          "403": {
            "description": "Insufficient key or current account permissions"
          },
          "409": {
            "description": "Idempotency conflict"
          },
          "429": {
            "description": "Rate limit: 60/minute and 10,000/day per key"
          }
        }
      }
    }
  }
}