{
  "openapi": "3.1.0",
  "info": {
    "title": "ValirScans agent API",
    "version": "5cccc886ae14cbc555866b8d4cae3aeb48c2adf83a012198262f9be0643c36d4",
    "description": "Agent operations for ValirScans. Discovery is advisory: the runtime 402 is authoritative for every payment parameter. Paid results are granted only after verification, settlement and confirmation. A read licence is personal and is not a training licence."
  },
  "servers": [
    {
      "url": "https://valirscans.org"
    }
  ],
  "x-service-info": {
    "categories": [
      "books",
      "comics",
      "media"
    ],
    "docs": {
      "homepage": "https://valirscans.org",
      "apiReference": "/api/ai/openapi.json",
      "llms": "/llms.txt"
    }
  },
  "paths": {
    "/api/ai/pay/series/{slug}/chapters/{number}": {
      "get": {
        "operationId": "buyAgentChapter",
        "summary": "Buy or re-read one paid chapter licence",
        "description": "Returns a personal read licence for one paid chapter after the runtime payment is verified, settled and confirmed. An existing licence is re-read without another charge. This operation is not on sale on this site right now.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            }
          },
          {
            "name": "number",
            "in": "path",
            "required": true,
            "schema": {
              "type": "number",
              "minimum": 0
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Bearer AI-user key; buying also requires the chapters:buy scope."
          },
          {
            "name": "Agent-Order-Token",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "SIGN-IN-WITH-X",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Payment-Authorization",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Accept",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "application/json",
                "text/markdown"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "chapter"
                  ],
                  "properties": {
                    "chapter": {
                      "type": "string"
                    },
                    "format": {
                      "type": "string"
                    },
                    "html": {
                      "type": "string"
                    },
                    "paragraphs": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "pages": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  }
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "202": {
            "description": "Accepted; check the order for the final state",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "code",
                    "detail",
                    "orderId",
                    "statusUrl"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "const": "pending"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "Agent-Order-Token": {
                "schema": {
                  "type": "string"
                },
                "description": "Secret order token for polling and re-reading; not present on a replay."
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication is required or refused",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required; the runtime challenge is authoritative",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            },
            "headers": {
              "PAYMENT-REQUIRED": {
                "schema": {
                  "type": "string"
                },
                "description": "Present when x402 is enabled."
              },
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                },
                "description": "Payment challenge present when MPP is enabled."
              }
            }
          },
          "403": {
            "description": "This caller or content is not allowed",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "The request conflicts with the current state; do not pay again",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many requests; wait for Retry-After",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "500": {
            "description": "The response could not be rendered; an existing licence still stands",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; no paid result is granted",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      }
    },
    "/api/ai/pay/orders/{orderId}": {
      "get": {
        "operationId": "getAgentPaymentOrder",
        "summary": "Check an agent payment order",
        "description": "Returns the buyer-safe state of one order to its order-token holder, AI user or payer. It never returns chapter text.",
        "parameters": [
          {
            "name": "orderId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Bearer AI-user key; buying also requires the chapters:buy scope."
          },
          {
            "name": "Agent-Order-Token",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "SIGN-IN-WITH-X",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "orderId",
                    "state",
                    "chapter",
                    "amount",
                    "network",
                    "txHash",
                    "nextStep"
                  ],
                  "properties": {
                    "orderId": {
                      "type": "string"
                    },
                    "state": {
                      "type": "string"
                    },
                    "chapter": {
                      "type": "object",
                      "required": [
                        "series",
                        "number"
                      ],
                      "properties": {
                        "series": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "number": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      }
                    },
                    "amount": {
                      "type": "object",
                      "required": [
                        "currency",
                        "micro",
                        "usd"
                      ],
                      "properties": {
                        "currency": {
                          "type": "string"
                        },
                        "micro": {
                          "type": "string",
                          "pattern": "^(0|[1-9][0-9]*)$"
                        },
                        "usd": {
                          "type": "string"
                        }
                      }
                    },
                    "network": {
                      "type": "string"
                    },
                    "txHash": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "nextStep": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication is required or refused",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "This caller or content is not allowed",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found"
          },
          "429": {
            "description": "Too many requests; wait for Retry-After",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; no paid result is granted",
            "content": {
              "application/json; charset=utf-8": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      }
    },
    "/api/ai/pay/orders/{orderId}/refund-request": {
      "post": {
        "operationId": "requestAgentPaymentRefund",
        "summary": "Request a full refund review",
        "description": "Opens a refund request for the order's authorised holder. A request does not move money or change the payment state by itself.",
        "parameters": [
          {
            "name": "orderId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1
            }
          },
          {
            "name": "Authorization",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Bearer AI-user key; buying also requires the chapters:buy scope."
          },
          {
            "name": "Agent-Order-Token",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "SIGN-IN-WITH-X",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "Accepted; check the order for the final state",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "state": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication is required or refused",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "This caller or content is not allowed",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "404": {
            "description": "Not found",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "The request conflicts with the current state; do not pay again",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many requests; wait for Retry-After",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; no paid result is granted",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      }
    },
    "/api/ai/pay/siwx": {
      "get": {
        "operationId": "getAgentSiwxNonce",
        "summary": "Get a SIGN-IN-WITH-X nonce",
        "description": "Issues a short-lived, origin-bound, single-use nonce and message for wallet-based licence re-access.",
        "parameters": [],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "nonce",
                    "domain",
                    "uri",
                    "statement",
                    "version",
                    "chainId",
                    "network",
                    "issuedAt",
                    "expirationTime",
                    "message"
                  ],
                  "properties": {
                    "nonce": {
                      "type": "string",
                      "pattern": "^[0-9a-f]{32}$"
                    },
                    "domain": {
                      "type": "string"
                    },
                    "uri": {
                      "type": "string",
                      "format": "uri"
                    },
                    "statement": {
                      "type": "string"
                    },
                    "version": {
                      "type": "string",
                      "const": "1"
                    },
                    "chainId": {
                      "type": "integer",
                      "enum": [
                        8453,
                        84532
                      ]
                    },
                    "network": {
                      "type": "string",
                      "enum": [
                        "eip155:8453",
                        "eip155:84532"
                      ]
                    },
                    "issuedAt": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "expirationTime": {
                      "type": "string",
                      "format": "date-time"
                    },
                    "message": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many requests; wait for Retry-After",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; no paid result is granted",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      }
    },
    "/api/ai/pay/licence": {
      "get": {
        "operationId": "getAgentReadLicence",
        "summary": "Read the agent chapter licence",
        "description": "Returns the personal read licence as Markdown, or as JSON when Accept includes application/json. A read licence is not a training licence.",
        "parameters": [
          {
            "name": "Accept",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "application/json",
                "text/markdown"
              ]
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "version",
                    "status",
                    "approved",
                    "terms",
                    "readLicenceNotTrainingLicence"
                  ],
                  "properties": {
                    "version": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "enum": [
                        "draft",
                        "approved"
                      ]
                    },
                    "approved": {
                      "type": "boolean"
                    },
                    "terms": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "readLicenceNotTrainingLicence": {
                      "type": "boolean",
                      "const": true
                    }
                  }
                }
              },
              "text/markdown": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "429": {
            "description": "Too many requests; wait for Retry-After",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; no paid result is granted",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      }
    },
    "/api/ai/pay/credits": {
      "get": {
        "operationId": "getAgentCredits",
        "summary": "Read an AI user's operation-credit balance",
        "description": "Returns the AI user's remaining prepaid operation calls. Catalogue calls inside the published free quota stay free.",
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Bearer AI-user key; buying also requires the chapters:buy scope."
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "calls": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "remaining": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "expiresAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication is required or refused",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "403": {
            "description": "This caller or content is not allowed",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many requests; wait for Retry-After",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; no paid result is granted",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "buyAgentCredits",
        "summary": "Buy a prepaid operation-credit pack",
        "description": "Buys extra operation calls for an AI user after the runtime payment is verified, settled and confirmed. The free quota is unchanged. This operation is not on sale on this site right now.",
        "parameters": [
          {
            "name": "Authorization",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Bearer AI-user key; buying also requires the chapters:buy scope."
          },
          {
            "name": "PAYMENT-SIGNATURE",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Payment-Authorization",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "calls": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "remaining": {
                      "type": "integer",
                      "minimum": 0
                    },
                    "expiresAt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    }
                  }
                }
              }
            }
          },
          "202": {
            "description": "Accepted; check the order for the final state",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "type",
                    "title",
                    "status",
                    "code",
                    "detail",
                    "orderId",
                    "statusUrl"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "string",
                      "const": "pending"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    }
                  }
                }
              }
            },
            "headers": {
              "Agent-Order-Token": {
                "schema": {
                  "type": "string"
                },
                "description": "Secret order token for polling and re-reading; not present on a replay."
              },
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "400": {
            "description": "The request is malformed",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Authentication is required or refused",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Payment required; the runtime challenge is authoritative",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            },
            "headers": {
              "PAYMENT-REQUIRED": {
                "schema": {
                  "type": "string"
                },
                "description": "Present when x402 is enabled."
              },
              "WWW-Authenticate": {
                "schema": {
                  "type": "string"
                },
                "description": "Payment challenge present when MPP is enabled."
              }
            }
          },
          "403": {
            "description": "This caller or content is not allowed",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "409": {
            "description": "The request conflicts with the current state; do not pay again",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            }
          },
          "429": {
            "description": "Too many requests; wait for Retry-After",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          },
          "503": {
            "description": "Temporarily unavailable; no paid result is granted",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "status",
                    "detail"
                  ],
                  "properties": {
                    "type": {
                      "type": "string",
                      "format": "uri"
                    },
                    "title": {
                      "type": "string"
                    },
                    "status": {
                      "type": "integer"
                    },
                    "code": {
                      "type": "string"
                    },
                    "detail": {
                      "type": "string"
                    },
                    "orderId": {
                      "type": "string"
                    },
                    "statusUrl": {
                      "type": "string"
                    },
                    "offer": {
                      "type": "object"
                    }
                  }
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            }
          }
        }
      }
    }
  }
}