Get A Release By ID

Get a release with a given identifier, optionally filtering out some content based on labels and zones. If the release is not found a 404 Not Found response status will be returned.

A release has a deliveryType field which indicates whether this is a ‘delta’ or a ‘full’ release. Delta releases allow updating an available ‘full’ release to a later version incrementally.

The iterationType field denotes the iteration of the release. Current values are ‘commercial’, ‘pilot’, ‘prototype’, ‘sample’ and ‘deprecated’.

A release has a tags field which is a map of key-value pairs. Tags are used to add additional information to a release, and do not necessarily follow a fixed structure. Only string keys and string values are supported.

The state field is an object which indicates whether a release is ‘published’, ‘released’, ‘recalled’ or ‘withdrawn’. A published release is not generally accessible. Released releases are accessible to customers. Recalled releases are also accessible to customer but this state indicates a problem has been reported related to this release. Withdrawn releases used to be generally accessible but were withdrawn because of a later identified issue with the release. The state object also contains a date which is the date at which the release got into the current state.

The frequencies describe the release cadence of the given release with possible values of ‘annual’, ‘yearly’, ‘semi-annual’, ‘quarterly’, ‘monthly’, ‘weekly’ or ‘daily’. Multiple values are possible.

It is possible to request a MetaLink 4 XML document which contains links to the release content. This Metalink file can be given to a number of download managers (for example aria2) which will then download the content. To receive this type of response, provide an Accept header with value application/metalink4+xml.

When downloading release content using MetaLink files and third-party download managers, make sure to pass the necessary Authentication and Authorization header. Not all download managers support this option.

Note

The names of labels and zones depends on the product family. Labels and zones that are in place and the structure of zone name is documented in the product documentation.

Endpoint	/releases/{ID}
HTTP Methods	GET
Response Content Type	application/vnd.tomtom.mcapi+json
Response Body	Release

Request Parameters

Name	Description	Required
id	A release id	Yes
zone	(repetitive) Only include content for zones starting with the given value	No
label	(repetitive) Only include content with labels equal to the given value	No

Example Request

curl -X GET 'https://example.com/releases/50?label=data&zone=WORLD.EUR.BEL'
    --header 'Accept: application/vnd.tomtom.mcapi+json'
    --header 'Authorization: Bearer <api_key>'

GET /releases/50?label=data&zone=WORLD.EUR.BEL HTTP/1.1
Host: example.com
Accept: application/vnd.tomtom.mcapi+json
Authorization: Bearer <api_key>

Example Response

HTTP/1.1 200
Content-Type: application/vnd.tomtom.mcapi+json

{
    "id": 50,
    "product": {
        "id": 42,
        "name": "Product Name",
        "location": "https://example.com/products/42"
    },
    "family": {
        "id": 41,
        "name": "Family Name",
        "location": "https://example.com/families/41"
    },
    "version": "2023.09.000",
    "deliveryType": "full",
    "iterationType": "prototype",
    "tags": {
        "some key": "a value"
    },
    "dueDate": "2023-11-07T10:01:29.000Z",
    "description": "standard release",
    "state": {
        "type": "released",
        "date": "2023-11-07T10:01:29.000Z",
        "reason": "reason",
    },
    "labels": ["data"],
    "zones": [{
        "name": "WORLD.EUR.BEL",
        "displayName": "Belgium"
    }],
    "contents": [{
        "id": 48,
        "name": "bel",
        "path": "/",
        "folder": true,
        "location": "https://example.com/contents/48",
        "checksum": null,
        "checksumType": null,
        "sizeBytes": 0,
        "zones": ["WORLD.EUR.BEL"],
        "labels": ["data"],
        "contents": [{
            "id": 49,
            "name": "bel.tar.gz",
            "path": "/bel",
            "folder": false,
            "location": "https://example.com/contents/49",
            "checksum": "15cb5edd330b63dc01eacde70e82d99e",
            "checksumType": "md5",
            "sizeBytes": 5429805,
            "zones": ["WORLD.EUR.BEL"],
            "labels": ["data"],
            "contents": [],
            "geoRestrictions": [],
            "action": null
        }],
        "geoRestrictions": [],
        "action": null
    }],
    "frequencies": [
        "annual",
        "quarterly"
    ]
}