{
  "openapi": "3.1.1",
  "info": {
    "title": "HakiChain Public Discovery API",
    "version": "1.0.0",
    "description": "A machine-readable directory of public HakiChain resources. This API does not expose customer or legal-work data. Public API versions remain available for at least 90 days after a successor version is published. A future removal is announced with a Deprecation header and a Sunset header at least 90 days before the removal date. Policy: https://hakichain.com/developers/deprecation-policy"
  },
  "servers": [{ "url": "https://hakichain.com" }],
  "paths": {
    "/api/v1/platform": {
      "get": {
        "operationId": "getHakiChainPlatform",
        "summary": "Get public HakiChain platform resources",
        "description": "Returns links to public documentation, developer resources, the OpenAPI specification, agent instructions, and support. Request text/markdown with an Accept: text/markdown header.",
        "responses": {
          "200": {
            "description": "Public platform metadata",
            "headers": {
              "RateLimit": { "description": "RFC rate-limit policy and remaining capacity.", "schema": { "type": "string" } },
              "RateLimit-Limit": { "schema": { "type": "string" } },
              "RateLimit-Remaining": { "schema": { "type": "string" } },
              "RateLimit-Reset": { "schema": { "type": "string" } },
              "Vary": { "description": "Accept, Accept-Encoding", "schema": { "type": "string" } },
              "Link": { "description": "Link to the deprecation policy.", "schema": { "type": "string" } }
            },
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Platform" }
              },
              "text/markdown": {
                "schema": { "type": "string", "description": "Markdown directory of public HakiChain resources." }
              }
            }
          },
          "405": {
            "description": "Method not allowed",
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          },
          "429": {
            "description": "Rate limit exceeded. Respect Retry-After before retrying.",
            "headers": {
              "Retry-After": { "description": "Seconds until a request may be retried.", "schema": { "type": "integer", "minimum": 0 } },
              "RateLimit": { "description": "RFC rate-limit policy and remaining capacity.", "schema": { "type": "string" } }
            },
            "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Platform": {
        "type": "object",
        "required": ["name", "description", "documentation", "developerResources", "openapi", "agentInstructions", "support"],
        "properties": {
          "name": { "type": "string", "description": "Product name", "example": "HakiChain" },
          "description": { "type": "string", "description": "Product summary" },
          "documentation": { "type": "string", "format": "uri", "description": "Public product documentation" },
          "developerResources": { "type": "string", "format": "uri", "description": "Public developer resources" },
          "openapi": { "type": "string", "format": "uri", "description": "OpenAPI specification URL" },
          "agentInstructions": { "type": "string", "format": "uri", "description": "Agent instruction file URL" },
          "support": { "type": "string", "format": "uri", "description": "Support contact URI" }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message", "hint"],
            "properties": {
              "code": { "type": "string", "description": "Stable machine-readable error code" },
              "message": { "type": "string", "description": "Human-readable error summary" },
              "hint": { "type": "string", "description": "Suggested resolution" }
            }
          }
        }
      }
    }
  }
}