{
  "openapi": "3.1.0",
  "info": {
    "title": "Orvane public website assessments",
    "version": "1.0.0",
    "description": "Anonymous server-to-server API. One shared free completed report per website across browser, API and MCP. Available jobs/reports are reused; no credit spending. Reports expire after 30 days. Keep evidence and limitations in summaries."
  },
  "servers": [
    {
      "url": "https://orvane.co.ke"
    }
  ],
  "security": [],
  "paths": {
    "/api/v1/scans": {
      "post": {
        "operationId": "startScan",
        "summary": "Start or reuse a website assessment",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "url"
                ],
                "properties": {
                  "url": {
                    "type": "string",
                    "maxLength": 2048,
                    "minLength": 1
                  }
                }
              },
              "example": {
                "url": "https://example.com"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Reused available report or active job.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Scan"
                }
              }
            }
          },
          "202": {
            "description": "New job queued. Poll after 10 seconds.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Scan"
                }
              }
            }
          },
          "400": {
            "description": "Structured error; retryAfter and Retry-After on retryable failures. FREE_REPORT_USED includes nextUrl.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "402": {
            "description": "Structured error; retryAfter and Retry-After on retryable failures. FREE_REPORT_USED includes nextUrl.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "description": "Structured error; retryAfter and Retry-After on retryable failures. FREE_REPORT_USED includes nextUrl.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Structured error; retryAfter and Retry-After on retryable failures. FREE_REPORT_USED includes nextUrl.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Structured error; retryAfter and Retry-After on retryable failures. FREE_REPORT_USED includes nextUrl.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/scans/{id}": {
      "get": {
        "operationId": "getScan",
        "summary": "Read progress and available report findings",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Assessment job or report. Results are present on GET; null until findings are available.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Scan"
                }
              }
            }
          },
          "403": {
            "description": "Structured error; retryAfter and Retry-After on retryable failures. FREE_REPORT_USED includes nextUrl.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "Structured error; retryAfter and Retry-After on retryable failures. FREE_REPORT_USED includes nextUrl.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "Structured error; retryAfter and Retry-After on retryable failures. FREE_REPORT_USED includes nextUrl.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "503": {
            "description": "Structured error; retryAfter and Retry-After on retryable failures. FREE_REPORT_USED includes nextUrl.",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Scan": {
        "type": "object",
        "required": [
          "apiVersion",
          "id",
          "url",
          "status",
          "edition",
          "reportUrl",
          "pollAfterSeconds",
          "createdAt",
          "startedAt",
          "finishedAt",
          "expiresAt",
          "error"
        ],
        "properties": {
          "apiVersion": {
            "const": "1"
          },
          "id": {
            "type": "string",
            "format": "uuid"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "status": {
            "type": "string",
            "enum": [
              "queued",
              "running",
              "completed",
              "partial",
              "failed"
            ]
          },
          "edition": {
            "type": "string",
            "enum": [
              "foundation-1",
              "growth-1"
            ]
          },
          "reportUrl": {
            "type": "string",
            "format": "uri"
          },
          "pollAfterSeconds": {
            "type": [
              "integer",
              "null"
            ],
            "description": "10 while queued or running; null otherwise."
          },
          "reused": {
            "type": "boolean",
            "description": "Present on creation responses."
          },
          "progress": {
            "type": "object",
            "properties": {
              "stage": {
                "type": "string"
              }
            }
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          },
          "startedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "finishedAt": {
            "type": [
              "string",
              "null"
            ]
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time"
          },
          "error": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/ErrorDetail"
              }
            ]
          },
          "results": {
            "oneOf": [
              {
                "type": "null"
              },
              {
                "$ref": "#/components/schemas/Results"
              }
            ]
          }
        }
      },
      "Results": {
        "type": "object",
        "required": [
          "total",
          "summary",
          "priorities",
          "areas",
          "evidence",
          "coverage",
          "limitations"
        ],
        "properties": {
          "total": {
            "type": [
              "number",
              "null"
            ]
          },
          "summary": {
            "type": "string"
          },
          "priorities": {
            "type": "array",
            "maxItems": 3,
            "items": {
              "type": "object",
              "required": [
                "title",
                "detail"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "detail": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "area": {
                  "type": "string"
                },
                "impact": {
                  "type": "string"
                },
                "evidenceId": {
                  "type": "string",
                  "description": "Check identifier matching an item in evidence."
                },
                "observation": {
                  "type": "string"
                },
                "verification": {
                  "type": "string"
                }
              }
            }
          },
          "areas": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "key": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "points": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "status": {
                  "type": "string"
                },
                "reason": {
                  "type": "string"
                },
                "evidence": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Evidence"
                  }
                }
              }
            }
          },
          "evidence": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Evidence"
            }
          },
          "coverage": {
            "type": "object",
            "properties": {
              "pages": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "answers": {
                "type": "integer"
              },
              "expectedAnswers": {
                "type": "integer"
              },
              "sampling": {
                "type": "object",
                "properties": {
                  "questions": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    }
                  },
                  "runsPerQuestion": {
                    "const": 2
                  },
                  "planned": {
                    "const": 10
                  },
                  "completed": {
                    "type": "integer"
                  },
                  "systems": {
                    "const": 1
                  },
                  "assessedAt": {
                    "type": "string",
                    "format": "date-time"
                  },
                  "points": {
                    "type": [
                      "number",
                      "null"
                    ]
                  }
                }
              }
            }
          },
          "limitations": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "googleIndexing": {
            "const": "not_verified",
            "description": "Actual Google indexing was not verified."
          }
        }
      },
      "Evidence": {
        "type": "object",
        "required": [
          "title",
          "detail",
          "at"
        ],
        "properties": {
          "title": {
            "type": "string"
          },
          "detail": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "excerpt": {
            "type": "string"
          },
          "action": {
            "type": "string"
          },
          "value": {
            "type": "number"
          },
          "checkId": {
            "type": "string"
          },
          "outcome": {
            "enum": [
              "passed",
              "failed",
              "ambiguous",
              "unavailable"
            ]
          },
          "verify": {
            "type": "string"
          }
        }
      },
      "ErrorDetail": {
        "type": "object",
        "required": [
          "code",
          "message"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "retryAfter": {
            "type": "integer"
          },
          "nextUrl": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "$ref": "#/components/schemas/ErrorDetail"
          }
        }
      }
    }
  }
}
