---
title: "Inspect stub matching decision path"
method: POST
path: "/stubs/inspect"
tags: ["stubs"]
---

# Inspect stub matching decision path

`POST /stubs/inspect`

Returns detailed matching stages/candidates for a query without consuming stub times.

## Request body

- InspectRequest — A request to explain: the server reports every stub it considered and why each was kept or dropped.
  - `id` string, uuid — Stub identifier (UUID).
  - `service` string, required — Fully qualified gRPC service name.
  - `method` string, required — gRPC method name.
  - `session` string — Session to resolve against; empty means the global scope.
  - `headers` object — Request metadata, matched against stub `headers`.
  - `input` object[] — Request body, matched against stub `input`.

## Response `200`

Successful operation

- InspectReport — Why a request matched — or did not. Stages show how the candidate set narrowed.
  - `service` string, required — Service that was inspected.
  - `method` string, required — Method that was inspected.
  - `session` string, required — Session the request was resolved against.
  - `matchedStubId` string, required — UUID of the winning stub, absent when nothing matched.
  - `similarStubId` string, required — Closest non-matching stub, offered as a hint when nothing matched.
  - `fallbackToMethod` boolean, required — True when no stub matched the input and the search widened to any stub on the method.
  - `error` string, required — Why the request could not be resolved.
  - `stages` InspectStage[], required — How the candidate set narrowed, step by step.
    - `name` string, required — Filter applied at this step: service/method, session, times, headers, input, or the method fallback.
    - `before` integer, required — Candidates entering the step.
    - `after` integer, required — Candidates surviving the step.
    - `removed` integer, required — Candidates dropped by the step (`before` minus `after`).
  - `candidates` InspectCandidate[], required — Every stub considered, with its verdict.
    - `id` string, required — Stub UUID.
    - `service` string, required — Service the stub answers.
    - `method` string, required — Method the stub answers.
    - `session` string, required — Session the stub belongs to; empty means global.
    - `priority` integer, required — The stub `priority` value.
    - `times` integer, required — Effective match limit; `0` means unlimited.
    - `used` integer, required — How many times the stub has already matched in this session.
    - `specificity` integer, required — How narrowly the stub describes the request. Compared first when picking a winner.
    - `score` number, double, required — Match rank plus `priority × 10`. Breaks ties between equally specific stubs.
    - `visibleBySession` boolean, required — False when the stub belongs to a different session.
    - `withinTimes` boolean, required — False when the stub is exhausted by its `times` limit.
    - `headersMatched` boolean, required — Whether the stub `headers` matched the request metadata.
    - `inputMatched` boolean, required — Whether the stub `input` matched the request body.
    - `matched` boolean, required — True for the single stub that won.
    - `excludedBy` string[], required — Reasons this candidate was ruled out; empty when it survived.
    - `events` InspectCandidateEvent[], required — Per-stage verdicts for this candidate.
      - `stage` string, required — Stage the event belongs to.
      - `result` string, required — Whether the candidate passed the stage, was dropped, or was selected.
      - `reason` string — Why, when the candidate was dropped.

## Other responses

- `400` — Invalid inspect criteria
- `413` — Payload Too Large
- `422` — Validation error
- `500` — Internal Server Error

---

[API](https://skmtc.net/bavix/apis/gripmock-api-schema.md) · [All operations](https://skmtc.net/bavix/apis/gripmock-api-schema/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bavix/gripmock-api-schema/revisions/48019d318a0f/schema)