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

# Get Vocabulary Releases

> Retrieve the list of all available OHDSI OMOP vocabulary dataset releases, including release dates, version identifiers, and validity metadata.

Retrieve information about all OHDSI vocabulary dataset releases available in the system. Each release represents a complete vocabulary dataset version (e.g., "2025.1") containing all OMOP vocabularies at a specific point in time.

## Query Parameters

<ParamField query="include_inactive" type="boolean" default="false">
  Include inactive releases in the response. By default, only active releases are returned.
</ParamField>

## Response

<ResponseField name="success" type="boolean">
  Indicates if the request was successful.
</ResponseField>

<ResponseField name="data" type="array">
  Array of vocabulary release objects.

  <Expandable title="Release Object">
    <ResponseField name="id" type="integer">
      Unique identifier for the release.
    </ResponseField>

    <ResponseField name="vocab_release" type="string">
      Release identifier (e.g., "2025.1", "2024.2").
    </ResponseField>

    <ResponseField name="version_number" type="string">
      Version number.
    </ResponseField>

    <ResponseField name="athena_version" type="string">
      ATHENA vocabulary version this release is based on.
    </ResponseField>

    <ResponseField name="release_date" type="string">
      ISO 8601 formatted release date.
    </ResponseField>

    <ResponseField name="status" type="string">
      Release status (e.g., "ready", "pending", "deprecated").
    </ResponseField>

    <ResponseField name="is_default" type="boolean">
      Whether this is the default release used when no version is specified.
    </ResponseField>

    <ResponseField name="is_active" type="boolean">
      Whether this release is currently active and available for use.
    </ResponseField>

    <ResponseField name="total_concepts" type="integer">
      Total number of concepts across all vocabularies in this release.
    </ResponseField>

    <ResponseField name="total_vocabularies" type="integer">
      Number of vocabularies included in this release.
    </ResponseField>

    <ResponseField name="total_relationships" type="integer">
      Total number of concept relationships in this release.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="meta" type="object">
  <Expandable title="Metadata">
    <ResponseField name="request_id" type="string">
      Unique identifier for the request.
    </ResponseField>

    <ResponseField name="timestamp" type="string">
      Request timestamp.
    </ResponseField>

    <ResponseField name="vocab_release" type="string">
      Current default vocabulary release.
    </ResponseField>

    <ResponseField name="pagination" type="object">
      Pagination information.

      <Expandable title="Pagination">
        <ResponseField name="page" type="integer">
          Current page number.
        </ResponseField>

        <ResponseField name="page_size" type="integer">
          Number of items returned.
        </ResponseField>

        <ResponseField name="total_items" type="integer">
          Total number of releases.
        </ResponseField>

        <ResponseField name="total_pages" type="integer">
          Total number of pages.
        </ResponseField>

        <ResponseField name="has_next" type="boolean">
          Whether there are more pages.
        </ResponseField>

        <ResponseField name="has_previous" type="boolean">
          Whether there are previous pages.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://api.omophub.com/v1/vocabularies/releases" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```bash cURL (with options) theme={null}
  curl -X GET "https://api.omophub.com/v1/vocabularies/releases?include_inactive=true" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://api.omophub.com/v1/vocabularies/releases",
      headers={"Authorization": "Bearer YOUR_API_KEY"}
  )
  data = response.json()
  for release in data["data"]:
      print(f"{release['vocab_release']}: {release['total_concepts']} concepts")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('https://api.omophub.com/v1/vocabularies/releases', {
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY'
    }
  });
  const data = await response.json();
  console.log(data.data);
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": [
      {
        "id": 1,
        "vocab_release": "2025.1",
        "version_number": "1",
        "athena_version": "v5.3.1",
        "release_date": "2025-01-01T00:00:00Z",
        "status": "ready",
        "is_default": true,
        "is_active": true,
        "total_concepts": 8547321,
        "total_vocabularies": 87,
        "total_relationships": 45678234
      },
      {
        "id": 2,
        "vocab_release": "2024.2",
        "version_number": "4",
        "athena_version": "v5.3.0",
        "release_date": "2024-10-01T00:00:00Z",
        "status": "ready",
        "is_default": false,
        "is_active": true,
        "total_concepts": 8234567,
        "total_vocabularies": 85,
        "total_relationships": 44567123
      }
    ],
    "meta": {
      "request_id": "req_abc123def456",
      "timestamp": "2025-01-05T10:30:00Z",
      "vocab_release": "2025.1",
      "pagination": {
        "page": 1,
        "page_size": 2,
        "total_items": 2,
        "total_pages": 1,
        "has_next": false,
        "has_previous": false
      }
    }
  }
  ```
</ResponseExample>

## Usage Examples

### Get Active Releases

```bash theme={null}
curl -X GET "https://api.omophub.com/v1/vocabularies/releases" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

### Include Inactive Releases

```bash theme={null}
curl -X GET "https://api.omophub.com/v1/vocabularies/releases?include_inactive=true" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Notes

* Each release represents a complete OHDSI vocabulary dataset at a point in time
* The `is_default` release is used when no specific version is requested
* Use the `vocab_release` value (e.g., "2025.1") in the `vocab_release` query parameter of other endpoints to query specific versions

## Related Endpoints

* [List Vocabularies](/api-reference/vocabularies/list-vocabularies) - Get all vocabularies in a release