Foods

A food represents a product in all its packaging or consumption sizes - as long as they have equivalent nutritional information. Every food belongs to one brand and one category, and has one or more servings.

FieldTypeDescription
foodIduuidA UUID identifying the food. This does not change when the food changes.
revisionIduuidA UUID identifying the revision of the food. This will change whenever the food changes. If the revisionId of a food has not changed, you are guaranteed that the foods nutrients and servings have not changed either.
regionstringThe region associated with the food.
brandbrandThe food's brand.
categorycategoryThe food's category.
tags[]list<tag>A list of tags associated with the food.
namestringThe name of the food.
classificationstringThe food's classification.
massstringThe mass (in grams) associated with the nutrient information if it is known.
volumestringThe volume (in milliliters) associated with the nutrient information if it is known.
servings[]listA list of one or more servings for the food.
servings[].namestringThe name of the serving.
servings[].scalefloatThe scale of the serving compared to the inforamiotn attached to the food (eg. mass, volume, nutrients).
servings[].typestringOne of 'mass', 'volume', or 'serving' indicating the type of the serving. A type of 'serving' is used when the mass or volume is unknown.
nutrientsobjectA key:value listing of available nutrient information. See nutrients for a list of available nutrients.
/foods get

Returns a collection of all the foods in the CalorieKing database.

Request
Response

Request

Query Parameters
  • query: (string)

    Filter based on this query string. The exact meaning of this string depends on the query-type parameter.

  • query-type: one of (fts,prefix)

    Dictates how the query parameter is interpreted:

    • fts - Search for resources matching the query string using full text search (case insensitive).
    • prefix - Search for resources with names beginning with the query string (case insensitive).
  • region: one of (au,us)

    Filter results by region.

  • fields: (string)

    Selector to specify the fields to include in partial-responses

  • limit: (number)

    The number of results to include in requests when paging

  • offset: (number)

    The index (zero-based) of the first result to return when paging

  • brands: (string)

    Filter the results by brands. The syntax for the parameter is a comma separated list of brand IDs where you can:

    • Limit the results to a brand by specifying a brand ID
    • Exclude a brand from the results by prefixing the brand ID with a exclamation mark
    • Specify multiple brands to include or exclude by using a comma separated list

    For example, to return results for only McDonald's and McDonald's McCafe:

    GET /foods?region=us&brand=c4697cb5-74b3-437a-a1cd-d663cabd4f9f,754cd4a3-a253-4c80-8807-8b039d14c212
    

    To exclude Average All Brand results:

    GET /foods?region=us&query=orange&brand=!72e34d90-9563-4433-8ec4-c51801d06330
    
  • tags: (string)

    Filter results by tags. The syntax of this parameter should be a comma separated list of tag IDs. To exclude a certain tag, prefix the tag ID with an exclamation mark.

    For example, to limit a search to fruits:

    GET /foods?region=us&query=apple&tags=e6c09930-91af-4ef2-8e07-5d70fccb57a2
    

    To limit a search to fruits but exclude dried fruits:

    GET /foods?region=us&query=apple&tags=e6c09930-91af-4ef2-8e07-5d70fccb57a2,!42e5298c-293f-4ca4-9a89-d7708cb3907b
    
  • categories: (string)

    Filter results by categories. This is a comma separated list of category ids. The list may be prepended with a '!' to invert the filter and return foods that are not in any of the specified categories. Non-leaf categories may be included in this filter. In this case, the filter will return foods contained in any of the leaf categories under the non-leaf category.

  • classifications: (string)

    Filter results by classifications. This is a comma separated list of classification strings. Classification strings can be enclosed in double quotes to escape commas if necessary. The list may be prepended with a '!' to return foods without the listed classifications.

  • grouping: one of (brand,classification)

    Groups results either by brand or classification. See Food Ordering & Grouping for more details.

  • grouping-order: (string)

    Specifies the order of groups when a grouping has been specify. See Food Ordering & Grouping for more details.

    grouping-order=field:direction

    field (required): One of (rank, name)

    • rank: Order the groups according to the relevance of the foods it contains.

    • name: Order the groups according to the name of the group.

    direction: One of (asc, desc)

    • asc (default): Order the groups ascending.

    • desc: Order the groups descending.

    Note: A direction of ascending when used together with rank will result in the most relevant results appearing first.

  • grouping-limit: (number)

    Limit the number of foods included within a group. See Food Ordering & Grouping for more details.

  • order: (string)

    The order of in which the foods will be returned.

    Format: order=field:direction

    field (required): One of (rank, name)

    direction: One of (asc, desc). Defaults to 'asc' if omitted. A direction of ascending when used together with rank will result in the most relevant results appearing first.

    e.g. To order foods by name descending, order=name:desc

