---
title: "Subgraph"
method: POST
path: "/authorities/graph/subgraph"
tags: ["authorities"]
---

# Subgraph

`POST /authorities/graph/subgraph`

## Request

- Base URL: `https://api.casenode.ai`
- URL: `https://api.casenode.ai/authorities/graph/subgraph`
- Auth: none declared

Return the filtered match count, plus the graph itself when under the cap.

``total`` is always returned. When ``total > cap`` the response is
``{total, capped: true, courts}`` with no node/edge arrays (cheap — this
drives the client's "narrow your filters" guard). When ``total <= cap`` the
bounded node set and its induced `cites` edges are included.

``outcomes`` and ``appeals`` ride along here and deliberately **not** on
``/graph/export``. A verdict changes the moment a reviewer confirms it, and
``CorpusCacheControlMiddleware`` puts ``max-age=300,
stale-while-revalidate=86400`` on every successful GET under
``/authorities/`` — which covers ``/graph/export`` and does not cover this
POST. A verdict behind that cache would be stale for exactly the cases
someone had just reviewed, which is the same reason the outcome is attached
per search page rather than indexed into the Meilisearch document. The same
holds for ``appeals``: its status is derived from those verdicts, so it goes
stale on the same click.

## Request body

- SubgraphRequest: Filter criteria for a bounded citation subgraph. Mirrors the `/search` filter model (same `SearchFilter` / `FilterBlock` schemas) so the graph responds to the exact filters the search band builds.
  - `query` string
  - `filters` SearchFilter[]
    - `field` 'domain' | 'court' | 'respondent' | 'claimant' | 'cites' | 'mentions' | 'judge' | 'year_from' | 'year_to' | 'case_id' | 'disposition' | 'judgment_status' | 'appeal_from' | 'cited_by_min' | 'jurisdiction' | 'topic' | 'ids', required: Filter field — see FILTER_FIELD_HELP in the API schema for values.
    - `value` string: Single value. Omit when `values` is given.
    - `values` string[], nullable: Alternative spellings of ONE entity, OR'd together. Use for unconsolidated party/judge names. Omit for single-value filters; when given, `value` is ignored and set to the first entry. An exclude filter with several values excludes ALL of them.
    - `match` 'strict' | 'exclude'
    - `prec` 'exact' | 'fuzzy', nullable: Text precision for phrase fields (mentions/party/judge): 'exact' = the value must appear contiguously, 'fuzzy' = its significant words must all appear, in any order. Defaults to 'fuzzy' for party and judge names and 'exact' everywhere else.
  - `filter_blocks` FilterBlock[], nullable
    - `query` string
    - `filters` SearchFilter[]
      - `field` 'domain' | 'court' | 'respondent' | 'claimant' | 'cites' | 'mentions' | 'judge' | 'year_from' | 'year_to' | 'case_id' | 'disposition' | 'judgment_status' | 'appeal_from' | 'cited_by_min' | 'jurisdiction' | 'topic' | 'ids', required: Filter field — see FILTER_FIELD_HELP in the API schema for values.
      - `value` string: Single value. Omit when `values` is given.
      - `values` string[], nullable: Alternative spellings of ONE entity, OR'd together. Use for unconsolidated party/judge names. Omit for single-value filters; when given, `value` is ignored and set to the first entry. An exclude filter with several values excludes ALL of them.
      - `match` 'strict' | 'exclude'
      - `prec` 'exact' | 'fuzzy', nullable: Text precision for phrase fields (mentions/party/judge): 'exact' = the value must appear contiguously, 'fuzzy' = its significant words must all appear, in any order. Defaults to 'fuzzy' for party and judge names and 'exact' everywhere else.
  - `cap` integer

## Response `200`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/casenode/apis/casenode-api.md) · [All operations](https://skmtc.dev/casenode/apis/casenode-api/llms.txt) · [OpenAPI document](https://skmtc.dev/casenode/apis/casenode-api/revisions/5b2883d19661?raw)