{
  "openapi": "3.1.0",
  "info": {
    "title": "GlobalOS tenant inventory API",
    "version": "1.0.0",
    "description": "GlobalOS Inventory API v1. Authenticated incoming inventory and status polling on tenant domains. Public documentation: https://developers.globalos.ai/listings/v1. New items require staff approval."
  },
  "servers": [
    {
      "url": "https://{tenantDomain}/api/integrations/listings/v1",
      "description": "Use the verified website domain for your tenant. The documentation host does not accept inventory.",
      "variables": {
        "tenantDomain": {
          "default": "idahopawn.com",
          "description": "Your verified GlobalOS tenant domain, without scheme or path."
        }
      }
    }
  ],
  "security": [
    {
      "tenantApiKey": []
    }
  ],
  "paths": {
    "/stores": {
      "get": {
        "summary": "List stores allowed by this key",
        "description": "Requires listings:read.",
        "responses": {
          "200": {
            "description": "Stores",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "stores": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string",
                            "format": "uuid"
                          },
                          "name": {
                            "type": "string"
                          }
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/items": {
      "post": {
        "summary": "Receive an item or partial update",
        "description": "Requires listings:write; URL photo import also requires photos:write. Every event needs eventId, increasing sourceVersion, storeId and externalItemId plus at least one inventory field. First events also require title, category, condition and priceCents. Same event and identical data may be retried.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IncomingItem"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Idempotent event replay; latest receipt",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Receipt"
                }
              }
            }
          },
          "202": {
            "description": "Accepted inventory event; may require review/photos",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Receipt"
                }
              }
            }
          },
          "400": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      },
      "get": {
        "summary": "Read current correlation and publication state",
        "description": "Requires listings:read. Supply listingId OR both storeId and externalItemId.",
        "parameters": [
          {
            "in": "query",
            "name": "listingId",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "query",
            "name": "storeId",
            "required": false,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "query",
            "name": "externalItemId",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Current state",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Receipt"
                }
              }
            }
          },
          "400": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/photos": {
      "post": {
        "summary": "Upload raw photo bytes",
        "description": "Requires photos:write. Source photo ID must be in the current item manifest. Immutable content per sourceVersion; JPEG, PNG and WebP up to 5 MB.",
        "parameters": [
          {
            "in": "query",
            "name": "importItemId",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "in": "query",
            "name": "sourcePhotoId",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128
            }
          },
          {
            "in": "query",
            "name": "sourceVersion",
            "required": true,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 9007199254740991
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "image/jpeg": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/png": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            },
            "image/webp": {
              "schema": {
                "type": "string",
                "format": "binary"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Photo ready",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "photoId": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "sourcePhotoId": {
                      "type": "string",
                      "minLength": 1,
                      "maxLength": 128
                    },
                    "ready": {
                      "type": "boolean"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "See API guide for errors and retry behavior.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "tenantApiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "gos_live_<64 hex characters>"
      }
    },
    "schemas": {
      "IncomingItem": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "eventId",
          "sourceVersion",
          "storeId",
          "externalItemId"
        ],
        "properties": {
          "eventId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "sourceVersion": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9007199254740991
          },
          "storeId": {
            "type": "string",
            "format": "uuid"
          },
          "externalItemId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "sourceProductId": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128
          },
          "sourceUrl": {
            "type": "string",
            "format": "uri",
            "pattern": "^https://"
          },
          "sourceUpdatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "title": {
            "type": "string",
            "minLength": 3,
            "maxLength": 160
          },
          "description": {
            "type": "string",
            "maxLength": 4000
          },
          "category": {
            "type": "string",
            "enum": [
              "electronics",
              "tools",
              "handbags",
              "firearms",
              "gold",
              "silver",
              "jewelry",
              "watches",
              "equipment",
              "other"
            ]
          },
          "condition": {
            "type": "string",
            "enum": [
              "new",
              "excellent",
              "good",
              "fair",
              "for-parts"
            ]
          },
          "priceCents": {
            "type": "string",
            "pattern": "^(0|[1-9][0-9]{0,9})$",
            "description": "USD cents; maximum 1000000000. Zero allowed in staging only."
          },
          "currency": {
            "type": "string",
            "enum": [
              "USD"
            ]
          },
          "quantity": {
            "type": "integer",
            "minimum": 0,
            "maximum": 1000000
          },
          "status": {
            "type": "string",
            "enum": [
              "available",
              "reserved",
              "sold",
              "unavailable",
              "on_loan",
              "awaiting_approval",
              "deleted"
            ]
          },
          "attributes": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "brand": {
                "type": "string",
                "maxLength": 120
              },
              "model": {
                "type": "string",
                "maxLength": 120
              },
              "metal": {
                "type": "string",
                "maxLength": 40
              },
              "purity": {
                "type": "string",
                "maxLength": 40
              },
              "weightGrams": {
                "type": "string",
                "pattern": "^[0-9]{1,7}(\\.[0-9]{1,4})?$"
              }
            }
          },
          "photos": {
            "type": "array",
            "maxItems": 12,
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "id"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "minLength": 1,
                  "maxLength": 128
                },
                "url": {
                  "type": "string",
                  "format": "uri",
                  "pattern": "^https://"
                }
              }
            }
          }
        }
      },
      "Receipt": {
        "type": "object",
        "properties": {
          "importItemId": {
            "type": "string",
            "format": "uuid"
          },
          "listingId": {
            "type": "string",
            "format": "uuid"
          },
          "externalItemId": {
            "type": "string"
          },
          "storeId": {
            "type": "string",
            "format": "uuid"
          },
          "sourceVersion": {
            "type": "integer",
            "minimum": 1,
            "maximum": 9007199254740991
          },
          "reviewStatus": {
            "type": "string",
            "enum": [
              "pending",
              "approved",
              "rejected",
              "held"
            ]
          },
          "listingStatus": {
            "type": [
              "string",
              "null"
            ]
          },
          "listingUrl": {
            "type": [
              "string",
              "null"
            ],
            "format": "uri"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "duplicate": {
            "type": "boolean"
          },
          "photoWarnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "string"
          }
        }
      }
    }
  }
}