Responses

HTTP status code 200

OK.

The request succeeded and a collection of foods returned.

Body
application/json

Example:

{
  "metadata": {
    "total": 80,
    "limit": 20,
    "offset": 0
  },
  "foods": [
    {
      "revisionId": "66392724-3352-4af9-9579-f9ffb4450411",
      "brand": {
        "id": "7f2591ff-36d6-4344-8596-6e0b25d3e301",
        "name": "McDonald's"
      },
      "name": "French Fries",
      "classification": "Chips & Fries"
    },
    {
      "revisionId": "0789b1fd-fd51-4002-970f-48ee438edec9",
      "brand": {
        "id": "7f2591ff-36d6-4344-8596-6e0b25d3e301",
        "name": "McDonald's"
      },
      "name": "Big Mac Burger",
      "classification": "Sandwiches & Burgers",
    }
  ]
}
HTTP status code 400

Bad Request.

The request is invalid as outlined in the response message. Further information may exist and if so will be listed in the response details.

Body
application/json

Example:

{
  "code": 400,
  "message": "Unknown path in 'fields'",
  "details": "Path: 'category'"
}
HTTP status code 401

Unauthorized.

The request requires user authentication.

Body
application/json

Example:

{
  "code": 401,
  "message": "Not Authorized"
}
/foods/{foodId} get

Returns a specific food from the CalorieKing database.

Request
Response

Request

URI Parameters
  • foodId: required (string)

    The id of the food

Query Parameters

Responses

HTTP status code 200

OK.

The request succeeded and the food returned.

Body
application/json

Example:

{
  "food": {
    "revisionId": "0d613b29-214a-46d8-b3c6-d94a8f4a5d05",
    "foodId": "46b92291-86cc-4cc5-bce4-40b100c7f90c",
    "brand": {
      "id": "b2c1e370-1e74-421f-b685-513efede17b1",
      "name": "Coca-Cola"
    },
    "tags": [
      {
        "id": "b5dfce01-7215-45d1-bd8a-759bb82dc9bc",
        "name": "Soft Drinks, Soda"
      },
      {
        "id": "becb8a31-799e-4323-931d-63adb43569e8",
        "name": "Sodas, Soft Drinks"
      }
    ],
    "name": "Classic Coca-Cola",
    "classification": "Sodas, Soft Drinks",
    "volume": 240.0,
    "servings": [
      {
        "name": "cup",
        "scale": 1.0,
        "type": "volume"
      },
      {
        "name": "can or bottle",
        "scale": 1.47916666666667,
        "type": "volume"
      },
      {
        "name": "can",
        "scale": 0.925,
        "type": "volume"
      },
      {
        "name": "bottle",
        "scale": 2.4625,
        "type": "volume"
      }
    ],
    "upcs": {
      "0067000008290": {
        "servingIndex": 2,
        "quantity": 1.0
      },
      "0067000004162": {
        "servingIndex": 3,
        "quantity": 1.0
      },
      "0067000004278": {
        "servingIndex": 3,
        "quantity": 1.0
      },
      "0067000001857": {
        "servingIndex": 0,
        "quantity": 1.0
      }
    },
    "nutrients": {
      "energy": 405.0,
      "fat": 0.0,
      "protein": 0.0,
      "sugar": 27.0,
      "fiber": 0.0,
      "sodium": 33.0,
      "cholesterol": 0.0,
      "alcohol": 0.0,
      "potassium": 0.0,
      "caffeine": 23.0
    }
  }
}
HTTP status code 400

Bad Request.

The request is invalid as outlined in the response message. Further information may exist and if so will be listed in the response details.

Body
application/json

Example:

{
  "code": 400,
  "message": "Unknown path in 'fields'",
  "details": "Path: 'category'"
}
HTTP status code 401

Unauthorized.

The request requires user authentication.

Body
application/json

Example:

{
  "code": 401,
  "message": "Not Authorized"
}
HTTP status code 404

Not Found.

No food exists for the given id.

Body
application/json

Example:

