{
  "openapi": "3.1.0",
  "info": {
    "title": "CopyForge Agency API",
    "version": "v1",
    "description": "Catalog reads and deterministic saved scans. Agency key required; 60 requests/minute/key. No AI-generation or direct publishing API."
  },
  "servers": [
    {
      "url": "https://copy-forge-ai.com"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v1/catalog": {
      "get": {
        "summary": "Read an owned catalog page",
        "parameters": [
          {
            "in": "query",
            "name": "offset",
            "schema": {
              "type": "integer",
              "minimum": 0,
              "maximum": 1000000,
              "default": 0
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success; inspect each product outcome",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Catalog"
                }
              }
            }
          },
          "default": {
            "description": "Non-success; inspect status and either documented error shape",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/catalog/scan": {
      "post": {
        "summary": "Save deterministic scans of existing owned listings",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": [
                  "productIds"
                ],
                "properties": {
                  "productIds": {
                    "type": "array",
                    "minItems": 1,
                    "maxItems": 50,
                    "items": {
                      "type": "string",
                      "format": "uuid"
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success; inspect each product outcome",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ScanResult"
                }
              }
            }
          },
          "default": {
            "description": "Non-success; inspect status and either documented error shape",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "schemas": {
      "Finding": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "severity": {
            "type": "string"
          },
          "match": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "sourceUrl": {
            "type": "string"
          }
        }
      },
      "Scan": {
        "type": "object",
        "properties": {
          "score": {
            "type": "number"
          },
          "riskLevel": {
            "enum": [
              "low",
              "medium",
              "high"
            ]
          },
          "flagCount": {
            "type": "integer"
          },
          "findings": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Finding"
            }
          },
          "rulesetVersion": {
            "type": "string"
          }
        }
      },
      "Product": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "name": {
            "type": "string"
          },
          "sku": {
            "type": [
              "string",
              "null"
            ]
          },
          "asin": {
            "type": [
              "string",
              "null"
            ]
          },
          "gtin": {
            "type": [
              "string",
              "null"
            ]
          },
          "brand": {
            "type": [
              "string",
              "null"
            ]
          },
          "category": {
            "type": [
              "string",
              "null"
            ]
          },
          "createdAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "listing": {
            "type": "object",
            "properties": {
              "title": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "bullets": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "keywords": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "channel": {
                "type": [
                  "string",
                  "null"
                ]
              }
            }
          },
          "latestScan": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Scan"
                  },
                  {
                    "type": "object",
                    "properties": {
                      "scannedAt": {
                        "type": [
                          "string",
                          "null"
                        ]
                      }
                    }
                  }
                ]
              }
            ]
          }
        }
      },
      "Catalog": {
        "type": "object",
        "properties": {
          "object": {
            "const": "list"
          },
          "apiVersion": {
            "const": "v1"
          },
          "count": {
            "type": "integer"
          },
          "products": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Product"
            }
          },
          "totalCount": {
            "type": "integer"
          },
          "hasMore": {
            "type": "boolean"
          },
          "nextOffset": {
            "type": [
              "integer",
              "null"
            ]
          }
        }
      },
      "ScanResult": {
        "type": "object",
        "properties": {
          "object": {
            "const": "scan.result"
          },
          "apiVersion": {
            "const": "v1"
          },
          "scanned": {
            "type": "integer"
          },
          "results": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "status"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "format": "uuid"
                },
                "status": {
                  "enum": [
                    "scanned",
                    "skipped_no_content",
                    "not_found",
                    "failed"
                  ]
                },
                "scan": {
                  "$ref": "#/components/schemas/Scan"
                },
                "error": {
                  "type": "object",
                  "properties": {
                    "code": {
                      "type": "string"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "object",
                "properties": {
                  "code": {
                    "type": "string"
                  },
                  "message": {
                    "type": "string"
                  }
                }
              }
            ]
          },
          "code": {
            "type": "string"
          },
          "retryAfter": {
            "type": "number"
          }
        }
      },
      "ScanCompleted": {
        "type": "object",
        "required": [
          "event",
          "createdAt",
          "data"
        ],
        "properties": {
          "event": {
            "const": "scan.completed"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object",
            "properties": {
              "scanned": {
                "type": "integer"
              },
              "products": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "score": {
                      "type": "number"
                    },
                    "riskLevel": {
                      "type": "string"
                    },
                    "flagCount": {
                      "type": "integer"
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}