{
  "openapi": "3.1.0",
  "info": {
    "title": "The Coloring Collection Agent API",
    "version": "1.0.0"
  },
  "servers": [
    {
      "url": "/"
    }
  ],
  "components": {
    "securitySchemes": {
      "OrderToken": {
        "type": "apiKey",
        "in": "header",
        "name": "X-Order-Token",
        "description": "Buyer-held cryptographically random 64-character lowercase hex capability. Never publish it."
      }
    },
    "schemas": {
      "OrderRequest": {
        "type": "object",
        "required": [
          "book",
          "max_total",
          "billing_address",
          "terms_version",
          "authorized_by_buyer",
          "immediate_delivery",
          "withdrawal_acknowledged"
        ],
        "properties": {
          "book": {
            "type": "string"
          },
          "max_total": {
            "type": "integer",
            "minimum": 499,
            "maximum": 10000
          },
          "billing_address": {
            "type": "object",
            "required": [
              "country"
            ],
            "properties": {
              "country": {
                "type": "string"
              },
              "postal_code": {
                "type": "string"
              },
              "state": {
                "type": "string"
              },
              "city": {
                "type": "string"
              },
              "line1": {
                "type": "string"
              },
              "line2": {
                "type": "string"
              }
            }
          },
          "terms_version": {
            "type": "string"
          },
          "authorized_by_buyer": {
            "const": true
          },
          "immediate_delivery": {
            "const": true
          },
          "withdrawal_acknowledged": {
            "const": true
          }
        }
      }
    }
  },
  "paths": {
    "/api/agent/catalog": {
      "get": {
        "summary": "Read product offers and current availability",
        "responses": {
          "200": {
            "description": "Catalog; null Amazon URLs are unavailable placeholders."
          }
        }
      }
    },
    "/api/agent/orders": {
      "post": {
        "summary": "Create or recover one buyer-authorized, tax-calculated PDF order",
        "security": [
          {
            "OrderToken": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrderRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "New order, total, expiry and pay URL"
          },
          "200": {
            "description": "Existing order for the same token"
          },
          "400": {
            "description": "Missing consent or invalid input"
          },
          "409": {
            "description": "Budget exceeded or token reused for different details"
          },
          "503": {
            "description": "Purchases disabled"
          }
        }
      }
    },
    "/api/agent/orders/{id}": {
      "get": {
        "summary": "Recover order status, receipt and refreshed paid downloads",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "OrderToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Order or claim result"
          },
          "401": {
            "description": "Missing capability or account session"
          },
          "402": {
            "description": "MPP payment challenge (pay only)"
          },
          "403": {
            "description": "Payment/refund/origin check failed"
          },
          "404": {
            "description": "Unknown order or wrong capability"
          },
          "409": {
            "description": "In progress or ownership conflict; do not create another purchase"
          },
          "410": {
            "description": "Unpaid order expired"
          },
          "503": {
            "description": "Purchases disabled"
          }
        }
      }
    },
    "/api/agent/orders/{id}/pay": {
      "post": {
        "summary": "Obtain an MPP challenge or complete the authorized payment",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "schema": {
              "type": "string"
            },
            "description": "MPP Payment credential from a compatible wallet after buyer authorization."
          }
        ],
        "security": [
          {
            "OrderToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Order or claim result"
          },
          "401": {
            "description": "Missing capability or account session"
          },
          "402": {
            "description": "MPP payment challenge (pay only)"
          },
          "403": {
            "description": "Payment/refund/origin check failed"
          },
          "404": {
            "description": "Unknown order or wrong capability"
          },
          "409": {
            "description": "In progress or ownership conflict; do not create another purchase"
          },
          "410": {
            "description": "Unpaid order expired"
          },
          "503": {
            "description": "Purchases disabled"
          }
        }
      }
    },
    "/api/agent/orders/{id}/claim": {
      "post": {
        "summary": "Attach a paid order to the signed-in human account",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "security": [
          {
            "OrderToken": []
          }
        ],
        "responses": {
          "200": {
            "description": "Order or claim result"
          },
          "401": {
            "description": "Missing capability or account session"
          },
          "402": {
            "description": "MPP payment challenge (pay only)"
          },
          "403": {
            "description": "Payment/refund/origin check failed"
          },
          "404": {
            "description": "Unknown order or wrong capability"
          },
          "409": {
            "description": "In progress or ownership conflict; do not create another purchase"
          },
          "410": {
            "description": "Unpaid order expired"
          },
          "503": {
            "description": "Purchases disabled"
          }
        },
        "description": "Requires same-origin request and authenticated Google account cookie, plus private order token. No account linking by email."
      }
    },
    "/api/samples/{slug}/{format}": {
      "get": {
        "summary": "Download a free three-design sample without authentication or payment",
        "security": [],
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "mandalas-botanical"
              ]
            }
          },
          {
            "name": "format",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": [
                "a4",
                "letter"
              ]
            }
          }
        ],
        "responses": {
          "302": {
            "description": "Redirect to public sample PDF. Follow Location; no payment required."
          },
          "404": {
            "description": "Unknown sample or format"
          },
          "429": {
            "description": "Please retry later"
          }
        }
      }
    }
  }
}