{
  "openapi": "3.1.0",
  "info": {
    "title": "HakiChain Public Discovery API",
    "version": "1.0.0",
    "description": "Machine-readable directory of public HakiChain resources. This API does not expose customer or legal-work data.\n\n## Versioning\nPublic endpoints are versioned in the URL path under `/api/v1`. Breaking changes ship as `/api/v2`.\n\n## Deprecation and Sunset policy\nPublic API versions remain available for at least 90 days after a successor version is published. A future removal is announced with an HTTP `Deprecation` header and an HTTP `Sunset` header at least 90 days before the removal date. Full policy: https://hakichain.com/developers/deprecation-policy",
    "contact": {
      "name": "HakiChain",
      "email": "info@hakichain.com",
      "url": "https://hakichain.com/developers"
    },
    "license": {
      "name": "Proprietary"
    }
  },
  "externalDocs": {
    "description": "HakiChain API deprecation policy — Deprecation and Sunset headers, 90-day notice",
    "url": "https://hakichain.com/developers/deprecation-policy"
  },
  "servers": [
    {
      "url": "https://hakichain.com",
      "description": "Production. Public API versioning uses the `/api/v1` path prefix. Deprecation/Sunset policy: https://hakichain.com/developers/deprecation-policy"
    }
  ],
  "paths": {
    "/api/v1/platform": {
      "get": {
        "operationId": "getHakiChainPlatform",
        "summary": "Get public HakiChain platform resources",
        "description": "Returns typed links to HakiChain documentation, developer resources, the OpenAPI specification, agent instructions, and the API deprecation/Sunset policy. Use this when an agent needs to discover how to integrate with HakiChain before any authenticated customer-data call. Prefer `Accept: application/json` for structured tool results, or `Accept: text/markdown` / `format=markdown` for a Markdown directory.",
        "parameters": [
          {
            "name": "format",
            "in": "query",
            "required": false,
            "description": "Optional response format override. When omitted, negotiate with the Accept header (application/json default).",
            "schema": {
              "type": "string",
              "enum": ["json", "markdown"],
              "default": "json"
            }
          },
          {
            "name": "Accept",
            "in": "header",
            "required": false,
            "description": "Content negotiation. Use application/json (default) or text/markdown.",
            "schema": {
              "type": "string",
              "enum": ["application/json", "text/markdown"],
              "default": "application/json"
            }
          }
        ],
        "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": "Includes rel=deprecation-policy pointing at the Sunset/Deprecation policy page.",
                "schema": { "type": "string" }
              },
              "Deprecation": {
                "description": "RFC 8594 Deprecation header. Present only when this API version is deprecated (true or an HTTP-date).",
                "schema": { "type": "string" },
                "required": false
              },
              "Sunset": {
                "description": "RFC 8594 Sunset header. HTTP-date after which a deprecated version may be removed. HakiChain gives at least 90 days notice.",
                "schema": { "type": "string" },
                "required": false
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "name",
                    "description",
                    "documentation",
                    "developerResources",
                    "openapi",
                    "agentInstructions",
                    "deprecationPolicy",
                    "apiVersion",
                    "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 URL"
                    },
                    "developerResources": {
                      "type": "string",
                      "format": "uri",
                      "description": "HakiChain developer portal URL"
                    },
                    "openapi": {
                      "type": "string",
                      "format": "uri",
                      "description": "OpenAPI specification URL"
                    },
                    "agentInstructions": {
                      "type": "string",
                      "format": "uri",
                      "description": "Agent instruction file (llms.txt) URL"
                    },
                    "deprecationPolicy": {
                      "type": "string",
                      "format": "uri",
                      "description": "URL of the Deprecation and Sunset policy"
                    },
                    "apiVersion": {
                      "type": "string",
                      "description": "Current public URL API version segment",
                      "example": "v1"
                    },
                    "support": {
                      "type": "string",
                      "format": "uri",
                      "description": "Support contact URI"
                    }
                  }
                }
              },
              "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",
        "additionalProperties": false,
        "required": [
          "name",
          "description",
          "documentation",
          "developerResources",
          "openapi",
          "agentInstructions",
          "deprecationPolicy",
          "apiVersion",
          "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" },
          "deprecationPolicy": { "type": "string", "format": "uri", "description": "Deprecation and Sunset policy URL" },
          "apiVersion": { "type": "string", "description": "Current public URL API version", "example": "v1" },
          "support": { "type": "string", "format": "uri", "description": "Support contact URI" }
        }
      },
      "Error": {
        "type": "object",
        "additionalProperties": false,
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "additionalProperties": false,
            "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" }
            }
          }
        }
      }
    }
  }
}