# HackPost Agent-Facing API and Discovery Guide

HackPost is a read-only hackathon discovery experience that exposes agent-friendly discovery resources alongside the browser app.

## Discovery resources
- API catalog: https://hackpost.io/.well-known/api-catalog
- OpenAPI description: https://hackpost.io/openapi/hackpost-agent-ready.openapi.json
- Agent skills index: https://hackpost.io/.well-known/agent-skills/index.json
- MCP server card: https://hackpost.io/.well-known/mcp/server-card.json
- Health: https://hackpost.io/healthz.json

## Markdown negotiation
- Requests to `/` and `/hackathons/{slug}` may return Markdown when the request includes `Accept: text/markdown`.
- Markdown responses use `Content-Type: text/markdown; charset=utf-8`.
- Markdown responses include `x-markdown-tokens` as a lightweight token estimate.

## Public routes
- `GET /`: Hackathon directory, available as HTML by default and Markdown for agents.
- `GET /ai-hackathons`: AI hackathon SEO landing page, available as HTML by default and Markdown for agents.
- `GET /online-ai-hackathons`: Online AI hackathon SEO landing page, available as HTML by default and Markdown for agents.
- `GET /hackathons-with-prizes`: Prize-backed AI hackathon SEO landing page, available as HTML by default and Markdown for agents.
- `GET /hackathons/{slug}`: Hackathon detail page, available as HTML by default and Markdown for agents.
- `GET /llms.txt`: Short machine-readable overview of the site.
- `GET /llms-full.txt`: Expanded machine-readable listing data.

## Authentication metadata
- OpenID configuration mirror: https://hackpost.io/.well-known/openid-configuration
- OAuth protected resource metadata: https://hackpost.io/.well-known/oauth-protected-resource
- Upstream issuer: https://securetoken.google.com/hackpost-app

## WebMCP
- When the browser exposes `navigator.modelContext.provideContext()`, HackPost registers tools for listing hackathons, reading a hackathon, opening a hackathon detail page, and reporting the current route context.