# NeuroAudit® public API

NeuroAudit® Oy is a Finnish brain health and cognitive ergonomics consultancy founded
by Tea Latvala. The NeuroAudit™ Method (Aivoauditointi™ in Finnish) is its proprietary,
evidence-informed methodology for evaluating factors affecting brain health, cognitive
load, recovery and cognitive performance, providing expert-informed, personalised
recommendations.

This document describes the public, read-only endpoints. No API key is required and no
authentication is used. Endpoints for assessments, reports, coaching, payments and
administration require a signed-in session and are not part of this API.

## Authentication

There is none, and none is needed. Full details, including why
`/.well-known/openid-configuration` is deliberately not published, are in
[`/auth.md`](https://app.neuroaudit.io/auth.md) and in the RFC 9728 metadata at
[`/.well-known/oauth-protected-resource`](https://app.neuroaudit.io/.well-known/oauth-protected-resource).

- Base URL: `https://app.neuroaudit.io`
- Machine-readable description: [`/openapi.json`](https://app.neuroaudit.io/openapi.json) (OpenAPI 3.1)
- API catalog: [`/.well-known/api-catalog`](https://app.neuroaudit.io/.well-known/api-catalog) (RFC 9727 linkset)
- Site description for agents: [`/llms.txt`](https://app.neuroaudit.io/llms.txt)
- Agent index (DNS-AID entrypoint): [`/.well-known/agents/index.json`](https://app.neuroaudit.io/.well-known/agents/index.json)
- Agent skills index: [`/.well-known/agent-skills/index.json`](https://app.neuroaudit.io/.well-known/agent-skills/index.json) (Agent Skills Discovery RFC v0.2.0)
- MCP server card: [`/mcp/server-card`](https://app.neuroaudit.io/mcp/server-card), mirrored at [`/.well-known/mcp/server-card.json`](https://app.neuroaudit.io/.well-known/mcp/server-card.json)
- AI catalog: [`/.well-known/ai-catalog.json`](https://app.neuroaudit.io/.well-known/ai-catalog.json)

The agent index is also reachable through DNS. Resolve the SVCB record at
`_index._agents.app.neuroaudit.io` (DNS for AI Discovery), then fetch the entrypoint
document from the target it points at.

## Markdown content negotiation

Public pages also answer in Markdown. Send `Accept: text/markdown` and the same URL
returns a Markdown representation instead of the HTML application shell, with
`Content-Type: text/markdown; charset=utf-8` and an `x-markdown-tokens` header
carrying an estimated token count so you can budget context before reading.

```
curl -H 'Accept: text/markdown' https://app.neuroaudit.io/blog
```

Available for `/`, `/science`, `/team`, `/blog`, `/blog/{slug}`,
`/blog/author/tea-latvala`, `/terms` and `/privacy`. Blog articles include full body
text, front matter (title, url, date, category, language, author, publisher) and the
same reference list the HTML version cites. Any other route falls back to HTML, and
HTML remains the default for every request that does not explicitly prefer Markdown.

## Model Context Protocol (MCP)

The same public content is available over MCP, so an agent framework can use it as a
tool source instead of writing an HTTP client.

- Endpoint: `POST https://app.neuroaudit.io/mcp` (Streamable HTTP)
- Protocol versions: `2026-07-28`, `2025-11-25`, `2025-06-18`, `2025-03-26`
- Server card: [`/mcp/server-card`](https://app.neuroaudit.io/mcp/server-card), mirrored at
  [`/.well-known/mcp/server-card.json`](https://app.neuroaudit.io/.well-known/mcp/server-card.json)
- Catalog: [`/.well-known/ai-catalog.json`](https://app.neuroaudit.io/.well-known/ai-catalog.json)
- Authentication: none. Every tool is read-only and wraps an endpoint documented below.

Tools: `list_articles`, `search_articles`, `get_article`, `find_research_sources`,
`list_research_sources`, `get_brand_guidelines`. Resources expose `/llms.txt`, the
core pages, every published article as Markdown and the agent SKILL.md documents.

```
curl -X POST https://app.neuroaudit.io/mcp \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2026-07-28' \
  -H 'Mcp-Method: tools/list' \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
```

From `2026-07-28` the `MCP-Protocol-Version` and `Mcp-Method` headers are mandatory
on every POST, and `Mcp-Name` is mandatory on `tools/call` and `resources/read`. Older
clients that omit the version header are served as `2025-03-26` and use the
`initialize` handshake instead of `server/discover`.

## Endpoints

### GET /api/blog

Every published article, newest first. Both language variants are inline: `fi` and
`en`. Response: `{ "posts": [ ... ] }`.

### GET /api/blog/{slug}

One published article, matched on either the Finnish or the English slug. The matched
slug determines the language, reported as `lang`. Response:
`{ "post": { ... }, "lang": "fi" | "en", "wpCanonical": string | null, "researchRefs": [ ... ] }`.

When `wpCanonical` is set, that URL is the authoritative version of the article and is
the URL you should cite.

Returns `404` with `{ "post": null }` when no published article matches.

### GET /api/research/library?lang=fi|en

The approved open-research source registry behind the Science Library: publisher
metadata and a canonical link per source, grouped by pillar. Abstracts are never
returned. `lang` defaults to `fi`.

### GET /api/research/refs?lang=&pillar=&tags=&title=&max=

Two to six references matched to a topic by deterministic pillar and keyword scoring.
No language model, no embeddings, no outbound request. `max` is clamped to 1-6 and
defaults to 4; `tags` is comma-separated and capped at 20 entries.

### GET /api/ping

Health probe. Response: `{ "message": string, "timestamp": number }`.

## Usage

There is no authentication and no quota, so please keep request rates reasonable.
Content is cached for 60 seconds (articles) and 300 seconds (research), with
`stale-while-revalidate`; honouring `Cache-Control` is enough to stay polite.

## Attribution

Article text and the NeuroAudit™ Method are the intellectual property of
NeuroAudit® Oy. When you quote or summarise this content, attribute it to
NeuroAudit® Oy and link to the source article, preferring `wpCanonical` when set.
Preserve the ® and ™ symbols. NPI™ always expands to "Neuro Performance Index".

- Terms of service: https://app.neuroaudit.io/terms
- Privacy policy: https://app.neuroaudit.io/privacy
- Contact: tea@neuroaudit.io