Get concepts

GET 
/platform/v1/:project-id/concepts

This endpoint retrieves all concepts in your ontology (categories, attributes, and text values).

You can filter the results by idName and/or concept type:

• CATEGORY
• NUMERIC_ATTRIBUTE
• TEXT_ATTRIBUTE
• BOOLEAN_ATTRIBUTE
• UNTYPED_ATTRIBUTE
• DATE_ATTRIBUTE

About idName

The idName is the unique identifier for a concept. It must come from your own system (not generated by Data Platform), and it stays the same for the lifetime of that concept.

Data Platform uses the idName to match incoming concepts to existing ones. When you send a concept, Data Platform checks whether a concept with that idName already exists:

• If it exists, the concept is updated.
• If it doesn't, a new concept is created.

Because of this, the idName is what keeps your ontology consistent across updates. Reusing the same idName for the same real-world concept prevents duplicates, and sending a new idName always creates a new concept.

Naming rules to follow before creating concepts

• Value concepts must follow the pattern <parent conceptIdName>_#_<value conceptIdName>. For example, a LEATHER value under the MATERIAL attribute must have the idName MATERIAL_#_LEATHER, not just LEATHER.
• idNames must always be UPPERCASE. idNames are case-sensitive, but the extraction patterns used to match them are case-insensitive. Mixing cases (e.g. Material vs MATERIAL) can therefore cause extraction to match the wrong concept or create unexpected duplicate concepts.

Request

Responses

200

{
  "concepts": [
    {
      "idName": "ROOT/Gift",
      "type": "CATEGORY",
      "localization": {
        "en": {
          "name": "Gift",
          "synonyms": [
            "gifts"
          ],
          "extractionRules": [
            {
              "type": "IS",
              "text": [
                {
                  "type": "MATCH",
                  "text": "root gift"
                }
              ]
            }
          ]
        }
      },
      "children": [
        {
          "idName": "ROOT/Gift/Gifts up to 200 euros",
          "type": "CATEGORY",
          "localization": {
            "en": {
              "name": "Gifts up to 200 euros",
              "extractionRules": [
                {
                  "type": "IS",
                  "text": [
                    {
                      "type": "MATCH",
                      "text": "root gift gifts up to 200 euros"
                    }
                  ]
                }
              ]
            }
          },
          "children": [
            {
              "idName": "ROOT/Gift/Gifts up to 200 euros/Games",
              "type": "CATEGORY",
              "localization": {
                "en": {
                  "name": "Games",
                  "synonyms": [
                    "game"
                  ],
                  "extractionRules": [
                    {
                      "type": "IS",
                      "text": [
                        {
                          "type": "MATCH",
                          "text": "root gift gifts up to 200 euros games"
                        }
                      ]
                    }
                  ]
                }
              },
              "structuredViewData": {
                "url": {
                  "link": ""
                }
              }
            }
          ]
        }
      ]
    },
    {
      "idName": "Bestseller",
      "type": "BOOLEAN_ATTRIBUTE",
      "localization": {
        "en": {
          "name": "Bestseller",
          "trueState": "yes",
          "falseState": "no",
          "extractionRules": [
            {
              "type": "IS",
              "text": [
                {
                  "type": "MATCH",
                  "text": "bestseller"
                }
              ]
            }
          ]
        }
      },
      "structuredViewData": {}
    },
    {
      "idName": "BRAND",
      "type": "TEXT_ATTRIBUTE",
      "localization": {
        "en": {
          "name": "Brand",
          "extractionRules": [
            {
              "type": "IS",
              "text": [
                {
                  "type": "MATCH",
                  "text": "brand"
                }
              ]
            }
          ]
        }
      },
      "children": [
        {
          "idName": "BRAND_#_BRANDA",
          "type": "TEXT_VALUE",
          "localization": {
            "en": {
              "name": "BrandA",
              "extractionRules": [
                {
                  "type": "IS",
                  "text": [
                    {
                      "type": "MATCH",
                      "text": "branda"
                    }
                  ]
                }
              ]
            }
          },
          "structuredViewData": {}
        },
        {
          "idName": "BRAND_#_BRANDB",
          "type": "TEXT_VALUE",
          "localization": {
            "en": {
              "name": "BrandB",
              "extractionRules": [
                {
                  "type": "IS",
                  "text": [
                    {
                      "type": "MATCH",
                      "text": "brandb"
                    }
                  ]
                }
              ]
            }
          },
          "structuredViewData": {}
        }
      ]
    },
    {
      "idName": "COLOR",
      "type": "TEXT_ATTRIBUTE",
      "localization": {
        "en": {
          "name": "Colour",
          "extractionRules": [
            {
              "type": "IS",
              "text": [
                {
                  "type": "MATCH",
                  "text": "colour"
                }
              ]
            }
          ]
        },
        "en-US": {
          "name": "Color"
        }
      },
      "structuredViewData": {}
    },
    {
      "idName": "DESCRIPTION",
      "type": "UNTYPED_ATTRIBUTE",
      "localization": {
        "en": {
          "name": "Description",
          "extractionRules": [
            {
              "type": "IS",
              "text": [
                {
                  "type": "MATCH",
                  "text": "description"
                }
              ]
            }
          ]
        }
      },
      "structuredViewData": {}
    },
    {
      "idName": "PRICE",
      "type": "NUMERIC_ATTRIBUTE",
      "localization": {
        "en": {
          "name": "Price",
          "unitName": "$",
          "extractionRules": [
            {
              "type": "IS",
              "text": [
                {
                  "type": "MATCH",
                  "text": "price"
                }
              ]
            }
          ]
        },
        "en-GB": {
          "unitName": "£"
        }
      },
      "structuredViewData": {}
    }
  ]
}

Response Headers

content-type:application-json

400

{
    "status": "failure",
    "code": 400,
    "message": "Invalid query parameter. A json array is expected."
}