{
  "openapi": "3.1.0",
  "info": {
    "title": "Orders & Inventory Hub API",
    "version": "1.0.0",
    "description": "Read-only JSON API exposing synced orders and inventory. Every endpoint except /health requires an API key sent in the `x-api-key` header (a `Authorization: Bearer <key>` header also works). Each key is scoped to the datasets it may read and is rate limited per minute; exceeding the limit returns 429.",
    "contact": {
      "name": "ChangeEngine",
      "url": "https://pineapple-inventory.changeenginepreviewer.com"
    }
  },
  "servers": [
    {
      "url": "https://pineapple-inventory.changeenginepreviewer.com/api/public/v1",
      "description": "ChangeEngine Data Hub"
    },
    {
      "url": "/api/public/v1",
      "description": "Relative to this host"
    }
  ],
  "tags": [
    {
      "name": "Orders",
      "description": "Employee orders and their line items"
    },
    {
      "name": "Inventory",
      "description": "SKUs with per-size availability"
    },
    {
      "name": "System",
      "description": "Service status"
    }
  ],
  "security": [
    {
      "ApiKeyHeader": []
    }
  ],
  "paths": {
    "/orders": {
      "get": {
        "tags": [
          "Orders"
        ],
        "summary": "List orders",
        "description": "Returns orders newest first. All filters are optional and combine with AND.",
        "operationId": "listOrders",
        "parameters": [
          {
            "name": "employee_email",
            "in": "query",
            "description": "Exact employee email (case-insensitive).",
            "schema": {
              "type": "string",
              "format": "email"
            },
            "example": "dana@acme.com"
          },
          {
            "name": "sku",
            "in": "query",
            "description": "Only orders containing this item SKU.",
            "schema": {
              "type": "string"
            },
            "example": "TS-BLK"
          },
          {
            "name": "status",
            "in": "query",
            "description": "Order status.",
            "schema": {
              "type": "string",
              "enum": [
                "placed",
                "confirmed",
                "shipped",
                "delivered"
              ]
            }
          },
          {
            "name": "start_date",
            "in": "query",
            "description": "ISO date/datetime — orders placed on or after.",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-01-01"
          },
          {
            "name": "end_date",
            "in": "query",
            "description": "ISO date/datetime — orders placed on or before.",
            "schema": {
              "type": "string",
              "format": "date"
            },
            "example": "2026-12-31"
          },
          {
            "name": "limit",
            "in": "query",
            "description": "Page size.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500,
              "default": 100
            }
          },
          {
            "name": "offset",
            "in": "query",
            "description": "Rows to skip.",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "A page of orders.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Order"
                      }
                    },
                    "meta": {
                      "$ref": "#/components/schemas/PageMeta"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/orders/{order_id}": {
      "get": {
        "tags": [
          "Orders"
        ],
        "summary": "Get a single order",
        "operationId": "getOrder",
        "parameters": [
          {
            "name": "order_id",
            "in": "path",
            "required": true,
            "description": "Unique order ID from the source system.",
            "schema": {
              "type": "string"
            },
            "example": "ord_10241"
          }
        ],
        "responses": {
          "200": {
            "description": "The order.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Order"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "404": {
            "$ref": "#/components/responses/NotFound"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/inventory": {
      "get": {
        "tags": [
          "Inventory"
        ],
        "summary": "List inventory",
        "description": "Every SKU with per-size availability. Use `format=flat` for one row per SKU + size.",
        "operationId": "listInventory",
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "description": "`nested` (default) or `flat`.",
            "schema": {
              "type": "string",
              "enum": [
                "nested",
                "flat"
              ],
              "default": "nested"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Inventory rows.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "oneOf": [
                        {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/InventoryItem"
                          }
                        },
                        {
                          "type": "array",
                          "items": {
                            "$ref": "#/components/schemas/InventoryFlatRow"
                          }
                        }
                      ]
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "count": {
                          "type": "integer",
                          "example": 8
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/ServerError"
          }
        }
      }
    },
    "/health": {
      "get": {
        "tags": [
          "System"
        ],
        "summary": "Service status",
        "description": "Unauthenticated. Reports status and the last data sync.",
        "operationId": "getHealth",
        "security": [],
        "responses": {
          "200": {
            "description": "Service is up.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "status": {
                      "type": "string",
                      "example": "ok"
                    },
                    "version": {
                      "type": "string",
                      "example": "v1"
                    },
                    "server_time": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "last_sync": {
                      "type": [
                        "object",
                        "null"
                      ],
                      "properties": {
                        "status": {
                          "type": "string",
                          "example": "success"
                        },
                        "finished_at": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "format": "date-time"
                        },
                        "orders_synced": {
                          "type": "integer",
                          "example": 12
                        },
                        "inventory_synced": {
                          "type": "integer",
                          "example": 8
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyHeader": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Your issued API key, e.g. `ce_live_1a2b3c...`."
      }
    },
    "schemas": {
      "OrderItem": {
        "type": "object",
        "properties": {
          "sku": {
            "type": [
              "string",
              "null"
            ],
            "example": "TS-BLK"
          },
          "item_name": {
            "type": [
              "string",
              "null"
            ],
            "example": "Black Tee"
          },
          "quantity": {
            "type": [
              "integer",
              "null"
            ],
            "example": 2
          },
          "size": {
            "type": [
              "string",
              "null"
            ],
            "example": "L"
          }
        }
      },
      "Order": {
        "type": "object",
        "properties": {
          "order_id": {
            "type": "string",
            "example": "ord_10241"
          },
          "order_number": {
            "type": [
              "string",
              "null"
            ],
            "example": "SO-10241"
          },
          "employee_name": {
            "type": [
              "string",
              "null"
            ],
            "example": "Dana Whitfield"
          },
          "employee_email": {
            "type": [
              "string",
              "null"
            ],
            "example": "dana@acme.com"
          },
          "order_date": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "mailing_address": {
            "type": [
              "string",
              "null"
            ],
            "example": "812 Rowan St, Austin, TX 78702"
          },
          "status": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              "placed",
              "confirmed",
              "shipped",
              "delivered",
              null
            ]
          },
          "tracking_number": {
            "type": [
              "string",
              "null"
            ],
            "example": "1Z999AA10123456784"
          },
          "items": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/OrderItem"
            }
          }
        }
      },
      "InventorySize": {
        "type": "object",
        "properties": {
          "size": {
            "type": [
              "string",
              "null"
            ],
            "example": "M"
          },
          "quantity_available": {
            "type": "integer",
            "example": 14
          },
          "quantity_used": {
            "type": "integer",
            "example": 7
          }
        }
      },
      "InventoryItem": {
        "type": "object",
        "properties": {
          "sku": {
            "type": "string",
            "example": "TS-BLK"
          },
          "item_name": {
            "type": [
              "string",
              "null"
            ],
            "example": "Black Tee"
          },
          "total_quantity_available": {
            "type": "integer",
            "example": 42
          },
          "total_quantity_used": {
            "type": "integer",
            "example": 18
          },
          "sizes": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/InventorySize"
            }
          }
        }
      },
      "InventoryFlatRow": {
        "type": "object",
        "properties": {
          "sku": {
            "type": "string",
            "example": "TS-BLK"
          },
          "item_name": {
            "type": [
              "string",
              "null"
            ],
            "example": "Black Tee"
          },
          "size": {
            "type": [
              "string",
              "null"
            ],
            "example": "M"
          },
          "quantity_available": {
            "type": "integer",
            "example": 14
          },
          "quantity_used": {
            "type": "integer",
            "example": 7
          }
        }
      },
      "PageMeta": {
        "type": "object",
        "properties": {
          "count": {
            "type": "integer",
            "example": 1
          },
          "total": {
            "type": "integer",
            "example": 12
          },
          "limit": {
            "type": "integer",
            "example": 100
          },
          "offset": {
            "type": "integer",
            "example": 0
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "missing_api_key",
                  "invalid_api_key",
                  "revoked_api_key",
                  "not_found",
                  "server_error"
                ]
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Missing or unrecognised API key.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Forbidden": {
        "description": "The API key has been revoked, or is not permitted to access this resource (`insufficient_scope`).",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded for this API key. Check the `x-ratelimit-limit` and `retry-after` response headers.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "NotFound": {
        "description": "No record with that identifier.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "ServerError": {
        "description": "Unexpected server error.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      }
    }
  }
}