{
  "openapi": "3.0.3",
  "info": {
    "title": "Corhack Public REST API",
    "version": "1.0.0",
    "description": "Self-describing machine-readable API for Corhack (Altamsun LTD). Provides product discovery, evidence-led health guides, application metadata, and agent integration contracts.",
    "contact": {
      "name": "Corhack Support",
      "email": "support@corhack.com",
      "url": "https://corhack.com/contact"
    },
    "license": {
      "name": "Proprietary",
      "url": "https://corhack.com/terms"
    }
  },
  "servers": [
    {
      "url": "https://corhack.com",
      "description": "Corhack Production API Server"
    }
  ],
  "paths": {
    "/api/v1/site": {
      "get": {
        "operationId": "getSiteMetadata",
        "summary": "Get Corhack product and discovery metadata",
        "description": "Returns official site metadata, store download links, brand boundaries, and canonical discovery URLs for AI agents and developers.",
        "responses": {
          "200": {
            "description": "Public Corhack site metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SiteMetadata"
                }
              }
            }
          },
          "405": {
            "description": "Method not allowed.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/health": {
      "get": {
        "operationId": "getApiHealth",
        "summary": "Get API health and availability status",
        "description": "Returns the operational status, current version, and UTC timestamp of the Corhack API service.",
        "responses": {
          "200": {
            "description": "API health status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/HealthResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/products": {
      "get": {
        "operationId": "listProducts",
        "summary": "List Corhack product features and membership options",
        "description": "Returns descriptions of core app components (Signals, Protocol, Companion Coach) and official membership tiers.",
        "responses": {
          "200": {
            "description": "Product features and membership details.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProductsResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/library": {
      "get": {
        "operationId": "listLibraryArticles",
        "summary": "List evidence-led health guides in the Signal Library",
        "description": "Returns summaries of published Signal Library guides with evidence classifications, topics, and canonical URLs.",
        "responses": {
          "200": {
            "description": "List of library articles.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LibraryListResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/library/{slug}": {
      "get": {
        "operationId": "getLibraryArticleBySlug",
        "summary": "Get a specific Signal Library article by slug",
        "description": "Returns the complete details, key takeaways, clinical uncertainty boundaries, and cited academic sources for an article.",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "description": "Unique URL slug identifier of the article (e.g. 'what-testosterone-does').",
            "schema": {
              "type": "string",
              "example": "what-testosterone-does"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Detailed library article record.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LibraryArticleDetail"
                }
              }
            }
          },
          "404": {
            "description": "Article slug not found.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "SiteMetadata": {
        "type": "object",
        "required": [
          "name",
          "legalName",
          "description",
          "version",
          "downloads",
          "discovery",
          "boundaries"
        ],
        "properties": {
          "name": {
            "type": "string",
            "example": "Corhack"
          },
          "legalName": {
            "type": "string",
            "example": "Altamsun LTD"
          },
          "description": {
            "type": "string",
            "example": "Corhack is the men's health tracking app for testosterone, sleep, training, nutrition, and daily habits — all in one focused view."
          },
          "version": {
            "type": "string",
            "example": "1.0.0"
          },
          "downloads": {
            "type": "object",
            "required": [
              "appStore",
              "googlePlay"
            ],
            "properties": {
              "appStore": {
                "type": "string",
                "format": "uri",
                "example": "https://apps.apple.com/app/id6777719928"
              },
              "googlePlay": {
                "type": "string",
                "format": "uri",
                "example": "https://play.google.com/store/apps/details?id=com.altamsun.corhack"
              }
            }
          },
          "discovery": {
            "type": "object",
            "required": [
              "homepage",
              "sitemap",
              "agentGuide",
              "openApiJson",
              "openApiYaml",
              "developerPortal"
            ],
            "properties": {
              "homepage": {
                "type": "string",
                "format": "uri"
              },
              "sitemap": {
                "type": "string",
                "format": "uri"
              },
              "agentGuide": {
                "type": "string",
                "format": "uri"
              },
              "openApiJson": {
                "type": "string",
                "format": "uri"
              },
              "openApiYaml": {
                "type": "string",
                "format": "uri"
              },
              "developerPortal": {
                "type": "string",
                "format": "uri"
              },
              "about": {
                "type": "string",
                "format": "uri"
              },
              "contact": {
                "type": "string",
                "format": "uri"
              }
            }
          },
          "boundaries": {
            "type": "array",
            "items": {
              "type": "string"
            },
            "example": [
              "Personal daily tracking and wellness context, not medical diagnosis or treatment.",
              "Subscriptions and purchases are managed securely via Apple App Store or Google Play."
            ]
          }
        }
      },
      "HealthResponse": {
        "type": "object",
        "required": [
          "status",
          "version",
          "timestamp"
        ],
        "properties": {
          "status": {
            "type": "string",
            "example": "healthy"
          },
          "version": {
            "type": "string",
            "example": "1.0.0"
          },
          "timestamp": {
            "type": "string",
            "format": "date-time",
            "example": "2026-09-05T15:00:00Z"
          }
        }
      },
      "ProductsResponse": {
        "type": "object",
        "required": [
          "features",
          "membership"
        ],
        "properties": {
          "features": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "id",
                "name",
                "description"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "example": "signals"
                },
                "name": {
                  "type": "string",
                  "example": "Daily Signals"
                },
                "description": {
                  "type": "string"
                }
              }
            }
          },
          "membership": {
            "type": "object",
            "required": [
              "tiers",
              "platform"
            ],
            "properties": {
              "tiers": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "cadence",
                    "description"
                  ],
                  "properties": {
                    "cadence": {
                      "type": "string",
                      "example": "yearly"
                    },
                    "description": {
                      "type": "string"
                    }
                  }
                }
              },
              "platform": {
                "type": "string",
                "example": "In-App Purchase (Apple App Store / Google Play)"
              }
            }
          }
        }
      },
      "LibrarySummaryItem": {
        "type": "object",
        "required": [
          "slug",
          "title",
          "topic",
          "evidence",
          "readTime",
          "takeaway",
          "url"
        ],
        "properties": {
          "slug": {
            "type": "string",
            "example": "what-testosterone-does"
          },
          "title": {
            "type": "string",
            "example": "What does testosterone actually do?"
          },
          "topic": {
            "type": "string",
            "example": "Hormone Fundamentals"
          },
          "evidence": {
            "type": "string",
            "example": "Established"
          },
          "readTime": {
            "type": "string",
            "example": "7 min read"
          },
          "takeaway": {
            "type": "string"
          },
          "url": {
            "type": "string",
            "format": "uri"
          }
        }
      },
      "LibraryListResponse": {
        "type": "object",
        "required": [
          "total",
          "articles"
        ],
        "properties": {
          "total": {
            "type": "integer",
            "example": 9
          },
          "articles": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/LibrarySummaryItem"
            }
          }
        }
      },
      "SourceCitation": {
        "type": "object",
        "required": [
          "publisher",
          "title",
          "url"
        ],
        "properties": {
          "publisher": {
            "type": "string",
            "example": "Endocrine Society"
          },
          "title": {
            "type": "string",
            "example": "Hypogonadism in Men"
          },
          "url": {
            "type": "string",
            "format": "uri",
            "example": "https://www.endocrine.org"
          }
        }
      },
      "LibraryArticleDetail": {
        "type": "object",
        "required": [
          "slug",
          "title",
          "topic",
          "evidence",
          "dek",
          "takeaway",
          "limits",
          "readTime",
          "updated",
          "url",
          "sources",
          "related"
        ],
        "properties": {
          "slug": {
            "type": "string",
            "example": "what-testosterone-does"
          },
          "title": {
            "type": "string",
            "example": "What does testosterone actually do?"
          },
          "topic": {
            "type": "string",
            "example": "Hormone Fundamentals"
          },
          "evidence": {
            "type": "string",
            "example": "Established"
          },
          "dek": {
            "type": "string"
          },
          "takeaway": {
            "type": "string"
          },
          "limits": {
            "type": "string"
          },
          "readTime": {
            "type": "string",
            "example": "7 min read"
          },
          "updated": {
            "type": "string",
            "example": "Updated Aug 2026"
          },
          "url": {
            "type": "string",
            "format": "uri"
          },
          "sources": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SourceCitation"
            }
          },
          "related": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        }
      },
      "ErrorResponse": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "object",
            "required": [
              "status",
              "code",
              "message",
              "hint"
            ],
            "properties": {
              "status": {
                "type": "integer",
                "example": 404
              },
              "code": {
                "type": "string",
                "example": "API_NOT_FOUND"
              },
              "message": {
                "type": "string",
                "example": "The requested resource was not found."
              },
              "hint": {
                "type": "string",
                "example": "Read /openapi.json for supported public endpoints."
              }
            }
          }
        }
      }
    }
  }
}