{
  "openapi": "3.0.3",
  "info": {
    "title": "Vertex Warehouse API",
    "version": "1.0.0",
    "description": "Vertex Warehouse (asset / inventory system). Vocabulary: Assets · Reservations · Locations · Stock. Records are Assets, identified by asset_tag (e.g. VX-88213). Identifiers this system emits: asset_tag, employee_no. No authentication."
  },
  "servers": [
    {
      "url": "https://necogoode-systems.azurewebsites.net"
    }
  ],
  "tags": [
    {
      "name": "Assets"
    },
    {
      "name": "Operations"
    }
  ],
  "paths": {
    "/api/warehouse/records": {
      "get": {
        "operationId": "listWarehouseRecords",
        "tags": [
          "Assets"
        ],
        "summary": "List Assets (newest first)",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "count": {
                      "type": "integer"
                    },
                    "records": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Record"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createWarehouseRecord",
        "tags": [
          "Assets"
        ],
        "summary": "Create a Asset (emits vertex.asset.registered)",
        "description": "Creates a Asset in Vertex Warehouse and emits the vertex.asset.registered webhook to SoloLift.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "record": {
                      "$ref": "#/components/schemas/Record"
                    },
                    "event": {
                      "$ref": "#/components/schemas/Event"
                    },
                    "droppedFields": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "identifiers belonging to another system, dropped before the record was written"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "A required field was missing",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/warehouse/records/{id}": {
      "get": {
        "operationId": "getWarehouseRecord",
        "tags": [
          "Assets"
        ],
        "summary": "Read one Asset",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "asset_tag, e.g. VX-88213",
            "example": "VX-88213"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "record": {
                      "$ref": "#/components/schemas/Record"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          }
        }
      },
      "patch": {
        "operationId": "updateWarehouseRecord",
        "tags": [
          "Assets"
        ],
        "summary": "Update a Asset (emits vertex.asset.updated)",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "asset_tag, e.g. VX-88213",
            "example": "VX-88213"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "record": {
                      "$ref": "#/components/schemas/Record"
                    },
                    "event": {
                      "$ref": "#/components/schemas/Event"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/api/warehouse/records/{id}/reserve": {
      "post": {
        "operationId": "warehouseReserve",
        "tags": [
          "Operations"
        ],
        "summary": "Reserve stock (emits vertex.reservation.created)",
        "description": "Reserve the Asset out of a stock Location against an employee number.",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "asset_tag, e.g. VX-88213",
            "example": "VX-88213"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ActionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "record": {
                      "$ref": "#/components/schemas/Record"
                    },
                    "event": {
                      "$ref": "#/components/schemas/Event"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          }
        }
      }
    },
    "/api/warehouse/records/{id}/events": {
      "get": {
        "operationId": "listWarehouseRecordEvents",
        "tags": [
          "Operations"
        ],
        "summary": "Every event this system has emitted for the record",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "asset_tag, e.g. VX-88213",
            "example": "VX-88213"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "events": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Event"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/warehouse/events": {
      "get": {
        "operationId": "listWarehouseEvents",
        "tags": [
          "Operations"
        ],
        "summary": "Every event this system has emitted (newest first)",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "default": 200
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "events": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Event"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/warehouse/chaos": {
      "post": {
        "operationId": "warehouseChaos",
        "tags": [
          "Operations"
        ],
        "summary": "Emit a deliberately awkward event for anomaly testing",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChaosRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "event": {
                      "$ref": "#/components/schemas/Event"
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/warehouse/seed": {
      "post": {
        "operationId": "warehouseSeedHistory",
        "tags": [
          "Operations"
        ],
        "summary": "Generate N backdated Assets with events across a date window",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SeedRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    },
    "/api/_health": {
      "get": {
        "operationId": "health",
        "tags": [
          "Operations"
        ],
        "summary": "Liveness and build stamp",
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "ok": {
                      "type": "boolean"
                    },
                    "build": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Record": {
        "type": "object",
        "properties": {
          "asset_tag": {
            "type": "string",
            "description": "Asset identifier issued by Vertex Warehouse",
            "example": "VX-88213"
          },
          "asset_type": {
            "type": "string",
            "enum": [
              "Laptop",
              "Docking station",
              "Monitor",
              "Handset",
              "Headset"
            ],
            "description": "Asset type",
            "default": "Laptop"
          },
          "model": {
            "type": "string",
            "description": "Model",
            "default": "Vertex Pro 14"
          },
          "employee_no": {
            "type": "string",
            "description": "Employee no. (required on create)"
          },
          "stock_location": {
            "type": "string",
            "enum": [
              "Chicago DC",
              "Reno DC",
              "Rotterdam DC"
            ],
            "description": "Stock location",
            "default": "Chicago DC"
          },
          "cost_centre": {
            "type": "string",
            "description": "Cost centre"
          },
          "stock_status": {
            "type": "string",
            "enum": [
              "In stock",
              "Reserved",
              "Picked",
              "Shipped",
              "Retired"
            ],
            "description": "Stock status",
            "default": "In stock"
          },
          "quantity": {
            "type": "number",
            "description": "Quantity",
            "default": 1
          },
          "reservation_ref": {
            "type": "string",
            "description": "Reservation ref"
          },
          "notes": {
            "type": "string",
            "description": "Notes"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "eventCount": {
            "type": "integer",
            "description": "number of events this system has emitted for the record"
          },
          "lastDelivery": {
            "$ref": "#/components/schemas/Delivery"
          }
        }
      },
      "CreateRequest": {
        "type": "object",
        "required": [
          "employee_no"
        ],
        "properties": {
          "asset_type": {
            "type": "string",
            "enum": [
              "Laptop",
              "Docking station",
              "Monitor",
              "Handset",
              "Headset"
            ],
            "description": "Asset type",
            "default": "Laptop"
          },
          "model": {
            "type": "string",
            "description": "Model",
            "default": "Vertex Pro 14"
          },
          "employee_no": {
            "type": "string",
            "description": "Employee no. (required on create)"
          },
          "stock_location": {
            "type": "string",
            "enum": [
              "Chicago DC",
              "Reno DC",
              "Rotterdam DC"
            ],
            "description": "Stock location",
            "default": "Chicago DC"
          },
          "cost_centre": {
            "type": "string",
            "description": "Cost centre"
          },
          "stock_status": {
            "type": "string",
            "enum": [
              "In stock",
              "Reserved",
              "Picked",
              "Shipped",
              "Retired"
            ],
            "description": "Stock status",
            "default": "In stock"
          },
          "quantity": {
            "type": "number",
            "description": "Quantity",
            "default": 1
          },
          "reservation_ref": {
            "type": "string",
            "description": "Reservation ref"
          },
          "notes": {
            "type": "string",
            "description": "Notes"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "description": "Optional. Backdates the record and the emitted event (used for seeding history)."
          },
          "emit": {
            "type": "boolean",
            "default": true,
            "description": "Optional. false suppresses the webhook to SoloLift."
          }
        }
      },
      "UpdateRequest": {
        "type": "object",
        "properties": {
          "asset_type": {
            "type": "string",
            "enum": [
              "Laptop",
              "Docking station",
              "Monitor",
              "Handset",
              "Headset"
            ],
            "description": "Asset type",
            "default": "Laptop"
          },
          "model": {
            "type": "string",
            "description": "Model",
            "default": "Vertex Pro 14"
          },
          "employee_no": {
            "type": "string",
            "description": "Employee no. (required on create)"
          },
          "stock_location": {
            "type": "string",
            "enum": [
              "Chicago DC",
              "Reno DC",
              "Rotterdam DC"
            ],
            "description": "Stock location",
            "default": "Chicago DC"
          },
          "cost_centre": {
            "type": "string",
            "description": "Cost centre"
          },
          "stock_status": {
            "type": "string",
            "enum": [
              "In stock",
              "Reserved",
              "Picked",
              "Shipped",
              "Retired"
            ],
            "description": "Stock status",
            "default": "In stock"
          },
          "quantity": {
            "type": "number",
            "description": "Quantity",
            "default": 1
          },
          "reservation_ref": {
            "type": "string",
            "description": "Reservation ref"
          },
          "notes": {
            "type": "string",
            "description": "Notes"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "description": "Optional. Backdates the record and the emitted event (used for seeding history)."
          },
          "emit": {
            "type": "boolean",
            "default": true,
            "description": "Optional. false suppresses the webhook to SoloLift."
          }
        }
      },
      "ActionRequest": {
        "type": "object",
        "required": [
          "location"
        ],
        "properties": {
          "location": {
            "type": "string",
            "enum": [
              "Chicago DC",
              "Reno DC",
              "Rotterdam DC"
            ],
            "default": "Chicago DC"
          },
          "employee_no": {
            "type": "string"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "description": "Optional. Backdates the emitted event."
          }
        }
      },
      "ChaosRequest": {
        "type": "object",
        "required": [
          "mode"
        ],
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "out_of_order",
              "duplicate",
              "omit_field",
              "unknown_type"
            ]
          },
          "recordId": {
            "type": "string",
            "description": "defaults to the most recent record"
          }
        }
      },
      "SeedRequest": {
        "type": "object",
        "properties": {
          "count": {
            "type": "integer",
            "default": 5,
            "maximum": 200
          },
          "from": {
            "type": "string",
            "format": "date-time",
            "description": "start of the backdating window"
          },
          "to": {
            "type": "string",
            "format": "date-time",
            "description": "end of the backdating window"
          },
          "includeAction": {
            "type": "boolean",
            "default": true,
            "description": "also emit vertex.reservation.created per record"
          },
          "specialistRatio": {
            "type": "number",
            "default": 0.15
          },
          "fieldRatios": {
            "type": "object",
            "additionalProperties": {
              "type": "number"
            },
            "description": "probability a normally-optional field is populated, e.g. {\"CostCentre\":0.35}"
          },
          "template": {
            "type": "object",
            "description": "field values forced on every seeded record"
          },
          "emit": {
            "type": "boolean",
            "default": true
          }
        }
      },
      "Delivery": {
        "type": "object",
        "description": "the outcome of the SoloLift webhook for the latest event",
        "properties": {
          "httpStatus": {
            "type": "integer"
          },
          "receiptStatus": {
            "type": "string"
          },
          "receiptReason": {
            "type": "string"
          },
          "externalEventId": {
            "type": "string"
          },
          "transportError": {
            "type": "string",
            "nullable": true
          },
          "at": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Event": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "system": {
            "type": "string",
            "enum": [
              "warehouse"
            ]
          },
          "recordId": {
            "type": "string"
          },
          "eventType": {
            "type": "string",
            "enum": [
              "vertex.asset.registered",
              "vertex.asset.updated",
              "vertex.reservation.created",
              "vertex.asset.levitated"
            ]
          },
          "externalEventId": {
            "type": "string"
          },
          "eventSourceId": {
            "type": "string"
          },
          "subject": {
            "type": "string"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time"
          },
          "emittedAt": {
            "type": "string",
            "format": "date-time"
          },
          "chaos": {
            "type": "string",
            "nullable": true,
            "enum": [
              "out_of_order",
              "duplicate",
              "omit_field",
              "unknown_type",
              null
            ]
          },
          "payload": {
            "type": "object",
            "additionalProperties": true
          },
          "delivery": {
            "$ref": "#/components/schemas/Delivery"
          }
        }
      }
    }
  }
}