Skip to content

Search API

The Search API provides multiple search modes for finding rules and documents. All endpoints accept an optional project_id query parameter to scope results to a specific project.

Full-Text Search (BM25)

POST /api/v1/search/fulltext

Keyword matching on rule statements and rationale using Elasticsearch BM25 scoring.

Request Body:

{
  "query": "overtime monthly limit",
  "modality": "MUST",
  "severity": "HIGH",
  "scope": "hr/attendance",
  "tags": ["labor-law"],
  "page": 1,
  "page_size": 20
}

All filter fields (modality, severity, scope, tags) are optional.

Response:

{
  "items": [
    {
      "rule": {
        "id": "uuid",
        "statement": "Monthly overtime MUST NOT exceed 45 hours...",
        "modality": "MUST_NOT",
        "severity": "CRITICAL",
        "scope": ["hr/attendance/jp"],
        "tags": ["labor-law", "overtime"]
      },
      "score": 12.34
    }
  ],
  "total": 3,
  "page": 1,
  "page_size": 20,
  "query": "overtime monthly limit"
}

Semantic Search (Vector)

POST /api/v1/search/vector

Cosine similarity search using 768-dimensional embeddings generated by Gemini. Same request/response format as full-text search. Requires a running Gemini API connection for embedding generation.

Hybrid Search (BM25 + Vector)

POST /api/v1/search/hybrid

Combined BM25 and vector scoring for best-of-both-worlds results. Same request/response format. Falls back to BM25-only if Gemini is unavailable for embedding generation.

Category Search (Filter-Only)

POST /api/v1/search/category

Filter rules by metadata without a free-text query. Useful for browsing rules by modality, severity, scope, or tags.

Request Body:

{
  "modality": "MUST",
  "severity": "CRITICAL",
  "scope": "compliance",
  "tags": ["privacy"],
  "page": 1,
  "page_size": 20
}

All fields are optional. Returns all rules matching the provided filters.

Context Search (Fact-Based)

POST /api/v1/search/context

Given a set of facts about a situation, find applicable rules. Uses LLM-assisted matching to identify rules that apply to the described scenario.

Request Body:

{
  "facts": "Employee worked 50 hours overtime this month. Department is engineering. Location is Tokyo.",
  "scope": "hr/attendance/jp",
  "page": 1,
  "page_size": 20
}

POST /api/v1/search/temporal?as_of=2026-04-01T00:00:00Z

Find rules that were effective at a given point in time. Filters by effective_period dates and EFFECTIVE/APPROVED status.

Query Parameters:

Parameter Required Description
as_of Yes ISO 8601 timestamp -- return rules effective at this time
q No Optional text query to further filter results
page No Page number (default: 1)
page_size No Results per page (default: 20, max: 100)
project_id No Scope to a specific project 
POST /api/v1/search/citation?source=labor-standards-act

Find rules that reference a particular external source in their source_refs metadata.

Query Parameters:

Parameter Required Description
source Yes External source identifier to search for
page No Page number (default: 1)
page_size No Results per page (default: 20, max: 100)
project_id No Scope to a specific project 
POST /api/v1/search/subject

Find rules applicable to a specific subject profile (person, role, or entity).

Query Parameters:

Parameter Required Description
role No Subject's role (e.g., "manager", "contractor")
location No Subject's location (e.g., "jp", "us")
employment_type No Employment type (e.g., "full-time", "contract")
department No Department (e.g., "engineering", "sales")
page No Page number (default: 1)
page_size No Results per page (default: 20, max: 100)
project_id No Scope to a specific project

Matches rules whose scope patterns contain the provided field values.

POST /api/v1/search/conflict?rule_id=<uuid>

Find rules that have a CONFLICTS_WITH relationship with the given rule. Uses the Neo4j-backed relationship graph.

Query Parameters:

Parameter Required Description
rule_id Yes UUID of the rule to find conflicts for
project_id No Scope to a specific project

Full-Text Document Search

POST /api/v1/search/documents/fulltext

BM25 search over document filenames and content text stored in Elasticsearch.

POST /api/v1/search/documents/vector

Vector similarity search over document embeddings. Requires Gemini for embedding generation.

POST /api/v1/search/documents/hybrid

Combined BM25 + vector scoring for documents. Falls back to BM25-only if embeddings are unavailable.

Request Body (all three):

{
  "query": "expense policy",
  "page": 1,
  "page_size": 20
}

Response:

{
  "items": [
    {
      "document_id": "uuid",
      "filename": "expense_policy_2026.pdf",
      "mime_type": "application/pdf",
      "size_bytes": 245760,
      "uploaded_by": "admin",
      "uploaded_at": "2026-04-15T10:30:00Z",
      "snippet": "All expenses exceeding 10,000 JPY require ...",
      "score": 8.5
    }
  ],
  "total": 1,
  "page": 1,
  "page_size": 20,
  "query": "expense policy"
}

POST /api/v1/search/documents

Fallback search using PostgreSQL full-text search (tsvector) when Elasticsearch is unavailable. Includes relevance ranking and rule extraction count per document.

Rules by Source Document

POST /api/v1/search/by-source-document

Find all rules extracted from a specific source document.

Request Body:

{
  "document_id": "uuid-of-source-document",
  "page": 1,
  "page_size": 20
}

Returns the source document metadata and all rules whose source_refs reference that document.

See Also