> For the complete documentation index, see [llms.txt](https://docs.b2ihealthcare.com/snowray/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.b2ihealthcare.com/snowray/reference/api-access.md).

# API access

{% hint style="info" %}
Access to the Ontology Platform via its API endpoints is available to Enterprise tier users.
{% endhint %}

### FHIR Terminology API

The Ontology Platform provides a set of interactions and endpoints based on the [FHIR Terminology Service](https://hl7.org/fhir/terminology-service.html) specification and supports the [R4](https://hl7.org/fhir/R4/index.html), [R4B](https://hl7.org/fhir/R4B/index.html) and [R5](https://hl7.org/fhir/R5/index.html) formats.

To access the API you can navigate to your deployment's `/api-docs` subpage to see the rendered OpenAPI specification or if you wish to access the descriptor, you can request via this route:

```
curl https://<host>/api/openapi
```

The base URL of the FHIR API is `<host>/api/fhir` . To access the list of Code Systems available in the platform you can perform the following request:

```
curl https://<host>/api/fhir/CodeSystem \
  -H "Authorization: Bearer <YOUR_API_KEY>"
```

This will return a paginated list of Code Systems that your user has access to. The system defaults to the R5 format, to use R4 you need to explicitly request it through the Accept header:

```
curl https://<host>/api/fhir/CodeSystem \
  -H "Authorization: Bearer <YOUR_API_KEY>" 
  -H "Accept: application/fhir+json;fhirVersion=4.0"
```

For further information on the FHIR API capabilities please refer to the official Ontology Server documentation [here](https://docs.b2ihealthcare.com/snow-owl/rest-apis).

### Advanced Terminology API

For advanced content management and terminology workflows, the platform provides a set of dedicated API endpoints supporting use cases, such as:

* Import and export of ontology-specific and custom file formats, such as SNOMED CT RF2, LOINC official releases, ICD-10 ClaML, Excel, CSV, and many more
* Authoring and updating terminology content programmatically when updates through FHIR interactions are not possible or would be cumbersome
* Retrieving concept suggestions from one or more Code Systems or Value Sets based on input text and a configuration object

To explore these endpoints, visit the Terminology Server API documentation available at the `/snowowl` subpage.

{% hint style="warning" %}
***Note:*** A FHIR API group is available in this API collection as well, but the recommended way to access FHIR functionality is through the `/api/fhir` route. See [#fhir-terminology-api](#fhir-terminology-api "mention").
{% endhint %}

### API Keys

All content request API endpoints are protected and require an API token to be supplied in the `Authorization` HTTP header. API keys can be managed from the *Developer Settings* section of your profile settings.

<figure><img src="https://1779028359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCGAqlIn2vgCXJQadBh7%2Fuploads%2FvwJNuSp0zKMxYZotlFpO%2Fsettings_api.png?alt=media&amp;token=c44cc8d7-08e2-4985-b09b-8efb5a345123" alt=""><figcaption><p>API Keys Settings</p></figcaption></figure>

Click on the <img src="https://content.gitbook.com/content/qCGAqlIn2vgCXJQadBh7/blobs/rYuByx1fyvbrfyYxx2au/generate_new_token_button.png" alt="" data-size="line"> button and specify the required details for the new API token.

<figure><img src="https://1779028359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCGAqlIn2vgCXJQadBh7%2Fuploads%2FyBECiqRuhnvt9ylnFt1G%2Fsettings_api_generation_wizard.png?alt=media&amp;token=5eda72f5-eea3-48b4-b35d-bf42363585b6" alt="" width="279"><figcaption><p>API Key Generation Wizard</p></figcaption></figure>

| Property            | Definition                                                                                                                             |
| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Token name**      | The name of the token (mandatory)                                                                                                      |
| **Description**     | The description of the token                                                                                                           |
| **Expiration**      | Validity period of the token (mandatory)                                                                                               |
| **Permissions**     | <p>Permission type of the token (mandatory)<br><em>Note:</em> Currently, the only allowed value for this property is <em>Read</em></p> |
| **Resource Access** | The resources that are in scope of the token (mandatory)                                                                               |

Clicking <img src="https://content.gitbook.com/content/qCGAqlIn2vgCXJQadBh7/blobs/SSoRJBlBM2ORHBfyVe7U/generate_button.png" alt="" data-size="line"> completes the creation process and displays the newly generated token in a pop-up window.

<figure><img src="https://1779028359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCGAqlIn2vgCXJQadBh7%2Fuploads%2FRlDEZcluDryktc7zcHQT%2Fsettings_api_key_generated.png?alt=media&amp;token=12a01d3b-7135-4fd3-8677-852c04d930ab" alt="" width="278"><figcaption><p>Confirmation of Successfully Generated Token</p></figcaption></figure>

{% hint style="warning" %}
The new token is displayed only after creation. To save it, copy it from the pop-up window.
{% endhint %}

Existing tokens can be viewed and edited by clicking their name.

<figure><img src="https://1779028359-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FqCGAqlIn2vgCXJQadBh7%2Fuploads%2FGCZ4gvKEW375iToIOyna%2Fsettings_api_with_key.png?alt=media&amp;token=fd501ff3-2bd7-426e-a0ae-5db5f8f5b025" alt=""><figcaption><p>List of Available API Keys</p></figcaption></figure>

Minor token details, such as the description, can be edited without affecting the generated token.

Listed tokens can be deleted using the <img src="https://content.gitbook.com/content/qCGAqlIn2vgCXJQadBh7/blobs/y2tUFAbdqZXcRBPvGTQE/delete_icon.svg" alt="" data-size="line"> icon.

{% hint style="danger" %}
Deleting a token does not place it on a deny list, and the token remains valid until its expiration date. Please note that token revocation is not currently supported.
{% endhint %}