/v1/extract/concepts

Unlike /v1/normalize, which matches a single phrase you already isolated, extract/concepts takes a whole clinical note. It detects candidate spans (NER), embeds each one with a multilingual sentence-transformer, and resolves it against SNOMED descriptions via pgvector cosine similarity. Each span gets a status derived from the top cosine score and the margin to the second candidate, so you can decide which results are safe to auto-accept versus which need review.

Request body

Response

{
  "concepts": [
    {
      "span": "fibrillation auriculaire",
      "candidates": [
        { "code": "49436004", "display": "Atrial fibrillation", "cosine": 0.91 },
        { "code": "40593004", "display": "Fibrillation", "cosine": 0.78 }
      ],
      "code": "49436004",
      "cosine": 0.91,
      "margin": 0.13,
      "concept_confidence": 0.91,
      "status": "resolved"
    }
  ]
}

Examples

curl -X POST https://api.obscyro.com/v1/extract/concepts \
  -H "Authorization: Bearer $OBS_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Patient suivi pour une fibrillation auriculaire sous anticoagulant.",
    "language": "fr"
  }'

Tips

• Treat resolved spans as safe to map automatically; route flag and unresolved spans to human review.
• Feed the returned spans and codes into /v1/extract/contexts to learn whether each concept is negated, historical, or about a family member.
• The service uses a multilingual embedding model, so French and English notes both work without a separate model.

Errors