API Documentation

REST API for querying Vietnamese legal documents, articles, clauses, points, and their relationships.

Base URL

/api/v1

All endpoints return JSON. All requests use the GET method.

Canonical IDs follow the pattern: VN_LLD_2019_D35_K1_A where D = Điều (article), K = Khoản (clause), letter = Điểm (point).

Canonical ID Format

Every legal entity has a unique canonical ID that encodes its position in the document hierarchy.

Level	Pattern	Example
Document	`VN_{prefix}_{year}`	`VN_LLD_2019`
Article (Điều)	`...D{n}`	`VN_LLD_2019_D35`
Clause (Khoản)	`...K{n}`	`VN_LLD_2019_D35_K1`
Point (Điểm)	`...{LETTER}`	`VN_LLD_2019_D35_K1_A`

Relationship Types

Type	Vietnamese	Description
`amended_by`	Được sửa đổi bởi	Source was amended by target
`replaces`	Thay thế	Source replaces target
`related_to`	Liên quan đến	Bidirectional topical relationship
`references`	Tham chiếu	Source explicitly references target
`implements`	Hướng dẫn thi hành	Source implements/guides target

Error Responses

400Invalid or missing required parameters. Returns {"error": "message"}.

404Entity not found. Returns {"error": "Document not found"} or {"error": "Article not found"}.

GET/api/v1/documents

List documents

Returns all legal documents ordered by year descending. Each entry includes canonical ID, title, document number, type, issuing body, dates, slug, and status.

Example request

curl /api/v1/documents

Response

{
  "data": [
    {
      "canonicalId": "VN_LLD_2019",
      "title": "Bộ luật Lao động",
      "documentNumber": "45/2019/QH14",
      "documentType": "luat",
      "issuingBody": "Quốc hội",
      "issuedDate": "2019-11-20",
      "effectiveDate": "2021-01-01",
      "slug": "bo-luat-lao-dong",
      "year": 2019,
      "status": "active"
    }
  ]
}

GET/api/v1/documents?canonicalId={id}

Get single document

Returns a single document by its canonical ID, including its article list, metadata, relationships, and JSON-LD structured data.

Parameters

canonicalIdqueryrequiredCanonical ID of the document, e.g. "VN_LLD_2019"

Example request

curl /api/v1/documents?canonicalId=VN_LLD_2019

Response

{
  "data": {
    "canonicalId": "VN_LLD_2019",
    "title": "Bộ luật Lao động",
    "documentNumber": "45/2019/QH14",
    "documentType": "luat",
    "issuingBody": "Quốc hội",
    "issuedDate": "2019-11-20",
    "effectiveDate": "2021-01-01",
    "slug": "bo-luat-lao-dong",
    "year": 2019,
    "status": "active",
    "articles": [
      { "canonicalId": "VN_LLD_2019_D1", "articleNumber": 1, "title": "Phạm vi điều chỉnh" }
    ]
  },
  "canonical_id": "VN_LLD_2019",
  "canonical_url": "/doc/bo-luat-lao-dong/2019",
  "metadata": [
    { "key": "language", "value": "vi" }
  ],
  "relationships": [],
  "json_ld": { "@context": "https://schema.org", "@type": "Legislation", "..." : "..." }
}

GET/api/v1/articles/{canonicalId}

Get article

Returns a single article by canonical ID with its full clause/point hierarchy, parent document metadata, relationships, and JSON-LD.

Parameters

canonicalIdpathrequiredCanonical ID of the article, e.g. "VN_LLD_2019_D35"

Example request

curl /api/v1/articles/VN_LLD_2019_D35

Response

{
  "data": {
    "id": "uuid",
    "canonicalId": "VN_LLD_2019_D35",
    "articleNumber": 35,
    "title": "Quyền đơn phương chấm dứt hợp đồng lao động của người lao động",
    "content": "Full article text...",
    "chapter": "Chương III",
    "section": "Mục 4",
    "document": {
      "canonicalId": "VN_LLD_2019",
      "title": "Bộ luật Lao động",
      "documentNumber": "45/2019/QH14",
      "..."
    },
    "clauses": [
      {
        "canonicalId": "VN_LLD_2019_D35_K1",
        "clauseNumber": 1,
        "content": "Clause text...",
        "points": [
          {
            "canonicalId": "VN_LLD_2019_D35_K1_A",
            "pointLetter": "a",
            "content": "Point text..."
          }
        ]
      }
    ]
  },
  "canonical_id": "VN_LLD_2019_D35",
  "canonical_url": "/luat/bo-luat-lao-dong/2019/dieu-35",
  "metadata": [],
  "relationships": [],
  "json_ld": { "@context": "https://schema.org", "@type": "Legislation", "..." : "..." }
}

GET/api/v1/relationships/{canonicalId}

Get relationships

Returns all legal relationships where the given canonical ID appears as source or target. Useful for finding amendments, replacements, references, and implementing regulations.

Parameters

canonicalIdpathrequiredCanonical ID of any legal entity, e.g. "VN_LLD_2019_D35"

Example request

curl /api/v1/relationships/VN_LLD_2019_D35

Response

{
  "canonical_id": "VN_LLD_2019_D35",
  "relationships": [
    {
      "id": "uuid",
      "sourceType": "article",
      "sourceCanonicalId": "VN_BLDS_2015_D385",
      "targetType": "article",
      "targetCanonicalId": "VN_LLD_2019_D35",
      "relationshipType": "related_to",
      "description": "General contract principles apply to labor contracts",
      "effectiveDate": null
    }
  ]
}

GET/api/v1/search

Full-text search

Searches across articles, clauses, and points using case-insensitive matching. Returns matching entities with canonical URLs and parent document context. Query must be at least 2 characters.

Parameters

qqueryrequiredSearch query (min 2 characters). Supports Vietnamese diacritics.

typequeryFilter by entity type: "article", "clause", or "point". Omit to search all types.

Example request

curl /api/v1/search?q=lao+động

Response

{
  "query": "lao động",
  "total": 15,
  "results": [
    {
      "canonical_id": "VN_LLD_2019_D1",
      "entity_type": "article",
      "title": "Điều 1. Phạm vi điều chỉnh",
      "content": "First 200 characters of matching text...",
      "canonical_url": "/luat/bo-luat-lao-dong/2019/dieu-1",
      "document_title": "Bộ luật Lao động"
    }
  ]
}