---
title: "Semantic search over articles in force"
method: POST
path: "/api/v1/normativa/search"
tags: ["Legislation"]
---

# Semantic search over articles in force

`POST /api/v1/normativa/search`

## Request

- Base URL: `https://legal.nexusquantum.legal`
- URL: `https://legal.nexusquantum.legal/api/v1/normativa/search`
- Auth: HTTP bearer

Top-K vector search over articles in force on the requested date. Coverage varies by jurisdiction and is served from more than one store: Spain is indexed 100% (356k articles, voyage-3) in Postgres, while other jurisdictions — Singapore among them — are served from the vector store. Do NOT infer coverage from a jurisdiction code. When no articles are returned, `noteCode` tells you WHY, and the three cases are not interchangeable: `NO_MATCHES` (corpus searched, nothing matched the query), `CORPUS_NOT_INGESTED` (no corpus for this jurisdiction — retrying will not help), and `COVERAGE_UNKNOWN` (coverage could not be measured, e.g. the store did not answer — an empty result here is NOT evidence of absence and the call is worth retrying). A jurisdiction whose corpus is being served INCOMPLETE carries `corpusParcial` (the notice, in the language of the jurisdiction) and `corpusParcialCode` (a stable code to branch on) on EVERY response, empty or not — a partial list looks complete, so the warning cannot wait for an empty result. When such a response is also empty, `noteCode` carries that same code instead of `CORPUS_NOT_INGESTED`: the corpus was not never-ingested, part of it is parked. Today: `CO` → `CORPUS_PARCIAL_TEMPORAL`. Both fields are absent when the corpus is complete, so their presence is the signal. SCOPE: only legislation currently IN FORCE. Does not include earlier historical versions or repealed statutes.

## Request body

- object
  - `query` string, required
  - `jurisdiction` string: ISO code. REQUIRED (this field or its `jurisdiccion` alias) — no default (400 MISSING_JURISDICTION if both are missing, v1.28). Takes precedence over the alias if both are sent.
  - `jurisdiccion` string: Spanish-language alias for `jurisdiction`.
  - `date` string, date: English twin of `fecha`. Either works; neither is retired.
  - `fecha` string, date
  - `top_k` integer

## Response `200`

Top-K articles in force on the requested date, ordered by cosine similarity. Empty array + note if the jurisdiction is still on rails.

## Other responses

- `400`: MISSING_JURISDICTION (`jurisdiction`/`jurisdiccion` alias required — no default, v1.28) | VALIDATION_ERROR | INVALID_JSON
- `402`: INSUFFICIENT_CREDITS — paywall from minute one (balance > 0 required; the lookup does not consume credits).
- `403`: CONTENT_NOT_ENTITLED — the account does not have the legislation add-on (Layer 3) for the requested jurisdiction.
- `429`: RATE_LIMITED (RPM exceeded for the API key/organization) or CORPUS_DAILY_QUOTA (daily corpus volume quota exceeded — 500/day per user and per API key by default). The body includes `code`; `Retry-After` header in seconds.
- `502`: EMBED_FAILED / RPC_ERROR — transient failure of the Voyage embedder or the vector RPC. Retry.
- `503`: EMBEDDER_NOT_CONFIGURED — Voyage API key not configured on the server (a configuration issue, not normal operation).

---

[API](https://skmtc.dev/nexusquantum/apis/nexus-legal-api.md) · [All operations](https://skmtc.dev/nexusquantum/apis/nexus-legal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/nexusquantum/apis/nexus-legal-api/revisions/4084d8d4eb0b?raw)