---
title: "read_documentation"
description: "Generated reference for the management action read_documentation: its description, access metadata, payload contract, and registration status."
slug: /reference/actions/read-documentation
order: 73
visibility: public
redirects_from: []
---

# read\_documentation

Generated automatically from the [published contract sources](/cloud/reference/about/#contract-sources).

A script calls this action over HTTPS at `POST https://turnzero.ai/api/v1/read_documentation`, with a bearer credential and the action's payload as the JSON body. It also accepts `GET`. An MCP connection lists this action as the tool `read_documentation`.

OAuth access tokens and minted tokens, including the turnzero command's computer token, are bearer credentials. The action determines which kinds, scopes and grants it accepts ([Sign-in, sessions, and tokens](/cloud/concepts/sign-in-sessions-and-tokens/)).

**Build metadata:** Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured.

## Contract description

Read the platform's documentation\.

Reads cover tree indexes, pages and sections\. With `page`, `query` matches lines and `part: outline` lists headings\. Only trees your account holds are accessible\.

An action's longer reference is at `/cloud/reference/actions/<action-name>/`, with underscores changed to hyphens\.

Chunks continue with `next_offset` and the returned `stamp` until `next_offset` is null\. Hosts may cut batched long reads\.

## More about this action

Every account has `cloud` and `tzdocs`, an account with tzTeam access has `tzteam`, an account with tzmesh has `tzmesh`, and an account with tzTrack has `tztrack`\.

Pass `offset` to continue a read: use the previous answer's `next_offset`\. It counts Unicode code points in the complete text, 0 where none is given\. An offset inside a line, a code block, or the lines just under a section heading is read from the nearest earlier place where a chunk can begin\. The answer's `offset` gives that place\.

Pass `stamp` with any nonzero offset: copy the `stamp` member of the previous answer of this same read, unchanged\. It is 64 lowercase hexadecimal characters, the SHA\-256 of the text\. Send it beside that answer's `next_offset`; a first read sends no stamp\. Where the text has changed, the call is refused `context_changed`: restart at offset 0 without a stamp\. A stamp from another read is refused the same way\. A read of a `page` with `query` returns the page's own stamp, which you pass with any of the offsets it lists\.

Pass `tree` to choose the documentation tree to read\. Leave it out when `page` begins with a tree's base path, such as /cloud/, which identifies the tree\. Any other call without `tree` is refused `invalid_request`\. Requires a signed\-in connection whose account has the tree — cloud and tzdocs for every account, tzteam for tzTeam access, tzmesh for the tzmesh profile, tztrack for the tztrack profile — and a tree the served site version contains\.

Pass `part` to choose which text of the tree to read\. The default, `index`, gives one line per page with its title, address, and description\. With `outline`, each of those lines is followed by the page's headings with their anchors, for choosing a page by heading\. With `full`, you get every page of the tree in one text, without the generated reference, for a tool that reads the tree whole\.

Pass `page` to read one page by its route as the index prints it \(`/cloud/guides/add-a-database/`\), or by the same route without the base path and the trailing slash\. It returns the page's Markdown copy from the served version, in chunks within the page\. A page address from a completed answer is accepted as it is\. Without `tree`, the route must begin with a tree's base path, which identifies the tree\. A route the tree's manifest does not list is refused `context_not_found`\. You can narrow the read with `section`, `query`, or an `#anchor` on the route\. With `page`, `part` takes its default, `full` for the whole page, or `outline` for the page's headings, and those two only where you pass neither `section` nor `query`\.

Pass `section` with `page` to read one section of that page\. Give its anchor as the outline prints it, or its heading's plain text; where two headings share that text, you get the first in page order\. Letter case is ignored, and each run of spaces or punctuation reads as one hyphen\. The answer is the section alone, ending with its child headings' anchors where it has any\. An unknown value is refused `context_not_found`\. The refusal suggests `part` `outline` with that page and lists as many of the page's anchors as its size budget allows\. Anchors matching the most words of your value come first, with ties in page order\.

Pass `query` as a few words beside `page` for that page's lines that contain a query word, each with two lines of context and its code\-point offset, under the page's own `stamp`\. Without `page`, `query` is refused `invalid_request`: to search the documentation, call `search_documentation`\.

A word matches whole or by a four\-character prefix\. A stop word is dropped unless the query has nothing else\. The first 12 distinct words are searched and the rest are ignored\.

An empty query is read as left out\. The words of a query are recorded nowhere\.

The `limit` argument: 1 through 16000 code points, 8000 where none is given; a larger value reads 16000, and the answer's `note` says so\. A chunk read from `next_offset` under the same limit contains at most this many\.

## Access and action metadata

```json
{
  "name": "read_documentation",
  "resource": "platform_context",
  "tier": "observe",
  "surface": "account",
  "addresses": [
    "tzcloud",
    "tztools",
    "tzop"
  ],
  "admits": [
    "device_sign_in"
  ],
  "summary": "Read a documentation tree this connection's account holds, chosen by tree or by the base path of the page route: cloud and tzdocs for every account, tzteam for an account holding tzTeam access, tzmesh for an account holding tzmesh, and tztrack for an account holding tzTrack. It reads the tree's index by default. With page it reads one page by its route, with page and section one section of it, and with page and query that page's matching lines. With part outline it reads the index with every page's headings, or with page that page's alone, and with part full the whole text. Follow next_offset with its stamp for the complete text. For a long page, pass the section a search hit gives as section, or start at a section by the offset its first chunk's headings lists, with that chunk's stamp. To find a page by its words, call search_documentation.",
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": false,
    "idempotentHint": true
  }
}
```

## MCP catalog entry

```json
{
  "name": "read_documentation",
  "title": "Read documentation",
  "tier": "observe",
  "scenario": "CHI-L0-05",
  "summary": "Read the platform's documentation.\n\nReads cover tree indexes, pages and sections. With `page`, `query` matches lines and `part: outline` lists headings. Only trees your account holds are accessible.\n\nAn action's longer reference is at `/cloud/reference/actions/<action-name>/`, with underscores changed to hyphens.\n\nChunks continue with `next_offset` and the returned `stamp` until `next_offset` is null. Hosts may cut batched long reads.",
  "owners": [
    "CTX-07",
    "CTX-09",
    "ACB-L0-82",
    "PLD-L0-69",
    "CTX-05"
  ]
}
```

## request

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \[\]<br>Additional properties: false |
| /<wbr>properties/<wbr>offset | Code\-point offset in the whole text\. Continuation uses `next_offset`; nonzero needs `stamp`\.<br><br>Type: integer<br>Minimum: 0<br>Maximum: 9007199254740991 |
| /<wbr>properties/<wbr>stamp | Previous stamp of this same read, copied unchanged: 64 lower\-case hexadecimal characters\. Nonzero offset requires it, first reads omit it\. `context_changed` requires offset 0 without a stamp\. A stamp grants no access\.<br><br>Type: string<br>Pattern: ^\[a\-f0\-9\]\{64\}$ |
| /<wbr>properties/<wbr>limit | Chunk size in Unicode code points, at most 16000\. Larger values read 16000 with a `note`\.<br><br>Type: integer<br>Minimum: 1 |
| /<wbr>properties/<wbr>tree | An account\-held tree\. Optional only when `page` starts with its base path, otherwise required or `invalid_request`\.<br><br>Type: string<br>Allowed values: \["cloud","tzteam","tzdocs","tzmesh","tztrack","blueprint"\] |
| /<wbr>properties/<wbr>part | Default `index`: one line per page\. `outline`: page headings and anchors\. `full`: whole tree\. With `page`, outline gives its headings and full its text\. `section` and `query` permit only index\.<br><br>Type: string<br>Allowed values: \["index","full","outline"\]<br>Default: index |
| /<wbr>properties/<wbr>page | The page's path, as the index lists it\. Base path and trailing slash may be omitted with `tree`\. Without `tree`, the base path is required\. Unlisted routes give `context_not_found`\.<br><br>Type: string<br>Minimum length: 1<br>Maximum length: 160 |
| /<wbr>properties/<wbr>section | With `page`, an outline anchor or heading text, case\-insensitive\. Unknown gives `context_not_found`\. Excludes `query`, and permits only default `part`\.<br><br>Type: string<br>Minimum length: 1<br>Maximum length: 160 |
| /<wbr>properties/<wbr>query | Matches page lines containing a query word\. Needs `page`, else `invalid_request`; whole\-documentation search is `search_documentation`\. Only default `part`\.<br><br>Type: string<br>Maximum length: 200 |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["contract\_version","stamp","offset","total","next\_offset","id","mime\_type","text"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>contract\_version | Required value: 1 |
| /<wbr>properties/<wbr>stamp | Type: string<br>Pattern: ^\[a\-f0\-9\]\{64\}$ |
| /<wbr>properties/<wbr>offset | Where this chunk's text starts: the offset asked, or the nearest place before it where a chunk can begin, such as the start of the line or code block holding it\.<br><br>Type: integer<br>Minimum: 0<br>Maximum: 9007199254740991 |
| /<wbr>properties/<wbr>total | Type: integer<br>Minimum: 0<br>Maximum: 9007199254740991 |
| /<wbr>properties/<wbr>next\_offset | Type: \["integer","null"\]<br>Minimum: 0<br>Maximum: 9007199254740991 |
| /<wbr>properties/<wbr>id | Type: string |
| /<wbr>properties/<wbr>mime\_type | Type: string |
| /<wbr>properties/<wbr>note | Present where `limit` was past the most one read returns: a sentence saying this read used that most\. Absent on every other read\.<br><br>Type: string |
| /<wbr>properties/<wbr>continuation | Present where this answer holds part of the text\. Gives the characters read and total\. For more text, gives the next call with next\_offset as offset and the stamp value\. Otherwise says this is the last chunk\. On a `page` read's first chunk where more follows, it explains that a listed heading offset starts that section and whether `headings` is cut\. It points to `section` for one section and `query` for matching lines on the page\. A `section` or `query` read has no `headings` and points to the bare `page` read\. For a later chunk starting before the offset asked, it says so\. Absent where one answer holds the whole text\. Join the chunks' text in order for the whole text\.<br><br>Type: string |
| /<wbr>properties/<wbr>headings | Present on a bare `page` read's first chunk where more follows and the page has headings; absent on a `section` read, a `page` read with `query`, and a `page` read with `part` `outline`\. Each entry is a heading of depth 2 or deeper outside a code block, in order, with its text and the offset where its line starts\. A page with more than 40 lists those of depth 2 alone\. The list holds at most 200 entries, the first in the page's order, and a text longer than 200 code points is cut to 200; `continuation` says where either cuts it\. Call again with that offset and this answer's stamp to start at the section\.<br><br>Type: array<br>Maximum items: 200 |
| /<wbr>properties/<wbr>headings/<wbr>items | Type: object<br>Required fields: \["text","offset"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>headings/<wbr>items/<wbr>properties/<wbr>text | Type: string<br>Maximum length: 200 |
| /<wbr>properties/<wbr>headings/<wbr>items/<wbr>properties/<wbr>offset | Type: integer<br>Minimum: 0<br>Maximum: 9007199254740991 |
| /<wbr>properties/<wbr>moved\_to | Present where `page` was a route a page moved from: the route of the page this answer reads, where that page is now\. Use that route in your later calls\.<br><br>Type: string |
| /<wbr>properties/<wbr>text | Type: string |

## Complete payload contract

```json
{
  "request": {
    "type": "object",
    "properties": {
      "offset": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "description": "Code-point offset in the whole text. Continuation uses `next_offset`; nonzero needs `stamp`."
      },
      "stamp": {
        "type": "string",
        "pattern": "^[a-f0-9]{64}$",
        "description": "Previous stamp of this same read, copied unchanged: 64 lower-case hexadecimal characters. Nonzero offset requires it, first reads omit it. `context_changed` requires offset 0 without a stamp. A stamp grants no access."
      },
      "limit": {
        "type": "integer",
        "minimum": 1,
        "description": "Chunk size in Unicode code points, at most 16000. Larger values read 16000 with a `note`."
      },
      "tree": {
        "type": "string",
        "enum": [
          "cloud",
          "tzteam",
          "tzdocs",
          "tzmesh",
          "tztrack",
          "blueprint"
        ],
        "description": "An account-held tree. Optional only when `page` starts with its base path, otherwise required or `invalid_request`."
      },
      "part": {
        "type": "string",
        "enum": [
          "index",
          "full",
          "outline"
        ],
        "default": "index",
        "description": "Default `index`: one line per page. `outline`: page headings and anchors. `full`: whole tree. With `page`, outline gives its headings and full its text. `section` and `query` permit only index."
      },
      "page": {
        "type": "string",
        "minLength": 1,
        "maxLength": 160,
        "description": "The page's path, as the index lists it. Base path and trailing slash may be omitted with `tree`. Without `tree`, the base path is required. Unlisted routes give `context_not_found`."
      },
      "section": {
        "type": "string",
        "minLength": 1,
        "maxLength": 160,
        "description": "With `page`, an outline anchor or heading text, case-insensitive. Unknown gives `context_not_found`. Excludes `query`, and permits only default `part`."
      },
      "query": {
        "type": "string",
        "maxLength": 200,
        "description": "Matches page lines containing a query word. Needs `page`, else `invalid_request`; whole-documentation search is `search_documentation`. Only default `part`."
      }
    },
    "required": [],
    "additionalProperties": false
  },
  "response": {
    "type": "object",
    "properties": {
      "contract_version": {
        "const": 1
      },
      "stamp": {
        "type": "string",
        "pattern": "^[a-f0-9]{64}$"
      },
      "offset": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991,
        "description": "Where this chunk's text starts: the offset asked, or the nearest place before it where a chunk can begin, such as the start of the line or code block holding it."
      },
      "total": {
        "type": "integer",
        "minimum": 0,
        "maximum": 9007199254740991
      },
      "next_offset": {
        "type": [
          "integer",
          "null"
        ],
        "minimum": 0,
        "maximum": 9007199254740991
      },
      "id": {
        "type": "string"
      },
      "mime_type": {
        "type": "string"
      },
      "note": {
        "type": "string",
        "description": "Present where `limit` was past the most one read returns: a sentence saying this read used that most. Absent on every other read."
      },
      "continuation": {
        "type": "string",
        "description": "Present where this answer holds part of the text. Gives the characters read and total. For more text, gives the next call with next_offset as offset and the stamp value. Otherwise says this is the last chunk. On a `page` read's first chunk where more follows, it explains that a listed heading offset starts that section and whether `headings` is cut. It points to `section` for one section and `query` for matching lines on the page. A `section` or `query` read has no `headings` and points to the bare `page` read. For a later chunk starting before the offset asked, it says so. Absent where one answer holds the whole text. Join the chunks' text in order for the whole text."
      },
      "headings": {
        "type": "array",
        "maxItems": 200,
        "items": {
          "type": "object",
          "properties": {
            "text": {
              "type": "string",
              "maxLength": 200
            },
            "offset": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            }
          },
          "required": [
            "text",
            "offset"
          ],
          "additionalProperties": false
        },
        "description": "Present on a bare `page` read's first chunk where more follows and the page has headings; absent on a `section` read, a `page` read with `query`, and a `page` read with `part` `outline`. Each entry is a heading of depth 2 or deeper outside a code block, in order, with its text and the offset where its line starts. A page with more than 40 lists those of depth 2 alone. The list holds at most 200 entries, the first in the page's order, and a text longer than 200 code points is cut to 200; `continuation` says where either cuts it. Call again with that offset and this answer's stamp to start at the section."
      },
      "moved_to": {
        "type": "string",
        "description": "Present where `page` was a route a page moved from: the route of the page this answer reads, where that page is now. Use that route in your later calls."
      },
      "text": {
        "type": "string"
      }
    },
    "required": [
      "contract_version",
      "stamp",
      "offset",
      "total",
      "next_offset",
      "id",
      "mime_type",
      "text"
    ],
    "additionalProperties": false
  }
}
```

## Shared contracts

- [Refusals](/cloud/reference/refusals/): every refusal, by surface, with its cause and its remedy
- [schemas/wire\_error\.schema\.json](/cloud/reference/sources/schemas/wire-error-schema/)
- [schemas/wire\_errors\.json](/cloud/reference/sources/schemas/wire-errors/)
- [schemas/action\_payloads\.json](/cloud/reference/sources/schemas/action-payloads/) (includes shared shapes)
- [management\_api\_contract\.md](/cloud/reference/sources/management-api-contract/)