{
  "code": 404,
  "message": "Food not found",
  "details": "id: c4e85530-e4b1-421e-b1f8-ae32f39934b9"
}

Brands

A brand or restaurant from the CalorieKing database. Every food belongs to a single brand.

FieldTypeDescription
iduuidA UUID identifying the brand
namestringThe name of the brand
regionstringThe region associated with the brand

Each region contains a special brand called Average All Brands that contains generic foods (eg. apple, banana, etc). These brands can be identified using their UUID:

RegionUUID
us72e34d90-9563-4433-8ec4-c51801d06330
au4a497106-5e8c-4729-9451-667c2b57514b
/brands get

Returns a collection of brands from the CalorieKing database.

Request
Response

Request

Query Parameters
  • classifications: (string)

    Filter brands to those with foods with the specified classifications. This is a comma separated list of classification strings. Classification strings can be enclosed in double quotes to escape commas if necessary. The list may be prepended with a '!' to return brands with foods without the listed classifications.

  • categories: (string)

    Filter brands to those with foods in the specified categories. This is a comma separated list of category ids. The list may be prepended with a '!' to invert the filter and return brands with foods that are not in any of the specified categories. Non-leaf categories may be included in this filter. In this case, the filter will work on foods contained in any of the leaf categories under the non-leaf category.

  • tags: (string)

    Filter brands to those with foods with the specified tags. This is a comma separated list of tag ids. Each tag id can be prefixed with a '!' to indicate that foods with that tag should be excluded, rather than included.

    For Example, to select US brands that contain foods tagged as 'Fruit', but not as 'Dried Fruit'

    GET /brands?region=us&tags=2dff5ec3-2e9f-4da9-852e-61efbf2d67b8,!c3f2271b-add6-4d9c-937e-317c610eb13a

  • order: one of (asc,desc)

    Results are ordered alphabetically by name. This field indicated whether they are in ascending or descending alphabetical order.

  • query: (string)

    Filter based on this query string. The exact meaning of this string depends on the query-type parameter.

  • query-type: one of (fts,prefix)

    Dictates how the query parameter is interpreted:

    • fts - Search for resources matching the query string using full text search (case insensitive).
    • prefix - Search for resources with names beginning with the query string (case insensitive).
  • region: one of (au,us)

    Filter results by region.

  • fields: (string)

    Selector to specify the fields to include in partial-responses

  • limit: (number)

    The number of results to include in requests when paging

  • offset: (number)

    The index (zero-based) of the first result to return when paging

Responses

HTTP status code 200

OK.

The request succeeded and a collection of brands returned.

Body
application/json

Example:

{
  "metadata": {
    "total": 80,
    "limit": 20,
    "offset": 0
  },
  "brands": [
    {
      "id": "fb8d3d1b-1e61-4d32-96ae-dec48ea46e57",
      "region": "us",
      "name": "Apple & Eve"
    },
    {
      "id": "41bc9cd2-78dd-4844-9015-c8c92c19b710",
      "region": "us",
      "name": "Apple Time"
    },
    {
      "id": "c7484dac-78e0-498e-a713-83267a8e82ef",
      "region": "us",
      "name": "Applebee's"
    },
    {
      "id": "aa63f901-8e2d-47e9-a740-114433d7e130",
      "region": "us",
      "name": "Applegate Farms"
    }
  ]
}
HTTP status code 400

Bad Request.

The request is invalid as outlined in the response message. Further information may exist and if so will be listed in the response details.

Body
application/json

Example:

{
  "code": 400,
  "message": "Unknown path in 'fields'",
  "details": "Path: 'classification'"
}
HTTP status code 401

Unauthorized.

The request requires user authentication.

Body
application/json

Example:

{
  "code": 401,
  "message": "Not Authorized"
}
/brands/{brandId} get

Returns a specific brand from the CalorieKing database.

Request
Response

Request

URI Parameters
  • brandId: required (string)
Query Parameters

Responses

HTTP status code 200

OK.

The request has succeeded and the brand returned.

Body
application/json

Example:

{
  "brand": {
    "id": "3ebcd32e-7809-460d-8766-467f042beba9",
    "region": "us",
    "name": "Nestle"
  }
}
HTTP status code 400

Bad Request.

The request is invalid as outlined in the response message. Further information may exist and if so will be listed in the response details.

Body
application/json

Example:

{
  "code": 400,
  "message": "Unknown path in 'fields'",
  "details": "Path: 'classification'"
}
HTTP status code 401

