---
title: How agents use these docs
description: Read any page as Markdown, find pages through llms.txt, search the docs over HTTP, and connect an agent to UserReason.
url: https://docs.userreason.com/agents/
updated: 2026-10-10
---

# How agents use these docs

These docs have one source. A coding agent can read it as Markdown, find pages through `llms.txt` and search it over HTTP. Every route returns the same text as the website.

## Choose a route

| Route | Use it when | Needs |
| - | - | - |
| Markdown page | The agent has web access and already knows which page it needs. | Nothing |
| `llms.txt` | The agent needs to find out which pages exist. | Nothing |
| Search | The agent has a question and needs the section that answers it. | Nothing |
| Agent skill | The agent should know when in-app feedback is worth proposing and how to set it up. | The skill in your project |
| CLI or MCP connector | The agent should create, publish or read things in UserReason. | A grant a person approves |

## Fetch a page as Markdown

Add `index.md` to any page address, or ask for Markdown with a request header. Both return the same file.

```sh
curl https://docs.userreason.com/sdk/events/index.md
curl -H "Accept: text/markdown" https://docs.userreason.com/sdk/events/
```

Each Markdown page opens with its title, the package and version it describes, and its address. The response also carries an `x-markdown-tokens` header with the approximate size of the page in tokens.

## Index files

- [`/llms.txt`](https://docs.userreason.com/llms.txt) lists every page with its address and one line about it.
- [`/llms-full.txt`](https://docs.userreason.com/llms-full.txt) holds the full text of the docs in one file.

## Search the docs

Search returns the matching sections, best first. Each result has a passage, the package and version it applies to, and a link to the exact section.

```sh
curl "https://docs.userreason.com/search?q=report+an+event&limit=1"
```

```json title="Result"
{
  "query": "report an event",
  "results": [
    {
      "title": "Quickstart",
      "heading": "4. Report an event",
      "url": "https://docs.userreason.com/get-started/quickstart/#4-report-an-event",
      "markdown_url": "https://docs.userreason.com/get-started/quickstart/index.md",
      "package": "@userreason/js",
      "version": "0.4",
      "passage": "Report what happened after your app confirms it succeeded. You report the fact once. The prompt's settings decide the audience, the sampling and the timing. await UserReason.event('onboarding.completed'); See Events for properties, verified…"
    }
  ]
}
```

`limit` is optional. It defaults to 5 and can be at most 20.

## Install the skill

The installation wizard offers to add the UserReason skill to your project, in `.agents/skills/userreason/`. Pass `--agent-skill` to accept the offer without being asked.

```sh
npx -y @userreason/wizard@latest --agent-skill
```

The skill tells the agent to read these docs instead of relying on what it remembers.

## Connect over MCP

Add the UserReason server to your MCP client. It offers the same scoped management commands as the CLI.

```text title="MCP server address"
https://api.userreason.com/mcp
```

Your MCP client opens a browser window to sign in.

## What needs approval

> **For agents: Reading is open. Changes need a person.**
>
> An agent can read these docs and propose a prompt without signing in. Creating a site, saving a draft, publishing and reading responses each need a grant that a person approves in the dashboard.