---
title: "Resolve a free-text citation string to a canonical object"
method: GET
path: "/api/v1/resolve"
tags: ["objects"]
---

# Resolve a free-text citation string to a canonical object

`GET /api/v1/resolve`

## Request

- Base URL: `https://kvasir.legal`
- URL: `https://kvasir.legal/api/v1/resolve`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer
  - none

e.g. `§ 242 Abs. 1 BGB`, `Art. 6 Abs. 1 lit. f DSGVO`, `C-311/18`. Returns the object plus the pinpoint sub-unit when the citation names Absatz/Nummer/litera/Satz/Halbsatz, and did-you-mean suggestions when unresolved. Abbreviations are not globally unique: when the same one is used in several jurisdictions and the cited number exists in each (`Art. 141 BV` = Swiss referendum law AND the Bavarian right to roam), the response carries `ambiguous` with every candidate — pin the reading with `quellen`.

## Query parameters

- `cite` string, required
- `include` string
- `quellen` string
- `lang` 'de'

## Response `200`

Resolution result (check `exists`)

- object
  - `ambiguous` object: Present only on cross-jurisdiction collisions: {resolved, reason, candidates[], note}. The resolution is the first candidate by jurisdiction priority — do not present it as the only reading.
    - `candidates` object[]
    - `note` string
    - `reason` string
    - `resolved` string
  - `cite` string
  - `exists` boolean
  - `object` LegalObject
    - `authority` object
      - `indeg` integer
      - `pct` number
      - `score` number
    - `canonical_uri` string
    - `children` object[]: statute TOC (include=children)
      - `label` string
      - `section_path` string[]
      - `uri` string
    - `commentary` object[]: include=commentary: anchored, author-attributed annotations (never merged); with commentary_scope=inherit entries carry inherited=true + anchor_level
    - `content` object
    - `exists` boolean, required
    - `hint` string
    - `identity` object
      - `href` string, nullable
      - `path` union: concept hierarchy: array of {code,label}
        - object[]
        - string
      - `subtitle` string, nullable
      - `title` string
    - `include_ignored` string[]
    - `kind` 'norm' | 'decision' | 'gesetz' | 'aufsatz' | 'concept' | 'flow' | 'normversion' | 'material' | 'section' | 'unknown', required
    - `object_version` string, required
    - `provenance` Provenance: The verifiability kernel.
      - `derived` boolean
      - `quelle` string, nullable
      - `retrieved_at` string, date-time, nullable
      - `source` string
      - `source_url` string, nullable
      - `version` string, nullable: Content version (hash or update timestamp)
    - `relations` object
      - `in` object[]
      - `out` object[]
    - `suggestions` object[]: did-you-mean candidates when exists=false
    - `units` Unit[]
      - `citation` string
      - `deeplink` string
      - `label` string
      - `path` string: norm: a<abs>.n<nr>.b<buchst>; decision: r<Rn>
      - `text` string
      - `unit` string
    - `units_confidence` number: Fraction of extracted sub-units whose text verifies against the full text (1.0 = all clean). Only verified units are returned.
    - `uri` string, required
    - `versions` object[]
  - `parsed` object, nullable
  - `suggestions` object[]
  - `unit` Unit: Addressable, citable sub-unit.
    - `citation` string
    - `deeplink` string
    - `label` string
    - `path` string: norm: a<abs>.n<nr>.b<buchst>; decision: r<Rn>
    - `text` string
    - `unit` string
  - `uri` string

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key
- `429`: Rate limit (120/min default), monthly quota or sandbox cap reached — `code` distinguishes; honor Retry-After

---

[API](https://skmtc.dev/kvasir/apis/kvasir-legal-grounding-api.md) · [All operations](https://skmtc.dev/kvasir/apis/kvasir-legal-grounding-api/llms.txt) · [OpenAPI document](https://skmtc.dev/kvasir/apis/kvasir-legal-grounding-api/revisions/87f32370cf06?raw)