{
 "openapi": "3.1.0",
 "info": {
  "title": "Still Relevant Fax API",
  "version": "1.0.0",
  "description": "Prepare a fax to a fax number in the UK or 108 other countries and get a payment link for a person, or let an agent pay in USDC over x402. £2.49 within the UK and to most of Europe, the US and Canada (up to 25 pages), other countries priced by destination. Charged only if delivered. No API key.",
  "contact": {
   "name": "Still Relevant (Stu Mason Ltd)",
   "email": "help@stillrelevant.uk",
   "url": "https://stillrelevant.uk/fax/api/"
  }
 },
 "servers": [
  {
   "url": "https://stillrelevant.uk"
  }
 ],
 "paths": {
  "/api/v1/faxes": {
   "post": {
    "operationId": "prepareFax",
    "summary": "Prepare a fax and get a pay_url",
    "description": "Converts the document to fax pages and returns a pay_url. Nothing is sent until a person pays at pay_url.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "to"
        ],
        "properties": {
         "to": {
          "type": "string",
          "description": "Fax number. Include the country code (+44 20 7946 0000) or give country; UK numbers work without it.",
          "example": "+44 20 7946 0000"
         },
         "file_url": {
          "type": "string",
          "format": "uri",
          "description": "Public https URL of the document",
          "example": "https://stillrelevant.uk/sample.pdf"
         },
         "file_base64": {
          "type": "string",
          "description": "Document as base64"
         },
         "filename": {
          "type": "string",
          "description": "File name with extension, needed with file_base64"
         },
         "cover": {
          "$ref": "#/components/schemas/Cover"
         },
         "country": {
          "type": "string",
          "description": "Two-letter country code of the fax number if it has no + code. Default GB.",
          "example": "GB"
         }
        },
        "example": {
         "to": "+44 20 7946 0000",
         "file_url": "https://stillrelevant.uk/sample.pdf"
        }
       }
      },
      "multipart/form-data": {
       "schema": {
        "type": "object",
        "required": [
         "to",
         "file"
        ],
        "properties": {
         "to": {
          "type": "string"
         },
         "file": {
          "type": "string",
          "format": "binary"
         }
        }
       }
      }
     }
    },
    "responses": {
     "201": {
      "description": "Prepared",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Fax"
        }
       }
      }
     },
     "400": {
      "$ref": "#/components/responses/Error"
     },
     "422": {
      "$ref": "#/components/responses/Error"
     },
     "429": {
      "$ref": "#/components/responses/Error"
     }
    },
    "security": []
   }
  },
  "/api/fax/{id}": {
   "get": {
    "operationId": "getFax",
    "summary": "Check a fax",
    "parameters": [
     {
      "name": "id",
      "in": "path",
      "required": true,
      "schema": {
       "type": "string"
      }
     }
    ],
    "responses": {
     "200": {
      "description": "Status",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Fax"
        }
       }
      }
     },
     "404": {
      "$ref": "#/components/responses/Error"
     }
    },
    "security": []
   }
  },
  "/x402/fax": {
   "post": {
    "operationId": "payFaxX402",
    "summary": "Send a fax, paid by the agent in USDC (x402)",
    "description": "x402 v2, USDC on Base (eip155:8453). The first call (no PAYMENT-SIGNATURE header) answers 402 with a PAYMENT-REQUIRED header and the prepared fax (pages, price in pounds and USDC, preview link). Retry the same request with PAYMENT-SIGNATURE. Payment is verified when the fax is sent and settled only if it is delivered. Without a valid body the 402 quotes the starting UK price; the exact price depends on the destination.",
    "requestBody": {
     "required": true,
     "content": {
      "application/json": {
       "schema": {
        "type": "object",
        "required": [
         "to"
        ],
        "properties": {
         "to": {
          "type": "string",
          "description": "Fax number. Include the country code (+44 20 7946 0000) or give country; UK numbers work without it.",
          "example": "+44 20 7946 0000"
         },
         "file_url": {
          "type": "string",
          "format": "uri",
          "description": "Public https URL of the document",
          "example": "https://stillrelevant.uk/sample.pdf"
         },
         "file_base64": {
          "type": "string",
          "description": "Document as base64"
         },
         "filename": {
          "type": "string",
          "description": "File name with extension, needed with file_base64"
         },
         "cover": {
          "$ref": "#/components/schemas/Cover"
         },
         "country": {
          "type": "string",
          "description": "Two-letter country code of the fax number if it has no + code. Default GB.",
          "example": "GB"
         }
        },
        "example": {
         "to": "+44 20 7946 0000",
         "file_url": "https://stillrelevant.uk/sample.pdf"
        }
       }
      },
      "multipart/form-data": {
       "schema": {
        "type": "object",
        "required": [
         "to",
         "file"
        ],
        "properties": {
         "to": {
          "type": "string"
         },
         "file": {
          "type": "string",
          "format": "binary"
         }
        }
       }
      }
     }
    },
    "responses": {
     "402": {
      "description": "Payment required (x402 v2). PAYMENT-REQUIRED header carries the requirements; the body repeats them with the prepared fax.",
      "content": {
       "application/json": {
        "schema": {
         "type": "object",
         "properties": {
          "x402Version": {
           "type": "integer"
          },
          "accepts": {
           "type": "array",
           "items": {
            "type": "object"
           }
          },
          "error": {
           "type": "string"
          },
          "fax": {
           "type": [
            "object",
            "null"
           ],
           "properties": {
            "id": {
             "type": "string"
            },
            "to": {
             "type": "string"
            },
            "pages": {
             "type": "integer"
            },
            "price": {
             "type": "string"
            },
            "price_usdc": {
             "type": "string"
            },
            "status_url": {
             "type": "string"
            },
            "preview_url": {
             "type": "string"
            }
           }
          }
         }
        }
       }
      }
     },
     "202": {
      "description": "Paid (verified) and sending. Settled only if delivered.",
      "content": {
       "application/json": {
        "schema": {
         "$ref": "#/components/schemas/Fax"
        }
       }
      }
     },
     "422": {
      "description": "The document could not be prepared."
     }
    }
   }
  }
 },
 "components": {
  "schemas": {
   "Cover": {
    "type": "object",
    "properties": {
     "to": {
      "type": "string"
     },
     "from": {
      "type": "string"
     },
     "note": {
      "type": "string"
     }
    }
   },
   "Fax": {
    "type": "object",
    "properties": {
     "id": {
      "type": "string"
     },
     "status": {
      "type": "string",
      "enum": [
       "ready",
       "paying",
       "queued",
       "sending",
       "retry",
       "delivered",
       "failed",
       "expired"
      ]
     },
     "pages": {
      "type": "integer"
     },
     "to": {
      "type": "string"
     },
     "price": {
      "type": "string"
     },
     "charged": {
      "type": "boolean"
     },
     "pay_url": {
      "type": "string"
     },
     "preview_url": {
      "type": "string"
     },
     "status_url": {
      "type": "string"
     },
     "confirmation_url": {
      "type": "string"
     },
     "reason": {
      "type": "string"
     },
     "note": {
      "type": "string"
     },
     "delivered_at": {
      "type": "string"
     }
    }
   }
  },
  "responses": {
   "Error": {
    "description": "Error",
    "content": {
     "application/json": {
      "schema": {
       "type": "object",
       "properties": {
        "error": {
         "type": "string"
        }
       }
      }
     }
    }
   }
  }
 }
}