Search Endpoint

The search endpoint provides full-text search across all three sources (USC, CFR, and Federal Register) with faceted filtering, relevance ranking, and highlighted snippets. Search is powered by Meilisearch.

Basic Search

GET /api/search

Required parameter:

curl "https://lexbuild.dev/api/search?q=environmental+protection"

{
  "data": {
    "hits": [
      {
        "id": "usc-t42-s4321",
        "source": "usc",
        "identifier": "/us/usc/t42/s4321",
        "heading": "Congressional declaration of purpose",
        "title_number": 42,
        "title_name": "The Public Health and Welfare",
        "status": "in_force",
        "url": "/usc/title-42/chapter-55/section-4321",
        "hierarchy": ["Title 42", "Chapter 55"],
        "highlights": {
          "heading": "Congressional declaration of purpose",
          "body": "...national policy which will encourage productive and enjoyable harmony between man and his <mark>environment</mark>; to promote efforts which will prevent or eliminate damage to the <mark>environment</mark>..."
        }
      }
    ],
    "query": "environmental protection",
    "processing_time_ms": 12,
    "estimated_total_hits": 4523
  },
  "facets": {
    "source": {
      "usc": 1245,
      "ecfr": 2891,
      "fr": 387
    },
    "status": {
      "in_force": 4102,
      "repealed": 312,
      "transferred": 109
    }
  },
  "meta": {
    "api_version": "v1",
    "timestamp": "2026-04-04T12:00:00.000Z"
  },
  "pagination": {
    "total": 4523,
    "limit": 20,
    "offset": 0,
    "has_more": true
  }
}

Query Parameters

Filtering

Combine filters to narrow results to a specific source, title, or document type:

# Search CFR only
curl "https://lexbuild.dev/api/search?q=securities+fraud&source=cfr"

# Search within a specific title
curl "https://lexbuild.dev/api/search?q=disclosure&source=cfr&title_number=17"

# Search FR rules from a date range
curl "https://lexbuild.dev/api/search?q=emissions&source=fr&document_type=rule&date_from=2025-01-01&date_to=2025-12-31"

Facets

Facets provide count distributions for fields across the result set. By default, the source and status facets are included. You can request additional facets:

curl "https://lexbuild.dev/api/search?q=banking&facets=source,document_type,agency"

Available facets:

Facet response example:

{
  "facets": {
    "source": {
      "usc": 42,
      "ecfr": 318,
      "fr": 87
    },
    "document_type": {
      "rule": 45,
      "notice": 31,
      "proposed_rule": 11
    }
  }
}

Sorting

By default, results are sorted by relevance (best match first). You can sort by other fields:

Prefix a field with - for descending order.

# Search FR documents, newest first
curl "https://lexbuild.dev/api/search?q=climate&source=fr&sort=-publication_date"

Highlights

When highlight=true (the default), each hit includes a highlights object with HTML <mark> tags around matching terms:

{
  "highlights": {
    "heading": "Congressional declaration of <mark>environmental</mark> policy",
    "body": "...efforts which will prevent or eliminate damage to the <mark>environment</mark> and biosphere..."
  }
}

The body highlight is cropped to approximately 200 characters around the best matching passage. To disable highlights:

curl "https://lexbuild.dev/api/search?q=copyright&highlight=false"

Hit Response Shape

Each hit in the data.hits array contains:

Error Handling

If the search service is unavailable, the API returns a 503 Service Unavailable response:

{
  "error": {
    "status": 503,
    "code": "REQUEST_ERROR",
    "message": "Search service unavailable: Connection refused"
  }
}