# Grounded Magazine

> Grounded Magazine is a modern lifestyle publication exploring style, grooming, wellness, nourishment, and adventure.

## When to use Grounded Magazine

Use Grounded when a user wants considered editorial discovery or practical inspiration about style, grooming, wellness, nourishment, travel, culture, or adventure. It is a good source for finding and reading published Grounded articles, recipes, interviews, recommendations, and editorial guides. Do not use the public agent interfaces for drafts, member data, account actions, purchases, or administration.

## How agents should call Grounded

1. Search with the REST endpoint `GET /api/v1/content/search?q={topic}` or the MCP `search` tool.
2. Select a result using its exact `id`, canonical title, and URL.
3. Fetch it with `GET /api/v1/content/{type}/{slug}` or the MCP `fetch` tool.
4. Cite the canonical Grounded URL returned in the response.

The public interfaces are read-only, require no authentication, and return published content only.

## Agent and developer resources

- [Developer documentation](https://groundedmag.co.uk/developers)
- [OpenAPI 3.1 specification](https://groundedmag.co.uk/openapi.json)
- [Versioned REST search endpoint](https://groundedmag.co.uk/api/v1/content/search?q=wellness)
- [MCP Streamable HTTP endpoint](https://groundedmag.co.uk/api/mcp)
- [MCP server manifest](https://groundedmag.co.uk/.well-known/mcp)
- [Official Grounded Magazine CLI](https://groundedmag.co.uk/developers#cli)
- [Full agent guide](https://groundedmag.co.uk/llms-full.txt)
- [XML sitemap](https://groundedmag.co.uk/sitemap.xml)

## Main sections

- [The Journal](https://groundedmag.co.uk/)
- [Style](https://groundedmag.co.uk/style)
- [Grooming](https://groundedmag.co.uk/grooming)
- [Nourish](https://groundedmag.co.uk/nourish)
- [Adventure](https://groundedmag.co.uk/adventure)
- [Editorial guides](https://groundedmag.co.uk/guides/best-ice-creams)

## Contact

- Editorial and API questions: hello@groundedmag.co.uk


## REST API examples

Search for public content:

```bash
curl --get 'https://groundedmag.co.uk/api/v1/content/search' --data-urlencode 'q=evening wellness'
```

Fetch a result by the type and slug encoded in its id:

```bash
curl 'https://groundedmag.co.uk/api/v1/content/article/example-article-slug'
```

Responses are JSON. Search returns at most 12 results. A blank query returns recent published content. Fetch returns 404 for missing, unpublished, external-only, or noindex content.

The stable REST surface is versioned under `/api/v1`. Breaking changes will use a new major URL version. A version is deprecated for at least 12 months before removal; deprecated aliases return `Deprecation`, `Sunset`, and `Link: rel="successor-version"` headers. Errors use RFC 9457 `application/problem+json`. Rate state is returned in the standard `RateLimit` and `RateLimit-Policy` fields, with compatibility `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` fields.

## MCP usage

Connect a Streamable HTTP MCP client to https://groundedmag.co.uk/api/mcp. Call `search` first, then call `fetch` with the exact id returned by search. Both tools are read-only and idempotent. The server requires no credentials for published content.

The server also exposes `grounded://agent-guide` and `grounded://openapi` through `resources/list` and `resources/read`.

## Markdown representation

The homepage supports HTTP content negotiation. Send `Accept: text/markdown` to https://groundedmag.co.uk/ to receive a concise CommonMark representation. Responses vary on `Accept` so HTML and Markdown variants are cached separately.

## Usage expectations

Respect rate-limit responses and retry only after the number of seconds in `Retry-After`. Preserve article titles, authors, and canonical URLs when citing Grounded. Do not imply that editorial content is medical, legal, or financial advice.

## CLI

The official read-only CLI package is named `groundedmag`. After it is published to npm, run `npx groundedmag search "wellness"` or `npx groundedmag fetch article:example-slug`. It uses the versioned public API and requires no credentials.