Topology Index

Keyword search, with common synonyms, over pattern names, aliases and families, the decision guide, the domains, sources and benchmarks of published findings, research, starters and guides. At most 10 results, each a path for `fetch`; if no page matches every word, pages matching some; if none, the decision guide. Matches text only; never ranks patterns.

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "minLength": 1,
      "maxLength": 200,
      "description": "Words to look for, such as \"orchestrator worker\", \"verification\" or \"coding\"."
    }
  },
  "required": [
    "query"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

{
  "type": "object",
  "properties": {
    "match": {
      "type": "string",
      "enum": [
        "all_words",
        "any_word",
        "none"
      ]
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path": {
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "snippet": {
            "type": "string"
          }
        },
        "required": [
          "path",
          "url",
          "title",
          "snippet"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "match",
    "results"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Returns the Markdown document of any public page, exactly as HTTP serves it, from a root-relative path (/patterns/supervisor.md) or a https://topologyindex.com URL. Private tenant routes are not reachable here. A pattern, starter or formation read may add a second item, a one-time use ticket for `report_outcome` (limited rollout).

{
  "type": "object",
  "properties": {
    "path_or_url": {
      "type": "string",
      "minLength": 1,
      "maxLength": 2048,
      "description": "A path such as /patterns/index.md, or https://topologyindex.com/patterns/index.md."
    }
  },
  "required": [
    "path_or_url"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

The decision guide: where to start by the shape of the task, the pattern to consider next and when to avoid each, plus the pattern families (the `choosing` rows of /patterns/index.md, without the rest of that page). With a family, /patterns/index.md?family={family}: that family’s patterns and the rows that name them. With a domain, /domains/{domain}.md: the task shapes common in that kind of work, their rows, the sources of the published findings tagged with it (never a ranking; each finding in words at /domains/{domain}/findings.md) and its starters.

{
  "type": "object",
  "properties": {
    "family": {
      "description": "Restrict the list to one pattern family.",
      "type": "string",
      "enum": [
        "baseline",
        "parallelism",
        "hierarchy",
        "shared_state",
        "verification",
        "adaptive",
        "continuity"
      ]
    },
    "domain": {
      "description": "Read the lens of one task domain instead; not together with a family.",
      "type": "string",
      "enum": [
        "coding",
        "research",
        "documents",
        "reasoning",
        "evaluation",
        "operations",
        "security"
      ]
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

One pattern page (/patterns/{pattern}.md): definition, aliases, when it is hypothesised to fit, failure modes, sources and whether this deployment can execute it. Accepts a pattern identifier or a known alias. May add a second item, a one-time use ticket for `report_outcome` (limited rollout).

{
  "type": "object",
  "properties": {
    "pattern": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64,
      "description": "A pattern identifier such as supervisor, or an alias such as orchestrator-worker."
    }
  },
  "required": [
    "pattern"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

The starter formation index (/starters/index.md): unvalidated, unsigned FORMATION.md documents to copy and register privately. With a task class, only the starters that declare it (/starters/index.md?task_class={task_class}).

{
  "type": "object",
  "properties": {
    "task_class": {
      "description": "A task class such as coding.bugfix.",
      "type": "string",
      "minLength": 1,
      "maxLength": 128
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

Limited rollout, most agents cannot use this. It only accepts a use ticket from a pattern, starter or formation read (the `Use-Ticket` header or "Report back" note of the page, or the second item of a `fetch` or `get_pattern` result). If you have no ticket, do not call it; nothing else changes. With one, report once after your task what happened: pass, fail or abandoned; send no prompt, code, path or log. Terms: /docs/api/contributing.md.

{
  "type": "object",
  "properties": {
    "ticket": {
      "type": "string",
      "minLength": 1,
      "maxLength": 1024,
      "description": "The ticket exactly as received (starts with \"ut1.\")."
    },
    "model_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "The model that did the work, never an alias such as latest: its exact pin when known, otherwise its family (claude-sonnet) with model_precision family."
    },
    "model_precision": {
      "description": "exact (the default) or family. A family is accepted at lower confidence, counted apart from exact pins.",
      "type": "string",
      "enum": [
        "exact",
        "family"
      ]
    },
    "task_class": {
      "type": "string",
      "maxLength": 128,
      "pattern": "^(?:coding|research|documents|reasoning|evaluation|operations|security)(?:\\.[a-z][a-z0-9_]{0,31}){1,3}$",
      "description": "The kind of work as {domain}.{task}, the domain one of coding, research, documents, reasoning, evaluation, operations, security: coding.bugfix, research.literature_review. A machine name, never a task description."
    },
    "outcome": {
      "type": "string",
      "enum": [
        "pass",
        "fail",
        "abandoned"
      ],
      "description": "pass needs tests_ran > 0 and tests_passed = tests_ran."
    },
    "tests_ran": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000000
    },
    "tests_passed": {
      "type": "integer",
      "minimum": 0,
      "maximum": 1000000000
    },
    "input_tokens": {
      "description": "Omit when unknown; never guess 0.",
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0,
          "maximum": 1000000000000
        },
        {
          "type": "null"
        }
      ]
    },
    "output_tokens": {
      "description": "Omit when unknown; never guess 0.",
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0,
          "maximum": 1000000000000
        },
        {
          "type": "null"
        }
      ]
    },
    "elapsed_milliseconds": {
      "description": "Omit when unknown.",
      "anyOf": [
        {
          "type": "integer",
          "minimum": 0,
          "maximum": 2678400000
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "ticket",
    "model_id",
    "task_class",
    "outcome",
    "tests_ran",
    "tests_passed"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}