--- updatedAt: 2026-07-15T12:53:39.000Z agentTools: projectIndex: https://docs.cupid.travel/llms.txt --- # Score explicit supplier↔reference room pairs Scores an explicit list of **supplier ↔ reference** room-name pairs. Each pair gets a calibrated match score and binary label. Use when you already know which pairs to evaluate (QA, A/B tests, custom pipelines)—unlike Room Match many-to-many, which scores the full grid and ranks per supplier. ### Key Parameters - `threshold`: Decision cutoff on calibrated score. Default: `0.5` - `batchSize`: Informational batch hint on the request. Default: `64` - `lowercase`: Lowercase room text before scoring. Default: `true` - `includeLogitRaw`: Include `logitRaw` per result when `true`. Default: `false` - `pairs`: Array of pairs to score, each with id, supplierRoomName, and referenceRoomName ### Per-pair Result `scoreCalibrated`, `predictedLabel` (1 = match at threshold), `decisionThreshold`, optional `logitRaw`. To experiment with this API, use the sandbox key: ```e2R4t6Y8u0i3O5p7A9s1D3f5G7h9J2k4``` # OpenAPI definition ````json { "openapi": "3.0.0", "info": { "title": "Cupid Room Match API", "description": "The **Cupid Room Match API** maps supplier rooms to reference rooms using a multilingual cross-encoder. It provides two matching modes: many-to-many scoring for full supplier×reference grid mapping, and pairwise scoring for explicit supplier↔reference pairs.", "version": "3.0" }, "servers": [ { "url": "https://room-match.cupid.travel" } ], "security": [ { "apikeyAuth": [] } ], "paths": { "/room_match_pairwise": { "post": { "operationId": "roomMatchPairwise", "tags": [ "Room Match" ], "summary": "Score explicit supplier↔reference room pairs", "description": "Scores an explicit list of **supplier ↔ reference** room-name pairs. Each pair gets a calibrated match score and binary label. Use when you already know which pairs to evaluate (QA, A/B tests, custom pipelines)—unlike Room Match many-to-many, which scores the full grid and ranks per supplier.\n\n### Key Parameters\n\n- `threshold`: Decision cutoff on calibrated score. Default: `0.5`\n- `batchSize`: Informational batch hint on the request. Default: `64`\n- `lowercase`: Lowercase room text before scoring. Default: `true`\n- `includeLogitRaw`: Include `logitRaw` per result when `true`. Default: `false`\n- `pairs`: Array of pairs to score, each with id, supplierRoomName, and referenceRoomName\n\n### Per-pair Result\n\n`scoreCalibrated`, `predictedLabel` (1 = match at threshold), `decisionThreshold`, optional `logitRaw`.\n\nTo experiment with this API, use the sandbox key:\n```e2R4t6Y8u0i3O5p7A9s1D3f5G7h9J2k4```", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoomMatchPairwiseMapping" }, "examples": { "basic example": { "value": { "threshold": 0.5, "lowercase": true, "includeLogitRaw": false, "pairs": [ { "id": "pair-a", "supplierRoomName": "Deluxe King", "referenceRoomName": "King Room" }, { "id": "pair-b", "supplierRoomName": "STUDIO", "referenceRoomName": "Studio Apartment" }, { "id": "pair-c", "supplierRoomName": "Ocean View Suite", "referenceRoomName": "Suite Ocean View" } ] } }, "with raw logits": { "value": { "threshold": 0.6, "lowercase": true, "includeLogitRaw": true, "batchSize": 32, "pairs": [ { "id": "test-1", "supplierRoomName": "Standard Room One King Bed", "referenceRoomName": "King Standard Room" }, { "id": "test-2", "supplierRoomName": "Deluxe Twin City View", "referenceRoomName": "Twin Room" }, { "id": "test-3", "supplierRoomName": "Junior Suite Balcony", "referenceRoomName": "Suite Jr" } ] } }, "QA validation pairs": { "value": { "threshold": 0.5, "pairs": [ { "id": "qa-001", "supplierRoomName": "DBL Room", "referenceRoomName": "Double Room" }, { "id": "qa-002", "supplierRoomName": "SGL", "referenceRoomName": "Single Room" }, { "id": "qa-003", "supplierRoomName": "Family Room 2 Queen Beds", "referenceRoomName": "Family Suite" } ] } } } } } }, "responses": { "200": { "description": "OK", "headers": { "Server": { "schema": { "type": "string", "example": "nginx/1.18.0 (Ubuntu)" } }, "Date": { "schema": { "type": "string", "example": "Fri, 28 Jul 2023 08:46:27 GMT" } }, "Content-Type": { "schema": { "type": "string", "example": "application/json" } }, "Content-Length": { "schema": { "type": "integer", "example": "1614" } }, "Connection": { "schema": { "type": "string", "example": "keep-alive" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RoomMatchPairwiseResponse" }, "examples": { "Scored pairs": { "value": { "threshold": 0.5, "results": [ { "id": "pair-a", "supplierRoomName": "Deluxe King", "referenceRoomName": "King Room", "scoreCalibrated": 0.87, "predictedLabel": 1, "decisionThreshold": 0.5 }, { "id": "pair-b", "supplierRoomName": "STUDIO", "referenceRoomName": "Studio Apartment", "scoreCalibrated": 0.92, "predictedLabel": 1, "decisionThreshold": 0.5 }, { "id": "pair-c", "supplierRoomName": "Ocean View Suite", "referenceRoomName": "Suite Ocean View", "scoreCalibrated": 0.95, "predictedLabel": 1, "decisionThreshold": 0.5 } ], "model_version": "cross-encoder-v2.1" } }, "Mixed results with logits": { "value": { "threshold": 0.6, "results": [ { "id": "test-1", "supplierRoomName": "Standard Room One King Bed", "referenceRoomName": "King Standard Room", "scoreCalibrated": 0.89, "predictedLabel": 1, "decisionThreshold": 0.6, "logitRaw": 2.15 }, { "id": "test-2", "supplierRoomName": "Deluxe Twin City View", "referenceRoomName": "Twin Room", "scoreCalibrated": 0.72, "predictedLabel": 1, "decisionThreshold": 0.6, "logitRaw": 1.45 }, { "id": "test-3", "supplierRoomName": "Junior Suite Balcony", "referenceRoomName": "Suite Jr", "scoreCalibrated": 0.45, "predictedLabel": 0, "decisionThreshold": 0.6, "logitRaw": -0.35 } ], "model_version": "cross-encoder-v2.1" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } } } } }, "components": { "securitySchemes": { "apikeyAuth": { "name": "X-API-Key", "type": "apiKey", "in": "header" } }, "responses": { "BadRequest": { "description": "Bad Request", "headers": { "Date": { "schema": { "type": "string", "example": "Fri, 28 Jul 2023 08:46:27 GMT" } }, "Content-Type": { "schema": { "type": "string", "example": "application/json" } }, "Content-Length": { "schema": { "type": "integer", "example": 1614 } }, "Connection": { "schema": { "type": "string", "example": "keep-alive" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "examples": { "wrong parameters": { "value": { "error": "Invalid Request" } } } } } }, "Unauthorized": { "description": "Unauthorized", "headers": { "Server": { "schema": { "type": "string", "example": "nginx/1.18.0 (Ubuntu)" } }, "Date": { "schema": { "type": "string", "example": "Fri, 28 Jul 2023 08:46:27 GMT" } }, "Content-Type": { "schema": { "type": "string", "example": "application/json" } }, "Content-Length": { "schema": { "type": "integer", "example": 1614 } }, "Connection": { "schema": { "type": "string", "example": "keep-alive" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } } }, "examples": { "Wrong API key": { "value": { "error": "Invalid API key" } } } } } } }, "schemas": { "RoomMatchPairwiseMapping": { "type": "object", "required": [ "pairs" ], "properties": { "threshold": { "type": "number", "format": "float", "minimum": 0, "maximum": 1, "default": 0.5, "description": "Decision cutoff on calibrated score.", "example": 0.5 }, "batchSize": { "type": "integer", "minimum": 1, "default": 64, "description": "Informational batch hint on the request.", "example": 64 }, "lowercase": { "type": "boolean", "default": true, "description": "Lowercase room text before scoring.", "example": true }, "includeLogitRaw": { "type": "boolean", "default": false, "description": "Include logitRaw per result when true.", "example": false }, "pairs": { "type": "array", "minItems": 1, "description": "Pairs to score.", "items": { "$ref": "#/components/schemas/MatchPair" } } } }, "RoomMatchPairwiseResponse": { "type": "object", "properties": { "threshold": { "type": "number", "format": "float", "description": "The threshold used for decisions.", "example": 0.5 }, "results": { "type": "array", "description": "Per-pair match results.", "items": { "$ref": "#/components/schemas/PairResult" } }, "model_version": { "type": "string", "description": "Version of the model used for scoring.", "example": "cross-encoder-v2.1" } } }, "MatchPair": { "type": "object", "required": [ "id", "supplierRoomName", "referenceRoomName" ], "properties": { "id": { "type": "string", "description": "Client-supplied pair identifier.", "example": "pair-a" }, "supplierRoomName": { "type": "string", "description": "Supplier-side room title.", "example": "Deluxe King" }, "referenceRoomName": { "type": "string", "description": "Reference-side room title.", "example": "King Room" } } }, "PairResult": { "type": "object", "properties": { "id": { "type": "string", "description": "Client-supplied pair identifier.", "example": "pair-a" }, "supplierRoomName": { "type": "string", "description": "Supplier-side room title.", "example": "Deluxe King" }, "referenceRoomName": { "type": "string", "description": "Reference-side room title.", "example": "King Room" }, "scoreCalibrated": { "type": "number", "format": "float", "description": "Calibrated match score.", "example": 0.87 }, "predictedLabel": { "type": "integer", "enum": [ 0, 1 ], "description": "1 = match at threshold, 0 = no match.", "example": 1 }, "decisionThreshold": { "type": "number", "format": "float", "description": "The threshold used for this decision.", "example": 0.5 }, "logitRaw": { "type": "number", "format": "float", "description": "Raw model logit (only present when includeLogitRaw is true).", "example": 2.15 } } } } }, "x-readme": { "explorer-enabled": true, "proxy-enabled": true, "samples-enabled": true } } ````