{
  "openapi": "3.1.0",
  "info": {
    "title": "Inventrackr API",
    "version": "1.0.0",
    "summary": "Read and update a Pro storage's products and suppliers, and receive signed webhooks.",
    "description": "Each API key belongs to one storage. Keys are created by the storage owner in the web app (Storage settings → Integrations) and work while the owner's plan is Pro. Full guide: https://inventrackr.com/developers",
    "contact": {
      "name": "Inventrackr support",
      "email": "support@inventrackr.com",
      "url": "https://inventrackr.com/support"
    },
    "termsOfService": "https://inventrackr.com/terms"
  },
  "externalDocs": {
    "description": "API & webhooks documentation",
    "url": "https://inventrackr.com/developers"
  },
  "servers": [
    {
      "url": "https://api-production-c3ca.up.railway.app/api/v1",
      "description": "Production"
    }
  ],
  "security": [
    {
      "apiKey": []
    }
  ],
  "tags": [
    {
      "name": "Items",
      "description": "Products in the key's storage."
    },
    {
      "name": "Suppliers"
    }
  ],
  "paths": {
    "/items": {
      "get": {
        "tags": [
          "Items"
        ],
        "operationId": "listItems",
        "summary": "List items",
        "description": "Items ordered by `updatedAt`, then `id` (oldest first). Deleted items are not listed.",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string",
              "maxLength": 200
            },
            "description": "The `nextCursor` of the previous page (opaque)."
          },
          {
            "name": "updatedSince",
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            },
            "description": "Only items with `updatedAt` at or after this moment (inclusive). ISO 8601 with `Z` or an offset."
          }
        ],
        "responses": {
          "200": {
            "description": "A page of items.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "items",
                    "nextCursor"
                  ],
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Item"
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Pass as `cursor` for the next page; null on the last page."
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "Invalid query (`details`), or `INVALID_CURSOR`.",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/ValidationError"
                    },
                    {
                      "$ref": "#/components/schemas/Error"
                    }
                  ]
                },
                "example": {
                  "error": "Invalid cursor",
                  "code": "INVALID_CURSOR"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Busy"
          }
        }
      },
      "post": {
        "tags": [
          "Items"
        ],
        "operationId": "createItem",
        "summary": "Create an item",
        "description": "Needs a write key. Sends an `item.created` webhook. Not idempotent.",
        "security": [
          {
            "apiKey": [
              "write"
            ]
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ItemCreate"
              },
              "example": {
                "name": "Espresso beans",
                "barcode": "8714789120045",
                "quantity": 12,
                "minimumQuantity": 5,
                "unit": "kg",
                "priceCents": 1899
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Created.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Item"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Busy"
          }
        }
      }
    },
    "/items/{id}": {
      "get": {
        "tags": [
          "Items"
        ],
        "operationId": "getItem",
        "summary": "Get an item",
        "parameters": [
          {
            "$ref": "#/components/parameters/ItemId"
          }
        ],
        "responses": {
          "200": {
            "description": "The item.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Item"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Busy"
          }
        }
      }
    },
    "/items/{id}/quantity": {
      "patch": {
        "tags": [
          "Items"
        ],
        "operationId": "updateItemQuantity",
        "summary": "Change stock",
        "description": "Needs a write key. Send either `quantity` (absolute) or `delta` (relative; the result is clamped at 0). If both are sent, `quantity` is used. Sends `item.quantityChanged` (and `item.lowStock` when the stock crosses to at or below the minimum).",
        "security": [
          {
            "apiKey": [
              "write"
            ]
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/ItemId"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuantityChange"
              },
              "examples": {
                "delta": {
                  "value": {
                    "delta": -2,
                    "note": "Sold at the counter"
                  }
                },
                "absolute": {
                  "value": {
                    "quantity": 40,
                    "expectedQuantity": 3.5,
                    "note": "Stock count"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The updated item plus its previous quantity.",
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Item"
                    },
                    {
                      "type": "object",
                      "required": [
                        "previousQuantity"
                      ],
                      "properties": {
                        "previousQuantity": {
                          "type": "number"
                        }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "409": {
            "description": "`expectedQuantity` didn't match the current stock.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": "The stock changed since expectedQuantity was read",
                  "code": "STOCK_CHANGED"
                }
              }
            }
          },
          "413": {
            "$ref": "#/components/responses/TooLarge"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Busy"
          }
        }
      }
    },
    "/suppliers": {
      "get": {
        "tags": [
          "Suppliers"
        ],
        "operationId": "listSuppliers",
        "summary": "List suppliers",
        "description": "All suppliers of the storage, sorted by name (case-insensitive). Not paged.",
        "responses": {
          "200": {
            "description": "Suppliers.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Supplier"
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "429": {
            "$ref": "#/components/responses/TooManyRequests"
          },
          "503": {
            "$ref": "#/components/responses/Busy"
          }
        }
      }
    }
  },
  "webhooks": {
    "item.created": {
      "post": {
        "summary": "item.created",
        "description": "A product was added (apps, CSV import or API).",
        "operationId": "webhook_item_created",
        "parameters": [
          {
            "name": "Inventrackr-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "`t=<unix seconds>,v1=<hex HMAC-SHA256(secret, t + \".\" + raw body)>`. The key is the whole signing secret (`whsec_…`)."
          },
          {
            "name": "Inventrackr-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "const": "item.created"
            }
          },
          {
            "name": "Inventrackr-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Unique per endpoint and event; unchanged across retries."
          },
          {
            "name": "User-Agent",
            "in": "header",
            "schema": {
              "type": "string",
              "const": "Inventrackr-Webhooks/1.0"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/WebhookEnvelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "item.created"
                      },
                      "data": {
                        "type": "object",
                        "required": [
                          "item"
                        ],
                        "properties": {
                          "item": {
                            "$ref": "#/components/schemas/Item"
                          }
                        }
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Acknowledged. Respond within 10 seconds; anything else (other statuses, redirects, timeouts) is retried, up to 8 attempts over about 30 hours."
          }
        }
      }
    },
    "item.updated": {
      "post": {
        "summary": "item.updated",
        "description": "A product's details were edited in the apps or updated by CSV import.",
        "operationId": "webhook_item_updated",
        "parameters": [
          {
            "name": "Inventrackr-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "`t=<unix seconds>,v1=<hex HMAC-SHA256(secret, t + \".\" + raw body)>`. The key is the whole signing secret (`whsec_…`)."
          },
          {
            "name": "Inventrackr-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "const": "item.updated"
            }
          },
          {
            "name": "Inventrackr-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Unique per endpoint and event; unchanged across retries."
          },
          {
            "name": "User-Agent",
            "in": "header",
            "schema": {
              "type": "string",
              "const": "Inventrackr-Webhooks/1.0"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/WebhookEnvelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "item.updated"
                      },
                      "data": {
                        "type": "object",
                        "required": [
                          "item"
                        ],
                        "properties": {
                          "item": {
                            "$ref": "#/components/schemas/Item"
                          }
                        }
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Acknowledged. Respond within 10 seconds; anything else (other statuses, redirects, timeouts) is retried, up to 8 attempts over about 30 hours."
          }
        }
      }
    },
    "item.deleted": {
      "post": {
        "summary": "item.deleted",
        "description": "A product was deleted.",
        "operationId": "webhook_item_deleted",
        "parameters": [
          {
            "name": "Inventrackr-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "`t=<unix seconds>,v1=<hex HMAC-SHA256(secret, t + \".\" + raw body)>`. The key is the whole signing secret (`whsec_…`)."
          },
          {
            "name": "Inventrackr-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "const": "item.deleted"
            }
          },
          {
            "name": "Inventrackr-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Unique per endpoint and event; unchanged across retries."
          },
          {
            "name": "User-Agent",
            "in": "header",
            "schema": {
              "type": "string",
              "const": "Inventrackr-Webhooks/1.0"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/WebhookEnvelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "item.deleted"
                      },
                      "data": {
                        "type": "object",
                        "required": [
                          "item"
                        ],
                        "properties": {
                          "item": {
                            "type": "object",
                            "required": [
                              "id",
                              "name"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Acknowledged. Respond within 10 seconds; anything else (other statuses, redirects, timeouts) is retried, up to 8 attempts over about 30 hours."
          }
        }
      }
    },
    "item.quantityChanged": {
      "post": {
        "summary": "item.quantityChanged",
        "description": "Stock changed.",
        "operationId": "webhook_item_quantityChanged",
        "parameters": [
          {
            "name": "Inventrackr-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "`t=<unix seconds>,v1=<hex HMAC-SHA256(secret, t + \".\" + raw body)>`. The key is the whole signing secret (`whsec_…`)."
          },
          {
            "name": "Inventrackr-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "const": "item.quantityChanged"
            }
          },
          {
            "name": "Inventrackr-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Unique per endpoint and event; unchanged across retries."
          },
          {
            "name": "User-Agent",
            "in": "header",
            "schema": {
              "type": "string",
              "const": "Inventrackr-Webhooks/1.0"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/WebhookEnvelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "item.quantityChanged"
                      },
                      "data": {
                        "type": "object",
                        "required": [
                          "item",
                          "previousQuantity",
                          "delta"
                        ],
                        "properties": {
                          "item": {
                            "$ref": "#/components/schemas/Item"
                          },
                          "previousQuantity": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "delta": {
                            "type": [
                              "number",
                              "null"
                            ]
                          },
                          "note": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Acknowledged. Respond within 10 seconds; anything else (other statuses, redirects, timeouts) is retried, up to 8 attempts over about 30 hours."
          }
        }
      }
    },
    "item.lowStock": {
      "post": {
        "summary": "item.lowStock",
        "description": "A stock change took a product from above its minimum to at or below it.",
        "operationId": "webhook_item_lowStock",
        "parameters": [
          {
            "name": "Inventrackr-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "`t=<unix seconds>,v1=<hex HMAC-SHA256(secret, t + \".\" + raw body)>`. The key is the whole signing secret (`whsec_…`)."
          },
          {
            "name": "Inventrackr-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "const": "item.lowStock"
            }
          },
          {
            "name": "Inventrackr-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Unique per endpoint and event; unchanged across retries."
          },
          {
            "name": "User-Agent",
            "in": "header",
            "schema": {
              "type": "string",
              "const": "Inventrackr-Webhooks/1.0"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/WebhookEnvelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "item.lowStock"
                      },
                      "data": {
                        "type": "object",
                        "required": [
                          "item"
                        ],
                        "properties": {
                          "item": {
                            "$ref": "#/components/schemas/Item"
                          }
                        }
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Acknowledged. Respond within 10 seconds; anything else (other statuses, redirects, timeouts) is retried, up to 8 attempts over about 30 hours."
          }
        }
      }
    },
    "supplier.created": {
      "post": {
        "summary": "supplier.created",
        "description": "A supplier was added.",
        "operationId": "webhook_supplier_created",
        "parameters": [
          {
            "name": "Inventrackr-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "`t=<unix seconds>,v1=<hex HMAC-SHA256(secret, t + \".\" + raw body)>`. The key is the whole signing secret (`whsec_…`)."
          },
          {
            "name": "Inventrackr-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "const": "supplier.created"
            }
          },
          {
            "name": "Inventrackr-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Unique per endpoint and event; unchanged across retries."
          },
          {
            "name": "User-Agent",
            "in": "header",
            "schema": {
              "type": "string",
              "const": "Inventrackr-Webhooks/1.0"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/WebhookEnvelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "supplier.created"
                      },
                      "data": {
                        "type": "object",
                        "required": [
                          "supplier"
                        ],
                        "properties": {
                          "supplier": {
                            "$ref": "#/components/schemas/Supplier"
                          }
                        }
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Acknowledged. Respond within 10 seconds; anything else (other statuses, redirects, timeouts) is retried, up to 8 attempts over about 30 hours."
          }
        }
      }
    },
    "supplier.updated": {
      "post": {
        "summary": "supplier.updated",
        "description": "A supplier was edited.",
        "operationId": "webhook_supplier_updated",
        "parameters": [
          {
            "name": "Inventrackr-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "`t=<unix seconds>,v1=<hex HMAC-SHA256(secret, t + \".\" + raw body)>`. The key is the whole signing secret (`whsec_…`)."
          },
          {
            "name": "Inventrackr-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "const": "supplier.updated"
            }
          },
          {
            "name": "Inventrackr-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Unique per endpoint and event; unchanged across retries."
          },
          {
            "name": "User-Agent",
            "in": "header",
            "schema": {
              "type": "string",
              "const": "Inventrackr-Webhooks/1.0"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/WebhookEnvelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "supplier.updated"
                      },
                      "data": {
                        "type": "object",
                        "required": [
                          "supplier"
                        ],
                        "properties": {
                          "supplier": {
                            "$ref": "#/components/schemas/Supplier"
                          }
                        }
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Acknowledged. Respond within 10 seconds; anything else (other statuses, redirects, timeouts) is retried, up to 8 attempts over about 30 hours."
          }
        }
      }
    },
    "supplier.deleted": {
      "post": {
        "summary": "supplier.deleted",
        "description": "A supplier was deleted.",
        "operationId": "webhook_supplier_deleted",
        "parameters": [
          {
            "name": "Inventrackr-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "`t=<unix seconds>,v1=<hex HMAC-SHA256(secret, t + \".\" + raw body)>`. The key is the whole signing secret (`whsec_…`)."
          },
          {
            "name": "Inventrackr-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "const": "supplier.deleted"
            }
          },
          {
            "name": "Inventrackr-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Unique per endpoint and event; unchanged across retries."
          },
          {
            "name": "User-Agent",
            "in": "header",
            "schema": {
              "type": "string",
              "const": "Inventrackr-Webhooks/1.0"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/WebhookEnvelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "supplier.deleted"
                      },
                      "data": {
                        "type": "object",
                        "required": [
                          "supplier"
                        ],
                        "properties": {
                          "supplier": {
                            "type": "object",
                            "required": [
                              "id",
                              "name"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "format": "uuid"
                              },
                              "name": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              }
                            }
                          }
                        }
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Acknowledged. Respond within 10 seconds; anything else (other statuses, redirects, timeouts) is retried, up to 8 attempts over about 30 hours."
          }
        }
      }
    },
    "webhook.test": {
      "post": {
        "summary": "webhook.test",
        "description": "Sent by \"Send test\" in the app (one attempt, no retries). Can't be subscribed to.",
        "operationId": "webhook_webhook_test",
        "parameters": [
          {
            "name": "Inventrackr-Signature",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "`t=<unix seconds>,v1=<hex HMAC-SHA256(secret, t + \".\" + raw body)>`. The key is the whole signing secret (`whsec_…`)."
          },
          {
            "name": "Inventrackr-Event",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "const": "webhook.test"
            }
          },
          {
            "name": "Inventrackr-Delivery",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            },
            "description": "Unique per endpoint and event; unchanged across retries."
          },
          {
            "name": "User-Agent",
            "in": "header",
            "schema": {
              "type": "string",
              "const": "Inventrackr-Webhooks/1.0"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/WebhookEnvelope"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "type": {
                        "const": "webhook.test"
                      },
                      "data": {
                        "type": "object",
                        "required": [
                          "message"
                        ],
                        "properties": {
                          "message": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "2XX": {
            "description": "Acknowledged. Respond within 10 seconds; anything else (other statuses, redirects, timeouts) is retried, up to 8 attempts over about 30 hours."
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "apiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "itk_live_…",
        "description": "`Authorization: Bearer itk_live_…`. Read keys can call the GET endpoints; write keys can call everything."
      }
    },
    "parameters": {
      "ItemId": {
        "name": "id",
        "in": "path",
        "required": true,
        "schema": {
          "type": "string",
          "format": "uuid"
        }
      }
    },
    "headers": {
      "RetryAfter": {
        "description": "Seconds to wait before retrying.",
        "schema": {
          "type": "integer",
          "minimum": 1
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "Validation failed (`details` lists the problems), malformed JSON, a non-UUID id, or invalid Unicode.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/ValidationError"
            },
            "example": {
              "error": "Invalid request",
              "details": [
                {
                  "code": "custom",
                  "path": [
                    "quantity"
                  ],
                  "message": "Use at most 3 decimal places"
                }
              ]
            }
          }
        }
      },
      "Unauthorized": {
        "description": "Missing, malformed or revoked key (`API_KEY_INVALID`), or the storage owner's plan isn't Pro (`PLAN_REQUIRED`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "This API key is invalid or was revoked",
              "code": "API_KEY_INVALID"
            }
          }
        }
      },
      "Forbidden": {
        "description": "A read-only key called a write endpoint.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "This API key is read-only",
              "code": "INSUFFICIENT_SCOPE"
            }
          }
        }
      },
      "NotFound": {
        "description": "Not found in this key's storage.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "Item not found",
              "code": "NOT_FOUND"
            }
          }
        }
      },
      "TooLarge": {
        "description": "Request body larger than 256 KB.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "Request is too large"
            }
          }
        }
      },
      "TooManyRequests": {
        "description": "Rate limit exceeded: 120 requests/min per key, 600/min per client IP (fixed one-minute windows).",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "Too many attempts. Please wait a moment and try again."
            }
          }
        }
      },
      "Busy": {
        "description": "A conflicting change happened at the same moment; safe to retry.",
        "headers": {
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            },
            "example": {
              "error": "The server was busy with a conflicting change. Please try again."
            }
          }
        }
      }
    },
    "schemas": {
      "Unit": {
        "type": "string",
        "enum": [
          "each",
          "pack",
          "box",
          "case",
          "roll",
          "ml",
          "l",
          "g",
          "kg",
          "oz",
          "lb",
          "fl_oz",
          "gal",
          "cm",
          "m",
          "in",
          "ft"
        ]
      },
      "Item": {
        "type": "object",
        "required": [
          "id",
          "name",
          "description",
          "barcode",
          "quantity",
          "minimumQuantity",
          "unit",
          "priceCents",
          "supplierId",
          "supplierName",
          "hasImage",
          "imageVersion",
          "version",
          "createdAt",
          "updatedAt",
          "stockStatus"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string",
            "maxLength": 160
          },
          "description": {
            "type": "string",
            "maxLength": 4000
          },
          "barcode": {
            "type": "string",
            "maxLength": 120
          },
          "quantity": {
            "type": "number",
            "minimum": 0
          },
          "minimumQuantity": {
            "type": "number",
            "minimum": 0
          },
          "unit": {
            "$ref": "#/components/schemas/Unit"
          },
          "priceCents": {
            "type": "integer",
            "minimum": 0,
            "description": "In the smallest unit of the storage's currency (set in the app)."
          },
          "supplierId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid"
          },
          "supplierName": {
            "type": [
              "string",
              "null"
            ]
          },
          "hasImage": {
            "type": "boolean"
          },
          "imageVersion": {
            "type": "integer"
          },
          "version": {
            "type": "integer",
            "description": "Increases with every change."
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "stockStatus": {
            "type": "string",
            "enum": [
              "inStock",
              "lowStock",
              "outOfStock"
            ],
            "description": "outOfStock when quantity is 0; lowStock when quantity ≤ minimumQuantity."
          }
        },
        "example": {
          "id": "3f6c2a8e-6b1d-4c1e-9a52-2d8f0c7b9e10",
          "name": "Espresso beans",
          "description": "House blend, 1 kg bags",
          "barcode": "8714789120045",
          "quantity": 3.5,
          "minimumQuantity": 5,
          "unit": "kg",
          "priceCents": 1899,
          "supplierId": "9b2e7c44-1f0a-4d3b-8e6f-5a1c2d3e4f50",
          "supplierName": "Roastery Co.",
          "hasImage": false,
          "imageVersion": 0,
          "version": 7,
          "createdAt": "2026-10-02T14:05:11.482Z",
          "updatedAt": "2026-11-18T09:31:27.103Z",
          "stockStatus": "lowStock"
        }
      },
      "ItemCreate": {
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 160,
            "description": "Trimmed."
          },
          "description": {
            "type": "string",
            "maxLength": 4000,
            "default": ""
          },
          "barcode": {
            "type": "string",
            "maxLength": 120,
            "default": "",
            "description": "Trimmed."
          },
          "quantity": {
            "type": "number",
            "minimum": 0,
            "maximum": 999999999999,
            "multipleOf": 0.001,
            "description": "At most 3 decimal places.",
            "default": 0
          },
          "minimumQuantity": {
            "type": "number",
            "minimum": 0,
            "maximum": 999999999999,
            "multipleOf": 0.001,
            "description": "At most 3 decimal places.",
            "default": 0
          },
          "unit": {
            "$ref": "#/components/schemas/Unit",
            "default": "each"
          },
          "priceCents": {
            "type": "integer",
            "minimum": 0,
            "maximum": 2147483647,
            "default": 0
          },
          "supplierId": {
            "type": [
              "string",
              "null"
            ],
            "format": "uuid",
            "description": "A supplier of this storage; any other id is ignored (no supplier)."
          }
        }
      },
      "QuantityChange": {
        "type": "object",
        "properties": {
          "quantity": {
            "type": "number",
            "minimum": 0,
            "maximum": 999999999999,
            "multipleOf": 0.001,
            "description": "Sets the stock. At most 3 decimal places."
          },
          "delta": {
            "type": "number",
            "minimum": -1000000,
            "maximum": 1000000,
            "multipleOf": 0.001,
            "description": "Adds to the stock; the result never goes below 0."
          },
          "expectedQuantity": {
            "type": "number",
            "minimum": 0,
            "maximum": 999999999999,
            "multipleOf": 0.001,
            "description": "With `quantity` only: refuse with 409 STOCK_CHANGED unless the current stock equals this. Ignored with `delta`."
          },
          "note": {
            "type": "string",
            "maxLength": 280,
            "description": "Shown in the activity history and sent in the webhook."
          }
        },
        "anyOf": [
          {
            "required": [
              "quantity"
            ]
          },
          {
            "required": [
              "delta"
            ]
          }
        ]
      },
      "Supplier": {
        "type": "object",
        "required": [
          "id",
          "name",
          "contactName",
          "contactEmail",
          "contactPhone",
          "createdAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "contactName": {
            "type": "string"
          },
          "contactEmail": {
            "type": "string"
          },
          "contactPhone": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "description": "Human-readable message."
          },
          "code": {
            "type": "string",
            "enum": [
              "API_KEY_INVALID",
              "PLAN_REQUIRED",
              "INSUFFICIENT_SCOPE",
              "NOT_FOUND",
              "INVALID_CURSOR",
              "STOCK_CHANGED",
              "REFERENCE_REMOVED"
            ],
            "description": "Machine-readable code (not present on every error)."
          }
        }
      },
      "ValidationError": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string",
            "const": "Invalid request"
          },
          "details": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "code",
                "path",
                "message"
              ],
              "properties": {
                "code": {
                  "type": "string"
                },
                "path": {
                  "type": "array",
                  "items": {
                    "type": [
                      "string",
                      "integer"
                    ]
                  }
                },
                "message": {
                  "type": "string"
                }
              },
              "additionalProperties": true
            }
          }
        }
      },
      "WebhookEnvelope": {
        "type": "object",
        "required": [
          "id",
          "type",
          "createdAt",
          "storageId",
          "data"
        ],
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid",
            "description": "Event ID: the same for every endpoint and every retry. Use it to drop duplicates."
          },
          "type": {
            "type": "string"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "storageId": {
            "type": "string",
            "format": "uuid"
          },
          "data": {
            "type": "object"
          }
        }
      }
    }
  }
}
