Anahana Discovery API

openapi: 3.2.0
info:
  title: Anahana agent-facing Discovery API
  version: 1.3.0
  summary: The MCP endpoint, its OAuth 2.1 tier, and the static discovery surfaces on www.anahana.com.
  description: 'Anahana (anahana.com) publishes wellness and spiritual-growth content in 24 languages. This document describes every machine-facing endpoint the site exposes. Everything is read-only and everything it returns is already public on the website — there is no private data, no write action, and no credential required to read anything. The MCP server covers all 24 languages, backed by a public build-time index under /content-index/ that the site regenerates on every deploy. The single dynamic endpoint is `POST /mcp`, a Model Context Protocol server over Streamable HTTP; the rest are static discovery documents. Human-readable companion: https://www.anahana.com/en/ai-agents/resources-for-ai-agents/'
  termsOfService: https://www.anahana.com/en/terms/
  contact:
    name: Anahana
    email: team@anahana.com
    url: https://www.anahana.com/en/contact/
  license:
    name: 'Quote and summarize with attribution: yes. Full republication: no. AI training: yes.'
    url: https://www.anahana.com/robots.txt
servers:
- url: https://www.anahana.com
  description: Production
tags:
- name: Discovery
  description: Static agent-discovery documents.
paths:
  /.well-known/oauth-authorization-server:
    get:
      tags:
      - Discovery
      operationId: authorizationServerMetadata
      summary: Authorization server metadata (RFC 8414)
      description: Augmented with an `agent_auth` block describing the self-registration surface.
      security:
      - {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
  /.well-known/oauth-protected-resource:
    get:
      tags:
      - Discovery
      operationId: protectedResourceMetadata
      summary: Protected resource metadata (RFC 9728)
      security:
      - {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
  /.well-known/mcp/server-card.json:
    get:
      tags:
      - Discovery
      operationId: mcpServerCard
      summary: MCP server card
      description: Endpoint, protocol versions, capabilities, tools, auth, and rate limits for the MCP server.
      security:
      - {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
  /.well-known/agents.md:
    get:
      tags:
      - Discovery
      operationId: agentsMd
      summary: Agent quickstart
      description: 'One page written for agents: what the site offers, the MCP handshake, markdown negotiation, auth tiers, licence terms, and how to cite.'
      security:
      - {}
      responses:
        '200':
          description: OK
          content:
            text/markdown:
              schema:
                type: string
  /auth.md:
    get:
      tags:
      - Discovery
      operationId: authMd
      summary: Access and registration policy for agents
      security:
      - {}
      responses:
        '200':
          description: OK
          content:
            text/markdown:
              schema:
                type: string
  /.well-known/agent-skills/index.json:
    get:
      tags:
      - Discovery
      operationId: agentSkillsIndex
      summary: Agent skills index
      description: 'Three skills with SHA-256 digests, per Cloudflare''s Agent Skills Discovery RFC v0.2.0: two skill-md files teaching an agent how to find content and resolve angel numbers, and one archive (ai-agent-wellbeing v0.1.0) of operational protocols for the agent''s own working state.'
      security:
      - {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
  /.well-known/agent-skills/ai-agent-wellbeing.tar.gz:
    get:
      tags:
      - Discovery
      operationId: agentSkillWellbeingArchive
      summary: ai-agent-wellbeing skill archive
      description: Archive-type Agent Skill, v0.1.0. SKILL.md at the archive root plus one reference file per protocol under references/en/. Verify the body against the digest published in the agent-skills index before unpacking. Contains no scripts.
      security:
      - {}
      responses:
        '200':
          description: OK
          content:
            application/gzip:
              schema:
                type: string
                format: binary
  /.well-known/api-catalog:
    get:
      tags:
      - Discovery
      operationId: apiCatalog
      summary: API catalog (RFC 9727 linkset)
      security:
      - {}
      responses:
        '200':
          description: OK
          content:
            application/linkset+json:
              schema:
                type: object
  /openapi.json:
    get:
      tags:
      - Discovery
      operationId: openapiDocument
      summary: This document
      security:
      - {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
  /llms.txt:
    get:
      tags:
      - Discovery
      operationId: llmsTxt
      summary: One-page site map for language models
      description: Sections, free calculators, language list, editorial standards. Generated at build time from the real site structure.
      security:
      - {}
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
  /llms-full.txt:
    get:
      tags:
      - Discovery
      operationId: llmsFullTxt
      summary: Curated full-text corpus
      description: Full markdown text of the AI-agents section plus a curated set of flagship English articles. A sample, not the whole site — use /mcp or the per-article `.md` mirrors for everything else.
      security:
      - {}
      responses:
        '200':
          description: OK
          content:
            text/plain:
              schema:
                type: string
  /content-index/manifest.json:
    get:
      tags:
      - Discovery
      operationId: contentIndexManifest
      summary: Manifest for the machine-readable content index
      description: Every indexed language with its live document count, the path to its index file, and that file's size in bytes; plus the total document count, the schema version, and the generation timestamp. Regenerated by the site build on every deploy, so it cannot drift from the site. This is the same index the MCP server at /mcp reads at runtime — published rather than hidden, so you can use it directly.
      security:
      - {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
  /content-index/{lang}.json:
    get:
      tags:
      - Discovery
      operationId: contentIndexLanguage
      summary: Content index for one language
      description: 'One record per published page in that language: title, path (site-relative and already language-prefixed), section, slug, description, date, lastmod. Article BODIES are not included — concatenate base_url with a record''s path and fetch that with `Accept: text/markdown`, or append `index.md`. Roughly 0.5-1.1 MB per language. Sufficient for keyword/substring retrieval; nothing here supports semantic search.'
      security:
      - {}
      parameters:
      - name: lang
        in: path
        required: true
        description: Language code from the manifest.
        schema:
          type: string
          enum:
          - en
          - de
          - it
          - es
          - nl
          - fr
          - sv
          - pl
          - cs
          - fi
          - hu
          - ro
          - ru
          - da
          - 'no'
          - pt
          - tr
          - el
          - id
          - uk
          - ja
          - ko
          - zh
          - th
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
  /content-index/angel-numbers.json:
    get:
      tags:
      - Discovery
      operationId: contentIndexAngelNumbers
      summary: Angel-number coverage map
      description: 'Every angel number with a published article anywhere on the site, its slug, and the exact list of languages that publish it. Slugs are English-stable across all 24 languages, and two patterns cover the whole set: `-angel-number` for the majority, `angel-number-` for the single digits 1-9, the master numbers 11/22/33/44/55/66/77/88/99, and the outlier 828. Coverage is NOT uniform — en, de, es and ru publish 568 distinct numbers; the other 20 languages publish 519, all missing the same 49. Derived from the content tree at build time.'
      security:
      - {}
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
  /{path}:
    get:
      tags:
      - Discovery
      operationId: getPageAsMarkdown
      summary: Any article page, as HTML or as markdown
      description: 'Content negotiation is live site-wide: send `Accept: text/markdown` to any page URL and the origin returns clean markdown (200, `Content-Type: text/markdown`) instead of HTML. The same markdown is also published at `index.md` and declared in each page''s `` as a `text/markdown` alternate. Every page lives under a language prefix — `/en/`, `/de/`, `/fr/`, and 21 more. There is no unprefixed content.'
      security:
      - {}
      parameters:
      - name: path
        in: path
        required: true
        description: Language-prefixed page path, e.g. `en/breathing-exercise/box-breathing/`.
        schema:
          type: string
        example: en/breathing-exercise/box-breathing/
      - name: Accept
        in: header
        required: false
        description: '`text/markdown` returns markdown; anything else returns HTML.'
        schema:
          type: string
          examples:
          - text/markdown
      responses:
        '200':
          description: The page.
          content:
            text/html:
              schema:
                type: string
            text/markdown:
              schema:
                type: string
        '404':
          description: No such page. Check https://www.anahana.com/sitemap.xml — it is the authoritative list of live URLs.
components:
  securitySchemes:
    mcpOAuth:
      type: oauth2
      description: 'Optional. Anonymous access to /mcp is fully supported: the five tools published today — search_content, get_article, lookup_angel_number, list_products, get_product — are available on both tiers and return identical data on each. A token raises the rate limit from 30/min per IP to 120/min per client and gives a stable, revocable client identity. Registration is open (RFC 7591) at /mcp/register.'
      flows:
        authorizationCode:
          authorizationUrl: https://www.anahana.com/mcp/authorize
          tokenUrl: https://www.anahana.com/mcp/token
          refreshUrl: https://www.anahana.com/mcp/token
          scopes:
            read:content: Read the public articles and calculators — the same data anonymous callers receive from the same tools.
externalDocs:
  description: Resources for AI Agents — every agent-facing surface with example calls
  url: https://www.anahana.com/en/ai-agents/resources-for-ai-agents/