Unauthorized.

The request requires user authentication.

Body
application/json

Example:

{
  "code": 401,
  "message": "Not Authorized"
}
HTTP status code 404

Not Found.

No brand exists for the given id.

Body
application/json

Example:

{
  "code": 404,
  "message": "Brand not found",
  "details": "id: 43afe4c7-ffd5-4ccd-a14e-c3f297e34d48"
}

Categories

Categories organize foods into an hierarchical tree structure. Each food is directly associated with one, and only one category. Categories can either contain other categories, or contain foods, but not both. Categories that contains foods are refered to as leaf categories.

FieldTypeDescription
iduuidA UUID identifying the category
regionstringThe region associated with the category
namestringThe name of the category
parentuuidThe id of the category that contains this category. This field will not be present for top level categories.
hierarchy[]listAn array of all categories from the top level category down to this category, showing the position of this category in the hierarchy tree. This field enables a fully qualified category name to be displayed, with links to parent categories, without needing to fetch parent categories. Each entry in this array is a HierarchyEntry as described below.
hierarchy[].iduuidThe id of the category.
hierarchy[].namestringThe name of the category.
isLeafbooleanIndicates whether the category is a leaf. Leaf categories contain foods, but no other categories. Non-leaf categories contain other categories, but not foods.
/categories get

Returns a list of categories matching the specified criteria.

Request
Response

Request

Query Parameters
  • classifications: (string)

    Filter categories to those with foods with the specified classifications. This is a comma separated list of classification strings. Classification strings can be enclosed in double quotes to escape commas if necessary. The list may be prepended with a '!' to return categories with foods without the listed classifications.

  • brands: (string)

    Filter categories to those with foods in the specified brands. This is a comma separated list of brand ids. The list may be prepended with a '!' to invert the filter and return categories with foods that are not in any of the specified brands.

  • tags: (string)

    Filter categories to those with foods with the specified tags. This is a comma separated list of tag ids. Each tag id can be prefixed with a '!' to indicate that foods with that tag should be excluded, rather than included.

    For Example, to select US categories that contain foods tagged as 'Fruit', but not as 'Dried Fruit'

    GET /categories?region=us&tags=2dff5ec3-2e9f-4da9-852e-61efbf2d67b8,!c3f2271b-add6-4d9c-937e-317c610eb13a

  • order: one of (asc,desc)

    Results are ordered alphabetically by name. This field indicated whether they are in ascending or descending alphabetical order.

  • query: (string)

    Filter based on this query string. The exact meaning of this string depends on the query-type parameter.

  • query-type: one of (fts,prefix)

    Dictates how the query parameter is interpreted:

    • fts - Search for resources matching the query string using full text search (case insensitive).
    • prefix - Search for resources with names beginning with the query string (case insensitive).
  • region: one of (au,us)

    Filter results by region.

  • fields: (string)

    Selector to specify the fields to include in partial-responses

  • limit: (number)

    The number of results to include in requests when paging

  • offset: (number)

    The index (zero-based) of the first result to return when paging

  • parents: (string)

    Filter returned categories based on their parent. This is a comma separated list of category ids (uuid). This parameter may be inverted by prepending a '!'.

  • is-leaf: (boolean)

    Filter returned categories based on whether or not they are a leaf categories. Leaf categories contain foods. Non-leaf categories contain other categories.

Responses

HTTP status code 200

OK.

The request succeeded and a collection of categories returned.

Body
application/json

Example:

