API Deprecation Guidance - July 2025

The majority of the https://api.healthdatagateway.org/api/v1/* APIs for collections, datasets, data uses, publications and tools will be deprecated in July 2025 and removed in January 2026, to be replaced with https://api.healthdatagateway.org/api/v2/*. The guidance below outlines how the V2 APIs supersede their V1 equivalents.

Operation	V1	V2	Comments

Operation	V1	V2	Comments
index (GET)	`/api/v1/{entity-name}`	`/api/v2/{entity_name}`	The V2 version no longer offers filtering by `user_id` or `team_id`. Instead use `/api/v2/users/{userId}/{entityName}`, `/api/v2/teams/{teamId}/{entityName}`
count (GET)	`/api/v1/{entityName}/count/{field}`	`/api/v2/{entityName}/count/{field}`	The V2 version no longer offers filtering by user_id or team_id. Instead use `/api/v2/users/{userId}/{entityName}/count/{field}`, `/api/v2/teams/{teamId}/{entityName}/count/{field}`
show (GET)	`/api/v1/{entityName}/{id}`	`/api/v2/{entityName}/{id}`	Also available in v2 are `/api/v2/users/{userId}/{entityName}/{id}` and `/api/v2/teams/{teamId}/{entityName}/{id}` which will show more information in the response
store (POST)	`/api/v1/{entityName}`	`/api/v2/teams/{teamId}/{entityName}` `/api/v2/users/{userId}/{entityName}`	Datasets can only be created under a team, other entities can be created under a user or a team
update (PUT)	`/api/v1/{entityName}/{entityId}`	`/api/v2/teams/{teamId}/{entityName}/{entityId}` `/api/v2/users/{userId}/{entityName}/{entityId}`
edit (PATCH)	`/api/v1/{entityName}/{entityId}`	`/api/v2/teams/{teamId}/{entityName}/{entityId}` `/api/v2/users/{userId}/{entityName}/{entityId}`	To archive an entity, edit its `status` field to `“ARCHIVED"`, instead of calling `DELETE` as in V1
destroy (DELETE)	`/api/v1/<entity-name>/{entityId}`	`/api/v2/teams/{teamId}/{entityName}/{entityId}` `/api/v2/users/{userId}/{entityName}/{entityId}`	Entities can only be deleted under the user or team that created them

New in V2 only

Operation	Endpoints	Comments

Operation

Endpoints

Comments

indexStatus (GET)

/api/v2/teams/{teamId}/{entityName}/status/{status}

Return all entities of the given status under that team or user.

The entities can be filtered by title/name etc. using query parameters.

-