---
title: "The cross-reference corpus in aggregate"
method: GET
path: "/connections"
---

# The cross-reference corpus in aggregate

`GET /connections`

## Request

- Base URL: `https://vineverse.bible/api/v1`
- URL: `https://vineverse.bible/api/v1/connections`
- Auth: none required

Questions about the SHAPE of the cross-reference corpus rather than about one verse: which chapters are the hubs, which books lean on which, how much referencing crosses between the testaments.

With no argument, returns the totals plus the most-connected chapters and the strongest book-to-book pairs. Pass `book` for one book’s own incoming and outgoing rows, or `osis` for a single chapter’s rank and vote weight. Use /xrefs when you want the actual references for a passage.

Answers 503 when the aggregate has not been built — it is a build artefact, and a fresh checkout running `next dev` genuinely does not have it yet.

## Query parameters

- `book` string
- `osis` string
- `limit` integer
- `offset` integer

## Response `200`

Corpus totals, plus whichever slice was requested.

- Connections
  - `totals` object
    - `references` integer: Rows in the corpus that resolved to a chapter pair.
    - `distinctPairs` integer
    - `arcs` integer: Drawable arcs — pairs minus self-pairs.
    - `selfPairs` integer: A chapter referencing itself.
    - `crossTestament` integer
    - `chapters` integer
    - `generated` string, date-time
    - `source` string
  - `offset` integer: Applied to every ranked list below.
  - `topChaptersTotal` integer
  - `topChaptersCount` integer
  - `topChapters` object[]
  - `topBookPairsTotal` integer
  - `topBookPairsCount` integer
  - `topBookPairs` object[]
  - `book` object: Only when book= was given.
  - `referencesOutTotal` integer
  - `referencesOutCount` integer
  - `referencesOut` object[]: This book citing others, strongest first. Only when book= was given.
  - `referencesInTotal` integer
  - `referencesInCount` integer
  - `referencesIn` object[]
  - `chapter` object: Only when osis= was given.
  - `note` string
  - `licence` Licence: Carried on every response. The obligation is inherited by anyone who redistributes the data, not discharged by us. `document` is the licence of the specific document fetched, which is CC-BY-SA-4.0 for anything under sa/ and is the value to honour over the blanket statement.
    - `text` string
    - `data` string
    - `document` string: SPDX-style id for this document, e.g. "CC-BY-4.0".
    - `shareAlike` string
    - `reason` string
    - `attribution` string, uri

## Other responses

- `400`: The reference or parameter could not be parsed.
- `404`: No such document.
- `429`: Too many requests. Carries Retry-After. See the rate limit note in `info`.
- `503`: The build artefact this endpoint needs is not present on this deployment. Carries Retry-After, and code `dataset_unavailable`. GET /status lists which datasets exist.

---

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