{
  "metadata": {
    "total": 80,
    "limit": 20,
    "offset": 0
  },
  "categories": [
    {
      "id": "84c81cdc-8ae9-4ee2-9654-9c644e8181f5",
      "region": "us",
      "name": "Alcoholic Drinks",
      "hierarchy": [
        {
          "id": "84c81cdc-8ae9-4ee2-9654-9c644e8181f5",
          "name": "Alcoholic Drinks"
        }
      ],
      "isLeaf": false
    },
    {
      "id": "e9be2377-680f-4f9a-be20-fe7892f05b02",
      "region": "us",
      "name": "Ales & Beers",
      "hierarchy": [
        {
          "id": "84c81cdc-8ae9-4ee2-9654-9c644e8181f5",
          "name": "Alcoholic Drinks"
        },
        {
          "id": "e9be2377-680f-4f9a-be20-fe7892f05b02",
          "name": "Ales & Beers"
        }
      ],
      "parent": "84c81cdc-8ae9-4ee2-9654-9c644e8181f5",
      "isLeaf": true
    },
    {
      "id": "2c4ce015-0180-420c-b937-49a2758be2fd",
      "region": "us",
      "name": "Ciders, Wines",
      "hierarchy": [
        {
          "id": "84c81cdc-8ae9-4ee2-9654-9c644e8181f5",
          "name": "Alcoholic Drinks"
        },
        {
          "id": "2c4ce015-0180-420c-b937-49a2758be2fd",
          "name": "Ciders, Wines"
        }
      ],
      "parent": "84c81cdc-8ae9-4ee2-9654-9c644e8181f5",
      "isLeaf": true
    },
    {
      "id": "2b830a3e-a787-4d67-8a53-de8ba036c350",
      "region": "us",
      "name": "Coolers, Cocktails, Shooters",
      "hierarchy": [
        {
          "id": "84c81cdc-8ae9-4ee2-9654-9c644e8181f5",
          "name": "Alcoholic Drinks"
        },
        {
          "id": "2b830a3e-a787-4d67-8a53-de8ba036c350",
          "name": "Coolers, Cocktails, Shooters"
        }
      ],
      "parent": "84c81cdc-8ae9-4ee2-9654-9c644e8181f5",
      "isLeaf": true
    },
    {
      "id": "5d551ac4-aa63-40af-9be7-21c5399be417",
      "region": "us",
      "name": "Liqueurs, Liquors & Spirits",
      "hierarchy": [
        {
          "id": "84c81cdc-8ae9-4ee2-9654-9c644e8181f5",
          "name": "Alcoholic Drinks"
        },
        {
          "id": "5d551ac4-aa63-40af-9be7-21c5399be417",
          "name": "Liqueurs, Liquors & Spirits"
        }
      ],
      "parent": "84c81cdc-8ae9-4ee2-9654-9c644e8181f5",
      "isLeaf": true
    }
  ]
}
HTTP status code 400

Bad Request.

The request is invalid as outlined in the response message. Further information may exist and if so will be listed in the response details.

Body
application/json

Example:

{
  "code": 400,
  "message": "Unknown path in 'fields'",
  "details": "Path: 'classification'"
}
HTTP status code 401

Unauthorized.

The request requires user authentication.

Body
application/json

Example:

{
  "code": 401,
  "message": "Not Authorized"
}
/categories/{categoryId} get

Returns a specific category from the CalorieKing database.

Request
Response

Request

URI Parameters
  • categoryId: required (string)
Query Parameters

Responses

HTTP status code 200

OK.

The request has succeeded and the category returned.

Body
application/json

Example:

{
  "category": {
    "id": "3ebcd32e-7809-460d-8766-467f042beba9",
    "region": "us",
    "name": "Nestle"
  }
}
HTTP status code 400

Bad Request.

The request is invalid as outlined in the response message. Further information may exist and if so will be listed in the response details.

Body
application/json

Example:

{
  "code": 400,
  "message": "Unknown path in 'fields'",
  "details": "Path: 'classification'"
}
HTTP status code 401

Unauthorized.

The request requires user authentication.

Body
application/json

Example:

{
  "code": 401,
  "message": "Not Authorized"
}
HTTP status code 404

Not Found.

No category exists for the given id.

Body
application/json

Example:

{
  "code": 404,
  "message": "Brand not found",
  "details": "id: 43afe4c7-ffd5-4ccd-a14e-c3f297e34d48"
}

Tags

Tags are pieces of information associated with foods to convey further information about them. For example, an apple and a banana may both be tagged as 'Fresh' and 'Fruit', whilst tinned peaches may be tagged as 'Canned' and 'Fruit'. Each food can have zero or more associated tags, and a tag can be associated with many foods.

FieldTypeDescription
iduuidA UUID identifying the tag
namestringThe name of the tag
/tags get

Returns a collection of all the tags in the CalorieKing database.

Request
Response

Request

