Content Negotiation

Single-document endpoints support three response formats: JSON (structured metadata and body), raw Markdown (the original file with YAML frontmatter), and plaintext (body text with all Markdown formatting stripped). You can choose the format using either the Accept header or the format query parameter.

Response Formats

Using the Accept Header

Set the Accept header to the desired content type:

# JSON (default)
curl -H "Accept: application/json" \
  https://lexbuild.dev/api/usc/documents/t1/s1

# Markdown
curl -H "Accept: text/markdown" \
  https://lexbuild.dev/api/usc/documents/t1/s1

# Plaintext
curl -H "Accept: text/plain" \
  https://lexbuild.dev/api/usc/documents/t1/s1

Using the Format Query Parameter

Alternatively, use the format query parameter. This takes precedence over the Accept header if both are present.

# JSON
curl "https://lexbuild.dev/api/usc/documents/t1/s1?format=json"

# Markdown
curl "https://lexbuild.dev/api/usc/documents/t1/s1?format=markdown"

# Plaintext
curl "https://lexbuild.dev/api/usc/documents/t1/s1?format=text"

Format values: json, markdown, text

Priority

The format query parameter always takes precedence:

1. If ?format= is present, it determines the format.
2. Otherwise, the Accept header is checked.
3. If neither is specified, the default is JSON.

JSON Response

The JSON format returns a structured envelope with metadata separated from the body:

curl https://lexbuild.dev/api/usc/documents/t1/s1

{
  "data": {
    "id": "usc-t1-s1",
    "identifier": "/us/usc/t1/s1",
    "source": "usc",
    "metadata": {
      "identifier": "/us/usc/t1/s1",
      "source": "usc",
      "display_title": "1 U.S.C. SS 1 - Words denoting number, gender, and so forth",
      "title_number": 1,
      "title_name": "General Provisions",
      "section_number": "1",
      "section_name": "Words denoting number, gender, and so forth",
      "chapter_number": "1",
      "chapter_name": "Rules of Construction",
      "legal_status": "law",
      "positive_law": true,
      "status": "in_force",
      "currency": "2024-01-03",
      "last_updated": "2024-01-03",
      "source_credit": "Office of the Law Revision Counsel"
    },
    "body": "In determining the meaning of any Act of Congress, unless the context indicates otherwise--\n\n**(a)** words importing the singular include and apply to several persons, parties, or things;\n\n**(b)** words importing the plural include the singular;..."
  },
  "meta": {
    "api_version": "v1",
    "format_version": "1.0",
    "timestamp": "2026-04-04T12:00:00.000Z"
  }
}

The JSON format is the most versatile. It lets you use field selection to request only the fields you need.

Markdown Response

The Markdown format returns the raw file content exactly as it was generated by the LexBuild converter, including YAML frontmatter:

curl -H "Accept: text/markdown" \
  https://lexbuild.dev/api/usc/documents/t1/s1

---
identifier: /us/usc/t1/s1
source: usc
title_number: 1
title_name: General Provisions
section_number: "1"
section_name: Words denoting number, gender, and so forth
chapter_number: "1"
chapter_name: Rules of Construction
legal_status: law
positive_law: true
status: in_force
---

# SS 1. Words denoting number, gender, and so forth

In determining the meaning of any Act of Congress, unless the context indicates otherwise--

**(a)** words importing the singular include and apply to several persons, parties, or things;

**(b)** words importing the plural include the singular;

This format is ideal for:

• Ingesting into RAG pipelines that expect Markdown with frontmatter
• Storing documents locally in the same format the CLI produces
• Processing with Markdown parsers like remark or gray-matter

Plaintext Response

The plaintext format strips all Markdown formatting from the body text, returning clean prose:

curl "https://lexbuild.dev/api/usc/documents/t1/s1?format=text"

In determining the meaning of any Act of Congress, unless the context indicates otherwise--

(a) words importing the singular include and apply to several persons, parties, or things;

(b) words importing the plural include the singular;

Headings, bold/italic markers, link syntax, and other Markdown constructs are removed. The plaintext format does not include frontmatter metadata.

This format is useful for:

• Feeding content to language models that perform better on clean text
• Text analysis and NLP pipelines
• Displaying content where Markdown rendering is not available

Applicability

Content negotiation applies only to single-document endpoints:

Listing, search, hierarchy, and system endpoints always return JSON regardless of the Accept header or format parameter.