Skip to main content
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
}
'
{
  "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"
    }
  }
}
The value moment. Given a 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
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. 
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 }
  }'

​
Tuning the pipeline

The stages 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
}
StageDefaultPer-candidate costWhen to tune
sql_filteronmicrosecondsonly off for debugging
light_mlonmillisecondsraise min_score to be stricter
embeddingonsub-ms (ANN)almost always on; required for quality
cross_encoderon~10mslower top_k for latency, raise for quality
llm_judgeoffsecondsturn on when prompt-fit or free-text deal-breakers matter
Set "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

​
Authorization
string
header
required

API key issued by Jean Technologies. Contact the team for access.

Body

application/json
​
user_id
string
required
Example:

"u_alice"

​
domain
string
required
Example:

"dating"

​
limit
integer
default:10
Required range: 1 <= x <= 100
Example:

10

​
filters
object

Hard constraints applied before ranking.

Example:
{ "location_within_km": 50 }
​
stages
object

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.

Example:
{
  "llm_judge": true,
  "cross_encoder": { "enabled": true, "top_k": 25 }
}
​
explain
boolean
default:false

If true, response includes per-stage stage_scores and human-readable reasons for each candidate.

Response

Ranked candidates

​
matches
object[]
​
pipeline_stats
object
​
models_used
object

Which model tier and version served each stage. Log alongside outcomes to attribute lift to a specific deploy.

Example:
{
  "embedding": {
    "tier": "tenant",
    "version": "u_acme.dating.2026-05-17"
  },
  "cross_encoder": {
    "tier": "domain",
    "version": "dating.cx.2026-05-01"
  }
}