{
  "openapi": "3.0.3",
  "info": {
    "title": "web4page.org Registry API",
    "description": "REST API for validating, publishing, and resolving Web4 Pages. Canonical server: api.web4page.org.",
    "version": "1.0.0",
    "contact": {
      "name": "web4page.org",
      "url": "https://web4page.org",
      "email": "hello@web4page.org"
    },
    "license": {
      "name": "MIT",
      "url": "https://opensource.org/licenses/MIT"
    }
  },
  "servers": [
    {
      "url": "https://api.web4page.org",
      "description": "Production"
    }
  ],
  "paths": {
    "/v1/registry/validate": {
      "post": {
        "operationId": "validateWeb4Page",
        "summary": "Validate a web4page.json document",
        "tags": ["Registry"],
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/Web4Page" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Valid document",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "valid": { "type": "boolean" },
                    "entityScore": { "type": "integer", "minimum": 0, "maximum": 100 },
                    "vcap": { "$ref": "#/components/schemas/Vcap" }
                  }
                }
              }
            }
          },
          "400": { "description": "Validation failed" }
        }
      }
    },
    "/v1/registry/submit": {
      "post": {
        "operationId": "submitWeb4Page",
        "summary": "Index a Web4 Page in the registry",
        "tags": ["Registry"],
        "security": [{ "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/Web4Page" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Indexed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "indexed": { "type": "boolean" },
                    "url": { "type": "string", "format": "uri" },
                    "entityScore": { "type": "integer" },
                    "slug": { "type": "string" },
                    "vcap": { "$ref": "#/components/schemas/Vcap" }
                  }
                }
              }
            }
          },
          "401": { "description": "API key required" },
          "403": { "description": "Invalid API key" }
        }
      }
    },
    "/v1/registry/{prefix}/{slug}": {
      "get": {
        "operationId": "getRegistryEntity",
        "summary": "Fetch an indexed Web4 Page",
        "tags": ["Registry"],
        "parameters": [
          {
            "name": "prefix",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "enum": ["b", "i", "p", "o", "r"] }
          },
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Web4 Page document",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Web4Page" }
              }
            }
          },
          "404": { "description": "Entity not found" }
        }
      }
    },
    "/v1/registry/{prefix}/{slug}/update": {
      "put": {
        "operationId": "updateRegistryEntity",
        "summary": "Update an indexed Web4 Page",
        "tags": ["Registry"],
        "security": [{ "ApiKeyAuth": [] }],
        "parameters": [
          {
            "name": "prefix",
            "in": "path",
            "required": true,
            "schema": { "type": "string" }
          },
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/Web4Page" }
            }
          }
        },
        "responses": {
          "200": { "description": "Updated" },
          "404": { "description": "Entity not found" }
        }
      }
    },
    "/v1/resolve/register": {
      "post": {
        "operationId": "registerIrlSlug",
        "summary": "Register an IRL slug → host mapping",
        "tags": ["IRL Resolver"],
        "security": [{ "ApiKeyAuth": [] }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["slug", "host", "vcap"],
                "properties": {
                  "slug": { "type": "string" },
                  "host": { "type": "string", "format": "uri" },
                  "trust": { "type": "string", "enum": ["verified", "unverified"] },
                  "vcap": { "$ref": "#/components/schemas/Vcap" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Registered" }
        }
      }
    },
    "/resolve/{slug}": {
      "get": {
        "operationId": "resolveIrlSlug",
        "summary": "Resolve an IRL slug to its VCAP host",
        "tags": ["IRL Resolver"],
        "parameters": [
          { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "IRL resolution record",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "slug": { "type": "string" },
                    "host": { "type": "string", "format": "uri" },
                    "trust": { "type": "string" },
                    "vcap": { "$ref": "#/components/schemas/Vcap" }
                  }
                }
              }
            }
          },
          "404": { "description": "IRL slug not found" }
        }
      }
    },
    "/health": {
      "get": {
        "operationId": "healthCheck",
        "summary": "Service health",
        "tags": ["System"],
        "responses": {
          "200": { "description": "OK" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "X-API-Key"
      }
    },
    "schemas": {
      "Vcap": {
        "type": "object",
        "properties": {
          "read": { "type": "boolean" },
          "discover": { "type": "boolean" },
          "write": { "type": "boolean" },
          "act": { "type": "boolean" }
        }
      },
      "Web4Page": {
        "type": "object",
        "description": "Web4 Page open specification v1",
        "externalDocs": {
          "url": "https://web4page.org/spec/v1/schema.json"
        }
      }
    }
  }
}