{
  "openapi": "3.1.0",
  "info": {
    "title": "Web4Strategy Public API",
    "version": "1.0.0",
    "description": "Version 1 read-only JSON endpoints for Web4Strategy's public skills, prompts, specifications, directories, metadata, and agent capability discovery. Public reads are keyless for discoverability and protected by lightweight per-client edge throttles. Send X-Web4Strategy-API-Version: 1 or omit the header to use the current version. Use the standard RateLimit-* response headers and Retry-After after 429 responses.",
    "contact": {
      "name": "Web4Strategy",
      "url": "https://web4strategy.com/contact",
      "email": "hello@web4strategy.com"
    }
  },
  "servers": [
    {
      "url": "https://web4strategy.com",
      "description": "Production API"
    }
  ],
  "externalDocs": {
    "description": "Agent integration guide",
    "url": "https://web4strategy.com/llms.txt"
  },
  "x-api-versioning": {
    "strategy": "request-header",
    "requestHeader": "X-Web4Strategy-API-Version",
    "responseHeader": "X-Web4Strategy-API-Version",
    "currentVersion": "1",
    "supportedVersions": ["1"],
    "defaultWhenHeaderOmitted": "1",
    "deprecation": {
      "signalHeaders": ["Deprecation", "Sunset"],
      "minimumNoticeDays": 90,
      "policyUrl": "https://web4strategy.com/api/versioning.md"
    }
  },
  "x-developer-resources": {
    "url": "https://web4strategy.com/developers",
    "cli": "https://web4strategy.com/cli"
  },
  "x-rate-limit-headers": ["RateLimit-Limit", "RateLimit-Remaining", "RateLimit-Reset", "RateLimit-Policy", "Retry-After"],
  "paths": {
    "/api/agent/capabilities": {
      "get": {
        "operationId": "getAgentCapabilities",
        "summary": "Get agent capabilities",
        "description": "Return when-to-use guidance and links for Web4Strategy's public machine-readable interfaces.",
        "x-rate-limit": {
          "requests": 60,
          "windowSeconds": 60
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "Agent capability document.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentCapabilities"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/metadata": {
      "get": {
        "operationId": "getPageMetadata",
        "summary": "Extract public page metadata",
        "description": "Fetch a public HTTP(S) page and return its title, description, Open Graph image, Twitter image, favicon, and related metadata.",
        "x-rate-limit": {
          "requests": 12,
          "windowSeconds": 60
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          },
          {
            "$ref": "#/components/parameters/Url"
          }
        ],
        "responses": {
          "200": {
            "description": "Extracted page metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PageMetadata"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "502": {
            "$ref": "#/components/responses/UpstreamError"
          },
          "504": {
            "$ref": "#/components/responses/Timeout"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/skills": {
      "get": {
        "operationId": "searchSkills",
        "summary": "Search public agent skills",
        "description": "Search the public Agentic Skills registry with optional query, category, sort, page, and limit filters.",
        "x-rate-limit": {
          "requests": 60,
          "windowSeconds": 60
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          },
          {
            "$ref": "#/components/parameters/Query"
          },
          {
            "$ref": "#/components/parameters/Category"
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "description": "A paginated public skills directory result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DirectoryResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/prompts": {
      "get": {
        "operationId": "searchPrompts",
        "summary": "Search public prompts",
        "description": "Search the public prompts library with optional query, category, sort, page, and limit filters.",
        "x-rate-limit": {
          "requests": 60,
          "windowSeconds": 60
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          },
          {
            "$ref": "#/components/parameters/Query"
          },
          {
            "$ref": "#/components/parameters/Category"
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "description": "A paginated public prompts directory result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DirectoryResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/prds": {
      "get": {
        "operationId": "searchProductSpecifications",
        "summary": "Search public product specifications",
        "description": "Search open product requirements documents and technical specifications.",
        "x-rate-limit": {
          "requests": 60,
          "windowSeconds": 60
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          },
          {
            "$ref": "#/components/parameters/Query"
          },
          {
            "$ref": "#/components/parameters/Category"
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "description": "A paginated public product specifications result.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DirectoryResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/bots": {
      "get": {
        "operationId": "listPublicBots",
        "summary": "List public bots",
        "description": "Return the public bot directory as a versioned JSON document.",
        "x-rate-limit": {
          "requests": 60,
          "windowSeconds": 60
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "description": "Public bot directory.",
            "content": {
              "application/json": {
                  "schema": {
                  "$ref": "#/components/schemas/PublicBotListResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/outbid": {
      "get": {
        "operationId": "listPublicDirectorySites",
        "summary": "List public directory sites",
        "description": "Return public directory listings and pagination metadata for the selected directory type.",
        "x-rate-limit": {
          "requests": 60,
          "windowSeconds": 60
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          },
          {
            "name": "type",
            "in": "query",
            "description": "Directory type.",
            "schema": {
              "type": "string",
              "default": "startups"
            }
          },
          {
            "$ref": "#/components/parameters/Page"
          },
          {
            "$ref": "#/components/parameters/Limit"
          }
        ],
        "responses": {
          "200": {
            "description": "Public directory listings.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OutbidResult"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/seo-settings": {
      "get": {
        "operationId": "getPublicSeoSettings",
        "summary": "Get public SEO settings",
        "description": "Return public site metadata used to resolve Web4Strategy identity and canonical URLs.",
        "x-rate-limit": {
          "requests": 60,
          "windowSeconds": 60
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "Public SEO settings.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSettings"
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    },
    "/api/agentic-skills-settings": {
      "get": {
        "operationId": "getAgenticSkillsSettings",
        "summary": "Get public registry settings",
        "description": "Return feature availability and public pagination settings for agentic registry surfaces.",
        "x-rate-limit": {
          "requests": 60,
          "windowSeconds": 60
        },
        "parameters": [
          {
            "$ref": "#/components/parameters/ApiVersion"
          }
        ],
        "responses": {
          "200": {
            "description": "Public agentic registry settings.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicSettings"
                }
              }
            }
          },
          "503": {
            "$ref": "#/components/responses/ServiceUnavailable"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          },
          "500": {
            "$ref": "#/components/responses/InternalError"
          }
        }
      }
    }
  },
  "components": {
    "parameters": {
      "ApiVersion": {
        "name": "X-Web4Strategy-API-Version",
        "in": "header",
        "required": false,
        "description": "Public API version. Omit this header to use the current version.",
        "schema": {
          "type": "string",
          "enum": ["1"],
          "default": "1"
        }
      },
      "Url": {
        "name": "url",
        "in": "query",
        "required": true,
        "description": "Absolute HTTP(S) URL of a public page.",
        "schema": {
          "type": "string",
          "format": "uri",
          "pattern": "^https?://",
          "maxLength": 2000
        }
      },
      "Query": {
        "name": "q",
        "in": "query",
        "required": false,
        "description": "Free-text search query.",
        "schema": {
          "type": "string",
          "maxLength": 160
        }
      },
      "Category": {
        "name": "category",
        "in": "query",
        "required": false,
        "description": "Category slug filter.",
        "schema": {
          "type": "string",
          "maxLength": 80
        }
      },
      "Page": {
        "name": "page",
        "in": "query",
        "required": false,
        "description": "One-based page number.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "default": 1
        }
      },
      "Limit": {
        "name": "limit",
        "in": "query",
        "required": false,
        "description": "Maximum number of records to return.",
        "schema": {
          "type": "integer",
          "minimum": 1,
          "maximum": 500,
          "default": 24
        }
      }
    },
    "responses": {
      "BadRequest": {
        "description": "The request did not pass boundary validation.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "UpstreamError": {
        "description": "The requested public page returned an upstream error.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "Timeout": {
        "description": "The requested public page did not respond before the timeout.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "ServiceUnavailable": {
        "description": "The public data source is temporarily unavailable.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "RateLimited": {
        "description": "The client exceeded the documented request budget.",
        "headers": {
          "RateLimit-Limit": {
            "$ref": "#/components/headers/RateLimitLimit"
          },
          "RateLimit-Remaining": {
            "$ref": "#/components/headers/RateLimitRemaining"
          },
          "RateLimit-Reset": {
            "$ref": "#/components/headers/RateLimitReset"
          },
          "RateLimit-Policy": {
            "$ref": "#/components/headers/RateLimitPolicy"
          },
          "Retry-After": {
            "$ref": "#/components/headers/RetryAfter"
          }
        },
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "InternalError": {
        "description": "The service could not complete the request.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        }
      },
      "DirectoryResult": {
        "description": "A paginated public directory result.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/DirectoryResult"
            }
          }
        }
      },
      "JsonObject": {
        "description": "A structured JSON object.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/PublicSettings"
            }
          }
        }
      }
    },
    "headers": {
      "RateLimitLimit": {
        "description": "Maximum requests in the active rate-limit window.",
        "schema": { "type": "integer", "minimum": 0 }
      },
      "RateLimitRemaining": {
        "description": "Requests remaining in the active rate-limit window.",
        "schema": { "type": "integer", "minimum": 0 }
      },
      "RateLimitReset": {
        "description": "Seconds until the active rate-limit window resets.",
        "schema": { "type": "integer", "minimum": 0 }
      },
      "RateLimitPolicy": {
        "description": "The active quota policy, expressed as requests per window.",
        "schema": { "type": "string", "pattern": "^[0-9]+;w=[0-9]+$" }
      },
      "RetryAfter": {
        "description": "Seconds to wait before retrying after HTTP 429.",
        "schema": { "type": "integer", "minimum": 1 }
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error", "message", "resolution", "statusCode"],
        "properties": {
          "error": {
            "type": "string",
            "description": "Stable machine-readable error code."
          },
          "message": {
            "type": "string",
            "description": "Human-readable explanation."
          },
          "resolution": {
            "type": "string",
            "description": "Suggested next step for an agent or developer."
          },
          "statusCode": {
            "type": "integer"
          }
        }
      },
      "AgentCapabilities": {
        "type": "object",
        "required": ["name", "version", "description", "whenToUse", "links", "access", "rateLimits", "apiVersioning"],
        "properties": {
          "name": {
            "type": "string"
          },
          "version": {
            "type": "integer"
          },
          "description": {
            "type": "string"
          },
          "whenToUse": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "links": {
            "type": "object",
            "additionalProperties": {
              "type": "string",
              "format": "uri"
            }
          },
          "access": {
            "type": "object",
            "required": ["publicReadOnly", "freeTier", "authentication", "sandbox", "destructiveActions"],
            "properties": {
              "publicReadOnly": { "type": "boolean" },
              "freeTier": { "type": "boolean" },
              "authentication": { "type": "string" },
              "sandbox": { "type": "string" },
              "destructiveActions": { "type": "string" }
            }
          },
          "rateLimits": {
            "type": "object",
            "required": ["windowSeconds", "buckets", "responseHeaders"],
            "properties": {
              "identity": { "type": "string" },
              "windowSeconds": { "type": "integer", "minimum": 1 },
              "buckets": {
                "type": "object",
                "additionalProperties": { "type": "integer", "minimum": 1 }
              },
              "responseHeaders": {
                "type": "array",
                "items": { "type": "string" }
              },
              "legacyResponseHeaders": {
                "type": "array",
                "items": { "type": "string" }
              }
            }
          },
          "apiVersioning": {
            "type": "object",
            "required": ["current", "requestHeader", "policy"],
            "properties": {
              "current": { "type": "string" },
              "requestHeader": { "type": "string" },
              "policy": { "type": "string", "format": "uri" }
            }
          }
        }
      },
      "AgenticResource": {
        "type": "object",
        "description": "A public registry record. Additional documented fields may be added without changing the response envelope.",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "title": { "type": "string" },
          "description": { "type": "string" },
          "category": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "updatedAt": { "type": "string", "format": "date-time" }
        },
        "additionalProperties": true
      },
      "PageMetadata": {
        "type": "object",
        "required": ["url", "title", "description"],
        "properties": {
          "url": {
            "type": "string",
            "format": "uri"
          },
          "title": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "image": {
            "type": "string",
            "format": "uri"
          },
          "ogImage": {
            "type": "string",
            "format": "uri"
          },
          "twitterImage": {
            "type": "string",
            "format": "uri"
          },
          "favicon": {
            "type": "string",
            "format": "uri"
          },
          "siteName": {
            "type": "string"
          },
          "locale": {
            "type": "string"
          }
        }
      },
      "DirectoryResult": {
        "type": "object",
        "required": ["pagination"],
        "properties": {
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          },
          "skills": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgenticResource"
            }
          },
          "prompts": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgenticResource"
            }
          },
          "prds": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgenticResource"
            }
          }
        }
      },
      "Pagination": {
        "type": "object",
        "required": ["page", "limit", "total", "hasMore"],
        "properties": {
          "page": {
            "type": "integer",
            "minimum": 1
          },
          "limit": {
            "type": "integer",
            "minimum": 1
          },
          "total": {
            "type": "integer",
            "minimum": 0
          },
          "hasMore": {
            "type": "boolean"
          }
        }
      },
      "PublicBot": {
        "type": "object",
        "required": ["id", "name", "description"],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "category": {
            "type": "string"
          }
        },
        "additionalProperties": true
      },
      "PublicBotListResult": {
        "type": "object",
        "required": ["version", "bots"],
        "properties": {
          "version": {
            "type": "integer",
            "const": 1
          },
          "bots": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/PublicBot"
            }
          },
          "pagination": {
            "$ref": "#/components/schemas/Pagination"
          }
        }
      },
      "PublicSettings": {
        "type": "object",
        "description": "Public settings document. Known common fields are typed; forward-compatible settings are preserved.",
        "properties": {
          "version": { "type": "integer" },
          "enabled": { "type": "boolean" },
          "siteName": { "type": "string" },
          "siteUrl": { "type": "string", "format": "uri" },
          "pageSize": { "type": "integer", "minimum": 1 },
          "maxPageSize": { "type": "integer", "minimum": 1 }
        },
        "additionalProperties": true
      },
      "OutbidResult": {
        "type": "object",
        "required": ["sites", "total", "page", "perPage"],
        "properties": {
          "source": {
            "type": "string"
          },
          "sites": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/AgenticResource"
            }
          },
          "total": {
            "type": "integer",
            "minimum": 0
          },
          "page": {
            "type": "integer",
            "minimum": 1
          },
          "perPage": {
            "type": "integer",
            "minimum": 1
          }
        }
      }
    }
  }
}