search_documentation #

Generated automatically from the published contract sources.

A script calls this action over HTTPS at POST https://turnzero.ai/api/v1/actions/search_documentation, with a bearer credential and the action's payload as the JSON body. It also accepts GET. Without a credential it answers the signed-out search of the documentation open to everyone, the one action that does; a GET takes the members as query parameters.

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 #

Search documentation you can read for the words in query. hits holds the best matching sections first, each with tree, title, route, heading, anchor, excerpt, and score; text holds them as Markdown lines. Read one with read_documentation, route as page, anchor as section.

More about this action #

Pass query as a few words, at most 200 characters. A section is a hit where its heading or text holds a query word; the page title only helps order the hits. A word matches whole or by a four-character prefix, and a plural word also matches its singular. A stop word is dropped unless the query has nothing else. The first 12 distinct words are searched and the rest are ignored.

Pass tree to search one tree your account can read: cloud and tzdocs for every account, tzteam for tzTeam access, tzmesh for the tzmesh profile, and tztrack for the tztrack profile. Leave it out to search every tree your account can read; each hit carries its tree. A tree you cannot read is refused invalid_request, and the refusal lists the trees you can.

Pass limit for the most hits, 1 to 20. You get 8 where you give none, and at most 3 from one page. Where nothing matches, hits is empty, and so is text but for a query that is one rule code, which still returns the line saying what a rule code is.

The website's search box runs this same search, over the documentation open to everyone. A script or a page can call it with no sign-in at its address on the actions route, by GET with the members as query parameters; signed out, it searches that documentation alone and also takes q in place of query. The words of a query are recorded nowhere.

Access and action metadata #

{
  "name": "search_documentation",
  "resource": "platform_context",
  "tier": "observe",
  "summary": "Search the documentation for a few words and get the best matching sections, best first: each hit's tree, page title, route, section heading and anchor, excerpt, and score, and the same hits as Markdown lines. With a credential it searches every tree the account holds, or the one given as tree. With no credential, on the wire at its own address by GET or POST, it searches the documentation open to everyone, as the website's search box does.",
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": false,
    "idempotentHint": true
  }
}

MCP catalog entry #

{
  "name": "search_documentation",
  "title": "Search documentation",
  "tier": "observe",
  "scenario": "CHI-L0-05",
  "summary": "Search documentation you can read for the words in `query`. `hits` holds the best matching sections first, each with `tree`, `title`, `route`, `heading`, `anchor`, `excerpt`, and `score`; `text` holds them as Markdown lines. Read one with `read_documentation`, `route` as `page`, `anchor` as `section`.",
  "owners": [
    "CTX-10",
    "CTX-09",
    "ACB-L0-82",
    "API-L0-15"
  ]
}

request #

JSON pointer	Description and constraints
"" (root)	Type: object Required fields: ["query"] Additional properties: false
/properties/query	A few words to search for, at most 200 characters. Type: string Maximum length: 200
/properties/tree	One tree to search; leave it out to search every tree you may read. Type: string Allowed values: ["cloud","tzteam","tzdocs","tzmesh","tztrack"]
/properties/limit	The most hits, 1 to 20; 8 where absent. Type: integer Minimum: 1 Maximum: 20

response #

JSON pointer	Description and constraints
"" (root)	Type: object Required fields: ["contract_version","query","trees","hits","text"] Additional properties: false
/properties/contract_version	Required value: 1
/properties/query	The query as sent. Type: string
/properties/trees	The trees searched, in the order cloud, tzteam, tzdocs, tzmesh, then tztrack. Type: array
/properties/trees/items	Allowed values: ["cloud","tzteam","tzdocs","tzmesh","tztrack"]
/properties/hits	The hits, best first. Type: array Maximum items: 20
/properties/hits/items	Type: object Required fields: ["tree","title","route","heading","anchor","excerpt","score"] Additional properties: false
/properties/hits/items/properties/tree	Type: string
/properties/hits/items/properties/title	The page's title. Type: string
/properties/hits/items/properties/route	The page's route, which read_documentation takes as `page`. Type: string
/properties/hits/items/properties/heading	The section's heading, read plain; null for the text before a page's first section heading. Type: ["string","null"]
/properties/hits/items/properties/anchor	The section's anchor, which read_documentation takes as `section`; null where the section has none. Type: ["string","null"]
/properties/hits/items/properties/excerpt	The section's line holding the most query words. Type: string Maximum length: 200
/properties/hits/items/properties/score	The ranking score, rounded to four decimal places; higher is better. Type: number
/properties/text	The same hits as Markdown lines, one per hit in the same order, each `- [title › heading](route#anchor): excerpt`; where the query is one rule code, a first line says what a rule code is. Empty where nothing matches. Type: string

Complete payload contract #

{
  "request": {
    "type": "object",
    "properties": {
      "query": {
        "type": "string",
        "maxLength": 200,
        "description": "A few words to search for, at most 200 characters."
      },
      "tree": {
        "type": "string",
        "enum": [
          "cloud",
          "tzteam",
          "tzdocs",
          "tzmesh",
          "tztrack"
        ],
        "description": "One tree to search; leave it out to search every tree you may read."
      },
      "limit": {
        "type": "integer",
        "minimum": 1,
        "maximum": 20,
        "description": "The most hits, 1 to 20; 8 where absent."
      }
    },
    "required": [
      "query"
    ],
    "additionalProperties": false
  },
  "response": {
    "type": "object",
    "properties": {
      "contract_version": {
        "const": 1
      },
      "query": {
        "type": "string",
        "description": "The query as sent."
      },
      "trees": {
        "type": "array",
        "items": {
          "enum": [
            "cloud",
            "tzteam",
            "tzdocs",
            "tzmesh",
            "tztrack"
          ]
        },
        "description": "The trees searched, in the order cloud, tzteam, tzdocs, tzmesh, then tztrack."
      },
      "hits": {
        "type": "array",
        "maxItems": 20,
        "items": {
          "type": "object",
          "properties": {
            "tree": {
              "type": "string"
            },
            "title": {
              "type": "string",
              "description": "The page's title."
            },
            "route": {
              "type": "string",
              "description": "The page's route, which read_documentation takes as `page`."
            },
            "heading": {
              "type": [
                "string",
                "null"
              ],
              "description": "The section's heading, read plain; null for the text before a page's first section heading."
            },
            "anchor": {
              "type": [
                "string",
                "null"
              ],
              "description": "The section's anchor, which read_documentation takes as `section`; null where the section has none."
            },
            "excerpt": {
              "type": "string",
              "maxLength": 200,
              "description": "The section's line holding the most query words."
            },
            "score": {
              "type": "number",
              "description": "The ranking score, rounded to four decimal places; higher is better."
            }
          },
          "required": [
            "tree",
            "title",
            "route",
            "heading",
            "anchor",
            "excerpt",
            "score"
          ],
          "additionalProperties": false
        },
        "description": "The hits, best first."
      },
      "text": {
        "type": "string",
        "description": "The same hits as Markdown lines, one per hit in the same order, each `- [title › heading](route#anchor): excerpt`; where the query is one rule code, a first line says what a rule code is. Empty where nothing matches."
      }
    },
    "required": [
      "contract_version",
      "query",
      "trees",
      "hits",
      "text"
    ],
    "additionalProperties": false
  }
}

Shared contracts #

Refusals: every refusal, by surface, with its cause and its remedy
schemas/wire_error.schema.json
schemas/wire_errors.json
schemas/action_payloads.json (includes shared shapes)
management_api_contract.md