Match
curl --request POST \
--url https://api.jeantechnologies.com/v1/match \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"user_id": "u_alice",
"domain": "dating",
"limit": 10,
"filters": {
"location_within_km": 50
},
"stages": {
"llm_judge": true,
"cross_encoder": {
"enabled": true,
"top_k": 25
}
},
"explain": false
}
'import requests
url = "https://api.jeantechnologies.com/v1/match"
payload = {
"user_id": "u_alice",
"domain": "dating",
"limit": 10,
"filters": { "location_within_km": 50 },
"stages": {
"llm_judge": True,
"cross_encoder": {
"enabled": True,
"top_k": 25
}
},
"explain": False
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
user_id: 'u_alice',
domain: 'dating',
limit: 10,
filters: {location_within_km: 50},
stages: {llm_judge: true, cross_encoder: {enabled: true, top_k: 25}},
explain: false
})
};
fetch('https://api.jeantechnologies.com/v1/match', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.jeantechnologies.com/v1/match",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'user_id' => 'u_alice',
'domain' => 'dating',
'limit' => 10,
'filters' => [
'location_within_km' => 50
],
'stages' => [
'llm_judge' => true,
'cross_encoder' => [
'enabled' => true,
'top_k' => 25
]
],
'explain' => false
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.jeantechnologies.com/v1/match"
payload := strings.NewReader("{\n \"user_id\": \"u_alice\",\n \"domain\": \"dating\",\n \"limit\": 10,\n \"filters\": {\n \"location_within_km\": 50\n },\n \"stages\": {\n \"llm_judge\": true,\n \"cross_encoder\": {\n \"enabled\": true,\n \"top_k\": 25\n }\n },\n \"explain\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.jeantechnologies.com/v1/match")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"user_id\": \"u_alice\",\n \"domain\": \"dating\",\n \"limit\": 10,\n \"filters\": {\n \"location_within_km\": 50\n },\n \"stages\": {\n \"llm_judge\": true,\n \"cross_encoder\": {\n \"enabled\": true,\n \"top_k\": 25\n }\n },\n \"explain\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.jeantechnologies.com/v1/match")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"user_id\": \"u_alice\",\n \"domain\": \"dating\",\n \"limit\": 10,\n \"filters\": {\n \"location_within_km\": 50\n },\n \"stages\": {\n \"llm_judge\": true,\n \"cross_encoder\": {\n \"enabled\": true,\n \"top_k\": 25\n }\n },\n \"explain\": false\n}"
response = http.request(request)
puts response.read_body{
"matches": [
{
"user_id": "c_456",
"score": 0.87,
"stage_scores": {
"light_ml": 0.71,
"embedding": 0.84,
"cross_encoder": 0.87
},
"reasons": [
"shared communication style",
"compatible relationship goals"
]
}
],
"pipeline_stats": {
"after_sql_filter": 12431,
"after_light_ml": 412,
"after_embedding": 53,
"after_cross_encoder": 10
},
"models_used": {
"embedding": {
"tier": "tenant",
"version": "u_acme.dating.2026-05-17"
},
"cross_encoder": {
"tier": "domain",
"version": "dating.cx.2026-05-01"
}
}
}{
"error": {
"code": "invalid_request",
"message": "Field 'domain' is required.",
"details": {}
}
}{
"error": {
"code": "invalid_request",
"message": "Field 'domain' is required.",
"details": {}
}
}Matching
Match
Run the matching pipeline for a user and return ranked compatible candidates.
POST
/
match
Match
curl --request POST \
--url https://api.jeantechnologies.com/v1/match \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"user_id": "u_alice",
"domain": "dating",
"limit": 10,
"filters": {
"location_within_km": 50
},
"stages": {
"llm_judge": true,
"cross_encoder": {
"enabled": true,
"top_k": 25
}
},
"explain": false
}
'import requests
url = "https://api.jeantechnologies.com/v1/match"
payload = {
"user_id": "u_alice",
"domain": "dating",
"limit": 10,
"filters": { "location_within_km": 50 },
"stages": {
"llm_judge": True,
"cross_encoder": {
"enabled": True,
"top_k": 25
}
},
"explain": False
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
user_id: 'u_alice',
domain: 'dating',
limit: 10,
filters: {location_within_km: 50},
stages: {llm_judge: true, cross_encoder: {enabled: true, top_k: 25}},
explain: false
})
};
fetch('https://api.jeantechnologies.com/v1/match', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.jeantechnologies.com/v1/match",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'user_id' => 'u_alice',
'domain' => 'dating',
'limit' => 10,
'filters' => [
'location_within_km' => 50
],
'stages' => [
'llm_judge' => true,
'cross_encoder' => [
'enabled' => true,
'top_k' => 25
]
],
'explain' => false
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.jeantechnologies.com/v1/match"
payload := strings.NewReader("{\n \"user_id\": \"u_alice\",\n \"domain\": \"dating\",\n \"limit\": 10,\n \"filters\": {\n \"location_within_km\": 50\n },\n \"stages\": {\n \"llm_judge\": true,\n \"cross_encoder\": {\n \"enabled\": true,\n \"top_k\": 25\n }\n },\n \"explain\": false\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://api.jeantechnologies.com/v1/match")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"user_id\": \"u_alice\",\n \"domain\": \"dating\",\n \"limit\": 10,\n \"filters\": {\n \"location_within_km\": 50\n },\n \"stages\": {\n \"llm_judge\": true,\n \"cross_encoder\": {\n \"enabled\": true,\n \"top_k\": 25\n }\n },\n \"explain\": false\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.jeantechnologies.com/v1/match")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"user_id\": \"u_alice\",\n \"domain\": \"dating\",\n \"limit\": 10,\n \"filters\": {\n \"location_within_km\": 50\n },\n \"stages\": {\n \"llm_judge\": true,\n \"cross_encoder\": {\n \"enabled\": true,\n \"top_k\": 25\n }\n },\n \"explain\": false\n}"
response = http.request(request)
puts response.read_body{
"matches": [
{
"user_id": "c_456",
"score": 0.87,
"stage_scores": {
"light_ml": 0.71,
"embedding": 0.84,
"cross_encoder": 0.87
},
"reasons": [
"shared communication style",
"compatible relationship goals"
]
}
],
"pipeline_stats": {
"after_sql_filter": 12431,
"after_light_ml": 412,
"after_embedding": 53,
"after_cross_encoder": 10
},
"models_used": {
"embedding": {
"tier": "tenant",
"version": "u_acme.dating.2026-05-17"
},
"cross_encoder": {
"tier": "domain",
"version": "dating.cx.2026-05-01"
}
}
}{
"error": {
"code": "invalid_request",
"message": "Field 'domain' is required.",
"details": {}
}
}{
"error": {
"code": "invalid_request",
"message": "Field 'domain' is required.",
"details": {}
}
}The value moment. Given a
Each stage hands a smaller candidate set to the next so the expensive stages only see candidates worth their time. You can toggle or tune any stage per request.
Set
user_id and a domain, the platform runs the pipeline against the most specific model available for your tenant (general → domain → tenant-tuned):
SQL filter → light ML rerank → domain embedding → cross-encoder → optional LLM judge
curl https://api.jeantechnologies.com/v1/match \
-H "Authorization: Bearer $JEAN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"user_id": "u_alice",
"domain": "dating",
"limit": 10,
"filters": { "location_within_km": 50 }
}'
matches = requests.post(
"https://api.jeantechnologies.com/v1/match",
headers={"Authorization": f"Bearer {os.environ['JEAN_API_KEY']}"},
json={
"user_id": "u_alice",
"domain": "dating",
"limit": 10,
"filters": {"location_within_km": 50},
},
).json()
const res = await fetch("https://api.jeantechnologies.com/v1/match", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.JEAN_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
user_id: "u_alice",
domain: "dating",
limit: 10,
filters: { location_within_km: 50 },
}),
});
const { matches } = await res.json();
Tuning the pipeline
Thestages object accepts a boolean shortcut or a per-stage config. Mix freely.
{
"user_id": "u_alice",
"domain": "dating",
"stages": {
"llm_judge": true,
"cross_encoder": { "enabled": true, "top_k": 25 },
"light_ml": { "min_score": 0.3 }
},
"explain": true
}
| Stage | Default | Per-candidate cost | When to tune |
|---|---|---|---|
sql_filter | on | microseconds | only off for debugging |
light_ml | on | milliseconds | raise min_score to be stricter |
embedding | on | sub-ms (ANN) | almost always on; required for quality |
cross_encoder | on | ~10ms | lower top_k for latency, raise for quality |
llm_judge | off | seconds | turn on when prompt-fit or free-text deal-breakers matter |
"explain": true to get per-candidate stage_scores and human-readable reasons in the response.
Example response
{
"matches": [
{
"user_id": "c_456",
"score": 0.87,
"stage_scores": {
"light_ml": 0.71,
"embedding": 0.84,
"cross_encoder": 0.87
},
"reasons": [
"shared communication style",
"compatible relationship goals"
]
}
],
"pipeline_stats": {
"after_sql_filter": 12431,
"after_light_ml": 412,
"after_embedding": 53,
"after_cross_encoder": 10
}
}
pipeline_stats lets you see, per request, how the candidate pool narrowed. Useful when tuning: if after_light_ml is too small, your min_score is too aggressive. If after_sql_filter is huge, your hard filters aren’t pulling their weight.
Latency budget: with
llm_judge off, p99 is typically under 200ms on a 10M-user index. Turning the judge on adds 1-3 seconds per request. Reserve it for the final-decision call, not exploratory queries.Authorizations
API key issued by Jean Technologies. Contact the team for access.
Body
application/json
Example:
"u_alice"
Example:
"dating"
Required range:
1 <= x <= 100Example:
10
Hard constraints applied before ranking.
Example:
{ "location_within_km": 50 }
Per-stage controls. Each stage can be toggled on or off, or passed a config object for finer control. Omit the whole object to accept sensible defaults for the domain.
Show child attributes
Show child attributes
Example:
{
"llm_judge": true,
"cross_encoder": { "enabled": true, "top_k": 25 }
}
If true, response includes per-stage stage_scores and human-readable reasons for each candidate.
Response
Ranked candidates
Show child attributes
Show child attributes
Show child attributes
Show child attributes
Which model tier and version served each stage. Log alongside outcomes to attribute lift to a specific deploy.
Show child attributes
Show child attributes
Example:
{
"embedding": {
"tier": "tenant",
"version": "u_acme.dating.2026-05-17"
},
"cross_encoder": {
"tier": "domain",
"version": "dating.cx.2026-05-01"
}
}
⌘I