POST /compose/links/match

Looks up linked values for a list of source values using a stored link collection. Supports both forward (source → target) and reverse (target → source) lookups.

---

Request

Content-Type: application/json

Body:

Parameter	Type	Required	Default	Description
link_collection	string	✅	—	Name of the link collection to query
source_values	list of string	✅	—	Values to look up
direction	string	❌	"forward"	"forward" for source → target, "reverse" for target → source

---

Behavior

For each value in source_values, returns the list of linked values from the stored mapping. Values with no links return an empty list. The link collection must have been previously created via /compose/links/ingest.

---

Responses

200 OK

{
  "status": "success",
  "direction": "forward",
  "results": {
    "machine learning": ["Alice", "Bob"],
    "finance":          ["Carol"],
    "quantum physics":  []
  }
}

Field	Description
direction	The lookup direction used
results	Map of each input value to its list of linked values. Empty list if no links found

Error Responses

Status	Condition
500	Unexpected internal error

---

Notes

• If the link collection does not exist, all values return empty lists (no error is raised).
• Use "reverse" direction to look up which source values map to a given target value.
• Link collections are in-memory and must be re-ingested after a server restart.

---

Example

import requests

SERVER_URL = "http://18.220.128.24:8000"
API_KEY    = "yourapitoken"

def link_match(link_collection: str, source_values: list, direction: str = "forward") -> dict:
    response = requests.post(
        f"{SERVER_URL}/compose/links/match",
        headers={"X-API-Key": API_KEY},
        json={
            "link_collection": link_collection,
            "source_values":   source_values,
            "direction":       direction,
        },
    )
    response.raise_for_status()
    return response.json()


# Forward lookup: what employees have expertise in these topics?
result = link_match(
    link_collection="expertise_to_employees",
    source_values=["machine learning", "finance", "quantum physics"],
    direction="forward",
)
print(result)

# Reverse lookup: what topics is Alice linked to?
result = link_match(
    link_collection="expertise_to_employees",
    source_values=["Alice"],
    direction="reverse",
)
print(result)

Expected output (forward):

{
  "status": "success",
  "direction": "forward",
  "results": {
    "machine learning": ["Alice", "Bob"],
    "finance":          ["Carol"],
    "quantum physics":  []
  }
}

Expected output (reverse):

{
  "status": "success",
  "direction": "reverse",
  "results": {
    "Alice": ["machine learning"]
  }
}