> ## Documentation Index
> Fetch the complete documentation index at: https://ekacare-mintlify-efa94f7d.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Link Entities (Batch)

> Links up to 5 free-text entities in a single call. All queries in a batch share the same `ontology`, `version`, `top_k` and `metadata`. The response contains one result block per query, in request order.

## About this endpoint

`POST /med-link/nel/link/batch` links up to **5** free-text entities in a single
call. Every query in the batch shares the same `ontology`, `version`, `top_k`
and `metadata`.

The response `results[]` array contains one block per query, in request order —
each block has the same shape as a single
[Link Entity](/api-reference/health-ai/medical-entity-codification/link-entity) response.

## When to use it

* Coding several entities from the same document (e.g. all symptoms in a note).
* Reducing round-trips when the ontology and `metadata` are identical.

<Note>
  Because `metadata` is shared across the whole batch, group queries that need
  different hints — especially LOINC tests with different units or specimens —
  into separate batches, or use the single
  [Link Entity](/api-reference/health-ai/medical-entity-codification/link-entity) endpoint.
</Note>

## Limits

| Constraint          | Value            |
| ------------------- | ---------------- |
| Queries per request | 1–5              |
| `top_k`             | 1–10 (default 5) |


## OpenAPI

````yaml POST /med-link/nel/link/batch
openapi: 3.1.0
info:
  title: Medical Entity Codification API
  version: 1.0.0
  description: >-
    The Medical Entity Codification API (MedLink Named Entity Linking) maps
    free-text medical entities — symptoms, diagnoses, lab tests and drugs — to
    standardised ontology codes such as SNOMED CT, LOINC, ICD-10-CM and Eka's
    medication database.
servers:
  - url: https://api.eka.care
    description: Production
security:
  - authApiKey: []
tags:
  - name: Registry
    description: Discover the ontologies, versions and indexes available for codification.
  - name: Entity Linking
    description: Link free-text medical entities to standardised ontology codes.
paths:
  /med-link/nel/link/batch:
    post:
      tags:
        - Entity Linking
      summary: Link entities (batch)
      description: >-
        Links up to 5 free-text entities in a single call. All queries in a
        batch share the same `ontology`, `version`, `top_k` and `metadata`. The
        response contains one result block per query, in request order.
      operationId: linkEntitiesBatch
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/NELBatchRequest'
            example:
              queries:
                - fever
                - headache
              ontology: snomed
              version: 20250401_extended
              top_k: 2
      responses:
        '200':
          description: One result block per query, in request order.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NELBatchResponse'
              example:
                results:
                  - request_id: e4b280cf-40a1-4a83-9f25-f7f07f3766ed
                    query: fever
                    query_breakdown: null
                    ontology: snomed
                    version: 20250401_extended
                    index_name: >-
                      snomed_20250401_extended_c88b15811956d4fcb54da9ae_1bfcc90540_pg
                    model_version: c88b15811956d4fcb54da9ae6d14a733ac90e7a7
                    results:
                      - term_id: '386661006'
                        term_name: Febrile
                        score: 0.89858478307724
                        is_linked: true
                        metadata:
                          semantic_tag: finding
                          is_core: true
                          source: snomed_ct_20250401_extended
                          language: en
                          script: latin
                  - request_id: e4b280cf-40a1-4a83-9f25-f7f07f3766ed
                    query: headache
                    query_breakdown: null
                    ontology: snomed
                    version: 20250401_extended
                    index_name: >-
                      snomed_20250401_extended_c88b15811956d4fcb54da9ae_1bfcc90540_pg
                    model_version: c88b15811956d4fcb54da9ae6d14a733ac90e7a7
                    results:
                      - term_id: '25064002'
                        term_name: Headache
                        score: 0.9999999403953606
                        is_linked: true
                        metadata:
                          semantic_tag: finding
                          is_core: true
                          source: snomed_ct_20250401_extended
                          language: en
                          script: latin
        '422':
          description: Validation error — a required field is missing or malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    NELBatchRequest:
      type: object
      required:
        - queries
        - ontology
        - version
      properties:
        queries:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 5
          description: List of free-text entities to link (1–5).
        ontology:
          type: string
          description: Ontology name applied to every query in the batch.
          example: snomed
        version:
          type: string
          description: Ontology version applied to every query in the batch.
          example: 20250401_extended
        top_k:
          type: integer
          minimum: 1
          maximum: 10
          default: 5
          description: Number of candidate results to return per query.
        metadata:
          type: object
          additionalProperties: true
          default: {}
          description: Ontology-specific hints applied to every query in the batch.
        request_id:
          type: string
          nullable: true
          description: Optional request ID. Generated automatically if omitted.
    NELBatchResponse:
      type: object
      required:
        - results
      properties:
        results:
          type: array
          description: One `NELResponse` per query, in request order.
          items:
            $ref: '#/components/schemas/NELResponse'
    HTTPValidationError:
      type: object
      properties:
        detail:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
    NELResponse:
      type: object
      required:
        - request_id
        - query
        - results
        - ontology
        - version
        - index_name
      properties:
        request_id:
          type: string
        query:
          type: string
        query_breakdown:
          type: object
          additionalProperties: true
          nullable: true
          description: >-
            How the query was parsed. Present for LOINC, medication and
            ICD-10-CM Comprehend; `null` for SNOMED CT.
        results:
          type: array
          items:
            $ref: '#/components/schemas/NELResult'
        ontology:
          type: string
        version:
          type: string
        index_name:
          type: string
          description: The index that served the request.
        model_version:
          type: string
          nullable: true
    ValidationError:
      type: object
      required:
        - loc
        - msg
        - type
      properties:
        loc:
          type: array
          items:
            anyOf:
              - type: string
              - type: integer
        msg:
          type: string
        type:
          type: string
    NELResult:
      type: object
      required:
        - term_id
        - term_name
      properties:
        term_id:
          type: string
          description: The ontology code for this candidate.
          example: '29857009'
        term_name:
          type: string
          description: Human-readable name of the candidate term.
          example: Chest pain
        score:
          type: number
          nullable: true
          description: >-
            Relevance/confidence of the candidate. `null` for medication, where
            matching is reported through `metadata.matching_breakdown` instead.
        is_linked:
          type: boolean
          default: false
          description: >-
            `true` when the pipeline is confident this candidate is the correct
            single match for the query.
        metadata:
          type: object
          additionalProperties: true
          nullable: true
          description: >-
            Ontology-specific detail about the candidate (e.g. `semantic_tag`
            for SNOMED, `matching_breakdown`/`eka_id` for LOINC,
            `generic_name`/`matching_breakdown` for medication).
  securitySchemes:
    authApiKey:
      type: http
      scheme: bearer
      description: >-
        Bearer access token issued by the Eka authorization flow. See
        [Authorization](/api-reference/authorization/getting-started).

````