> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clinia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Concepts

> Understanding clinical concepts as the fundamental units of terminology in Clinia

# Concepts

A **concept** represents a single clinical idea or entity within a [vocabulary](/explanation/vocabularies). Each concept has a unique code within its vocabulary and includes human-readable descriptions, making it the fundamental building block of clinical terminologies.

## What is a Concept?

Concepts are the individual units of meaning within terminology systems. They represent specific clinical ideas, such as diseases, procedures, medications, or observations, in a standardized and machine-readable format.

**Core characteristics:**

* **Unique identification**: Each concept has a unique code within its vocabulary
* **Human-readable**: Includes display text and definitions for clinical users
* **Multilingual support**: Can include translations and alternative names

## Concept Structure

A concept in Clinia contains the following properties:

| Property        | Type                                                         | Description                                                                      |
| --------------- | ------------------------------------------------------------ | -------------------------------------------------------------------------------- |
| `vocabularyKey` | [`code`](/explanation/data-types/base-types#code-code)       | Identifier of the containing vocabulary (read-only, provided as a URL parameter) |
| `code`          | [`code`](/explanation/data-types/base-types#code-code)       | Unique identifier within the vocabulary (read-only)                              |
| `definition`    | [`symbol`](/explanation/data-types/base-types#symbol-symbol) | Detailed explanation of the concept's clinical meaning                           |
| `designation`   | [`object`](/explanation/data-types/base-types#object)        | Alternative names and translations in different languages                        |

**Example concept:**

```json theme={null}
{
  "code": "44054006",
  "definition": "A form of diabetes mellitus characterized by insulin resistance and relative insulin deficiency",
  "designation": {
    "en": "Type 2 diabetes mellitus",
    "fr": "Diabète de type 2",
    "es": "Diabetes mellitus tipo 2"
  }
}
```

## Managing Concepts

### Creating a Concept

Use the [upsert concept endpoint](/api-reference/vocabularies/upsert-a-concept-in-a-vocabulary) to create or update concepts:

```bash theme={null}
curl -X PUT "https://$CLINIA_WORKSPACE/terminology/v1/vocabularies/{vocabularyKey}/concepts/{conceptCode}" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "definition": "A chronic metabolic disorder characterized by high blood glucose levels",
    "designation": {
      "en": "Diabetes mellitus",
      "fr": "Diabète sucré"
    }
  }'
```

### Retrieving Concepts

Get specific concepts by their code:

```bash theme={null}
curl -X GET "https://$CLINIA_WORKSPACE/terminology/v1/vocabularies/{vocabularyKey}/concepts/{conceptCode}" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN"
```

### Searching Concepts

Use the [concept query endpoint](/api-reference/vocabularies/search-for-concepts-in-the-terminology) to perform concept resolution, using Clinia's [operators](/explanation/operator) and semantic [search](/explanation/search) capabilities:

```bash theme={null}
curl -X POST "https://$CLINIA_WORKSPACE/terminology/v1/vocabularies/*/concepts/query" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "query": {
      "match": {
        "designation.en": {
          "value": "diabetes",
          "type": "word"
        }
      }
    }
  }'
```

### Bulk Operations

Efficiently manage large sets of concepts using [bulk operations](/api-reference/vocabularies/bulk-upsert-update-or-delete-concepts):

```bash theme={null}
curl -X POST "https://$CLINIA_WORKSPACE/terminology/v1/vocabularies/{vocabularyKey}/concepts/bulk" \
  -H "X-Clinia-API-Key: $CLINIA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {
        "action": "UPSERT",
        "upsert": {
          "code": "123456789",
          "definition": "Example clinical concept",
          "designation": {
            "en": "Example Concept"
          }
        }
      }
    ]
  }'
```

## Concept Validation

Concepts are central to field validation at Clinia.
*Learn how to do [vocabulary-based validation](/explanation/field-validation/vocabulary) here.*

## Related Concepts

<CardGroup cols={2}>
  <Card title="Vocabularies" icon="book" href="/explanation/vocabularies">
    Learn about the containers that organize concepts into terminology systems
  </Card>

  <Card title="Clinical Terminology Standards" icon="book-medical" href="/explanation/vocabularies#clinical-terminology-standards">
    Understand the major terminology standards and their concept structures
  </Card>

  <Card title="Coding Data Type" icon="code" href="/explanation/data-types/clinia-types#coding-coding">
    See how concepts are represented in FHIR data structures
  </Card>

  <Card title="Field Validation" icon="shield-check" href="/explanation/field-validation/vocabulary">
    Explore how concepts enable clinical data validation
  </Card>
</CardGroup>

***

**Ready to work with concepts?** Start with the [Concept API reference](/api-reference/vocabularies/upsert-a-concept-in-a-vocabulary) to manage your clinical concepts.