Query Parameters
  • classifications: (string)

    Filter tags to those with foods with the specified classifications. This is a comma separated list of classification strings. Classification strings can be enclosed in double quotes to escape commas if necessary. The list may be prepended with a '!' to return tags with foods without the listed classifications.

  • categories: (string)

    Filter tags to those associated with foods in the specified categories. This is a comma separated list of category ids. The list may be prepended with a '!' to invert the filter and return tags associated with foods that are not in any of the specified categories. Non-leaf categories may be included in this filter. In this case, the filter will work on foods contained in any of the leaf categories under the non-leaf category.

    Examples

    Given the following categories, containing foods with the associated tags:

    Top Level CategoryLeaf CategoryFoodTags
    Top1Leaf1Food1A
    Food2B
    Leaf2Food3B
    Food4C
    Top2Leaf3Food5A, B
    Food6C, D
    Leaf4Food7B, C
    Food8D

    Below are the results from some categories filters:

    Categories Filter (where 'CategoryX' represents the id of that category)Resulting Tags
    Top1A, B, C
    Leaf1A, B
    Top1,Leaf4A, B, C, D
    !Leaf1A, B, C, D
    !Leaf1,Leaf3B, C, D
    !Top2,Leaf2A, B
  • brands: (string)

    Filter tags to those associated with foods in the specified brands. This is a comma separated list of brand ids. The list may be prepended with a '!' to invert the filter and return tags associated with foods that are not in any of the specified brands.

    Examples

    Given the following brands, containing foods with the associated tags:

    BrandFoodTags
    Brand1Food1A
    Food2B
    Food3C
    Brand2Food4A, B
    Food5A
    Food6B
    Brand3Food7B, C

    Below are the results from some brands filters:

    Brands Filter (where 'BrandX' represents the id of that brand)Resulting Tags
    Brand1A, B, C
    Brand2A, B
    Brand3B, C
    Brand2,Brand3A, B, C
    !Brand1A, B, C
    !Brand1,Brand2B, C
    !Brand1,Brand3A, B
  • order: one of (asc,desc)

    Results are ordered alphabetically by name. This field indicated whether they are in ascending or descending alphabetical order.

  • query: (string)

    Filter based on this query string. The exact meaning of this string depends on the query-type parameter.

  • query-type: one of (fts,prefix)

    Dictates how the query parameter is interpreted:

    • fts - Search for resources matching the query string using full text search (case insensitive).
    • prefix - Search for resources with names beginning with the query string (case insensitive).
  • fields: (string)

    Selector to specify the fields to include in partial-responses

  • limit: (number)

    The number of results to include in requests when paging

  • offset: (number)

    The index (zero-based) of the first result to return when paging

Responses

HTTP status code 200

OK.

The request succeeded and a collection of tags returned.

Body
application/json

Example:

{
  "metadata": {
    "total": 80,
    "limit": 20,
    "offset": 0
  },
  "tags": [
    {
      "id": "7c132457-2979-48be-90d9-0013884b24cc",
      "name": "Fruit Drinks"
    },
    {
      "id": "71c27b1e-f564-4091-b9c8-ac8f76d25f66",
      "name": "Fruit Juices"
    },
    {
      "id": "cac762fb-a70e-471e-96eb-65dde30e331b",
      "name": "Fruit Smoothies"
    }
  ]
}
HTTP status code 400

Bad Request.

The request is invalid as outlined in the response message. Further information may exist and if so will be listed in the response details.

Body
application/json

Example:

{
  "code": 400,
  "message": "Unknown path in 'fields'",
  "details": "Path: 'region'"
}
HTTP status code 401

Unauthorized.

The request requires user authentication.

Body
application/json

Example:

{
  "code": 401,
  "message": "Not Authorized"
}
/tags/{tagId} get

Returns a specific tag from the CalorieKing database.

Request
Response

Request

URI Parameters
  • tagId: required (string)
Query Parameters

Responses

HTTP status code 200

OK.

The request succeeded and the tag returned.

Body
application/json

Example:

{
  "tag": {
    "id": "796f4200-5527-460c-82c4-ebaeddf57bc9",
    "name": "Bars, Breakfast Cereals"
  }
}
HTTP status code 400

Bad Request.

The request is invalid as outlined in the response message. Further information may exist and if so will be listed in the response details.

Body
application/json

Example:

{
  "code": 400,
  "message": "Unknown path in 'fields'",
  "details": "Path: 'region'"
}
HTTP status code 401

Unauthorized.

The request requires user authentication.

Body
application/json

Example:

{
  "code": 401,
  "message": "Not Authorized"
}
HTTP status code 404

Not Found.

No tag exists for the given id.

Body
application/json

Example:

{
  "code": 404,
  "message": "Tag not found",
  "details": "id: a2da1442-3abc-4606-a442-aba5534db508"
}