Semantic Search

All endpoints on this page require the operations bearer token:

Authorization: Bearer $FL_API_TOKEN

They use two distinct stores. Hybrid and ontology search read FalkorDB. Embedding search reads the locally generated DuckDB embedding store and calls the configured embedding provider for the query vector.

Find functions by ontology

GET /api/skills/by-ontology

Resolve an ontology URI or a case-insensitive concept name, then return the Function exemplars mapped to it.

Parameter	Type	Required	Default	Notes
`concept`	string	Yes	—	An ontology URI such as `fibo:Account`, or a concept name such as `Account`.
`limit`	integer	No	`20`	Between `1` and `100`.

curl -H "Authorization: Bearer $FL_API_TOKEN" \
  "https://api.agentic.forwardlane.com/api/skills/by-ontology?concept=fibo:Account&limit=5"

{
  "concept": {"uri": "fibo:Account", "name": "Account"},
  "limit": 5,
  "count": 1,
  "items": [
    {
      "name": "open_account",
      "repo": "forwardlane-backend",
      "file_path": "services/account.py",
      "docstring": "Open a new account.",
      "domain": "services",
      "complexity": 4,
      "mapped_confidence": 0.95
    }
  ]
}

404 means the concept could not be resolved. 503 means FalkorDB is unavailable.

Hybrid code search

GET /api/search/hybrid

Search Function or Class nodes by full text (bm25), vector similarity (vector), or reciprocal-rank fusion (hybrid, the default). Function searches can be narrowed by enriched domain, ontology mapping, mapping confidence, and test coverage.

Parameter	Type	Required	Default	Notes
`q`	string	Yes	—	Search text.
`node_type`	`Function` or `Class`	No	`Function`	Function-only filters reject `Class` with `400`.
`mode`	`bm25`, `vector`, or `hybrid`	No	`hybrid`	`hybrid` combines the two rankings.
`top_k`	integer	No	`20`	Between `1` and `100`.
`repo`	string	No	—	Exact repository name.
`domain`	string	No	—	Canonical Function domain, for example `auth`, `services`, or `notifications`.
`ontology_concept_uri`	string	No	—	Require a `MAPPED_TO` edge to this concept.
`confidence_min`	number	No	—	Minimum mapping confidence, from `0` through `1`.
`has_tests`	boolean	No	—	`true` requires a linked test; `false` requires no linked test.

curl -H "Authorization: Bearer $FL_API_TOKEN" \
  "https://api.agentic.forwardlane.com/api/search/hybrid?q=account&mode=bm25&domain=services&ontology_concept_uri=fibo:Account&confidence_min=0.9&has_tests=true"

{
  "query": "account",
  "mode": "bm25",
  "node_type": "Function",
  "count": 1,
  "filters": {
    "domain": "services",
    "ontology_concept_uri": "fibo:Account",
    "confidence_min": 0.9,
    "has_tests": true
  },
  "results": [
    {
      "name": "open_account",
      "repo": "forwardlane-backend",
      "file_path": "services/account.py",
      "domain": "services",
      "score": 1.46,
      "ontology_matches": [
        {"uri": "fibo:Account", "name": "Account", "confidence": 0.92}
      ]
    }
  ]
}

For Function results, score is the source relevance score plus half of the highest matching ontology confidence. ontology_matches is always present, including as an empty array.

Search generated embeddings

GET /api/embeddings/search

This endpoint compares the embedded query with rows in function_embeddings, sorted by descending cosine similarity. It does not require FalkorDB.

The checked-in Railway image does not ship data/enrichment.duckdb, and no production data volume is currently configured. Use this endpoint locally, or mount a populated enrichment.duckdb into $DATA_DIR before enabling it in another environment. Without that database the endpoint returns 503.

Parameter	Type	Required	Default	Notes
`q`	string	Yes	—	Text to embed and search for.
`domain`	string	No	—	Exact stored Function domain. Unknown domains return an empty result set.
`top_k`	integer	No	`20`	Between `1` and `100`.
`model`	string	No	`text-embedding-3-small`	Limits the search to vectors from that model.

curl -H "Authorization: Bearer $FL_API_TOKEN" \
  "http://localhost:8000/api/embeddings/search?q=authenticate%20a%20user&domain=auth&top_k=3"

{
  "query": "authenticate a user",
  "domain": "auth",
  "model": "text-embedding-3-small",
  "top_k": 3,
  "count": 1,
  "results": [
    {
      "repo": "forwardlane-backend",
      "name": "login_user",
      "file_path": "auth.py",
      "domain": "auth",
      "model": "text-embedding-3-small",
      "similarity": 0.91
    }
  ]
}

503 means the local embedding database is unavailable. 500 means the query could not be embedded.

Get Started

Products

API Reference

CLI

FL Web

Python SDK

MCP Server

Graph Schema

Semantic Search

Semantic Search

Find functions by ontology

Hybrid code search

Search generated embeddings

​Semantic Search

​Find functions by ontology

​Hybrid code search

​Search generated embeddings

Semantic Search

Find functions by ontology

Hybrid code search

Search generated embeddings