Categories API

Categories are a way of grouping items. They can be added/updated/deleted through the Categories APIs.

Category Object

{
    "item_id": string,
    "category": string
}

Set Categories on an Item

PUT /api/data/v3/items/{id}/categories
{
    "categories": ["cat1", "cat2", "cat3", ...]
}

{id} - (string) ID of Item to set categories.
categories - ([]string) Array of category names to set on Item.

Set Categories Response

{
    "categories": [
        "cat1",
        "cat2",
        "cat3"
    ]
}

Set Categories Response Codes

StatusCreated (201) - Category successfully deleted.
StatusNotFound (404) - No category found by speficied ID.
StatusUnprocessableEntity (422) - Request missing category id.
StatusInternalServerError (500) - Unexpected error.

List Categories for an Item

GET /api/data/v3/items/{id}/categories

{id} - (string) ID of Item to list categories.

List Categories Response

{
    "categories": [
        "cat1",
        "cat2",
        "cat3"
    ]
}

List Categories Response Codes

StatusOK (200) - Category successfully listed.
StatusBadRequest (400) - Request missing item id.
StatusInternalServerError (500) - Unexpected error.

Update Categories on an Item

This endpoint will merge previous categories with additional categories for an item.

PATCH /api/data/v3/items/{id}/categories
{
    "categories": ["cat1", "cat2", "cat3", ...]
}

{id} - (string) ID of Item to set categories.
categories - ([]string) Array of category names to set on Item.

Update Categories Response

{
    "categories": [
        "cat1",
        "cat2",
        "cat3"
    ]
}

Update Categories Response Codes

StatusCreated (201) - Category successfully deleted.
StatusNotFound (404) - No category found by speficied ID.
StatusUnprocessableEntity (422) - Request missing category id.
StatusInternalServerError (500) - Unexpected error.

Search Categories

GET /api/data/v3/search/categories?q={query}

{query} - (string) Search term for category names.

Note: an empty {query} will return all categories.

Search Categories Response

{
    "categories": [
        {
            "category": "test-category1",
            "num_items": 23
        },
        {
            "category": "test-category2",
            "num_items": 39
        },
        {
            "category": "test-category4",
            "num_items": 12
        },
        {
            "category": "test-category5",
            "num_items": 90
        }
    ]
}

Search Categories Response Codes

StatusOK (200) - Category successfully listed.
StatusInternalServerError (500) - Unexpected error.

Category Items

GET /api/data/v3/search/categories/{category_name}/items

{category_name} - (string) Name of the cateogry to get items for.

Note: an empty {query} will return all categories.

Category Items Query Parameters

limit
- Min: 1
- Max: 100
- Default: 10
offset

Category Items Response

{
    "item_ids": [
      "3ab26f33b512d6dde6a217e96d25cdd5",
      "7e6f0e66e3e8113779b862da7e29cf27",
      "96815bc027bed98a643b2fbcfe2a4685"
    ],
    "next_page_token": ""
}

Category Items Response Codes

StatusOK (200) - Category successfully listed.
StatusNotFound (404) - Category not found.
StatusInternalServerError (500) - Unexpected error.

Delete Category on an Item, by Name

DELETE /api/data/v3/item/{id}/categories/{name}

{id} - (string) ID of Item to set categories.
{name} - (string) Name of category to be deleted.

Delete Category Response

{
    "categories": [
        "cat1",
        "cat3"
    ]
}

Delete Category Response Codes

StatusAccepted (200) - Category successfully deleted.
StatusBadRequest (400) - Request missing item id or category name.
StatusInternalServerError (500) - Unexpected error.

Add Categories in Bulk to Multiple Items

POST /api/data/v3/categories/bulk
{
    "items": ["item1", "item2"],
    "categories": ["cat1", "cat2", "cat3", ...]
}

items - ([]string) list of item ids on which to add categories.
categories - ([]string) Array of category names to add to the items.

Bulk Add Response

{
    "successes": [
        {
            "item_id": "item1",
            "categories": [
                "foo",
                "cat1",
                "cat2",
                "cat3"
            ]
        }
    ],
    "failures": [
        {
            "item_id": "item2",
            "error": "some error"
        }
    ]
}

Bulk Add Response Codes

StatusCreated (200) - OK. Check failures in response for any individual failures.
StatusUnprocessableEntity (403) - Attempting to access one or more items to which you do not have access.
StatusUnprocessableEntity (422) - Bad input data.
StatusInternalServerError (500) - Unexpected error.

Remove Categories in Bulk from Multiple Items

DELETE /api/data/v3/categories/bulk
{
    "items": ["item1", "item2"],
    "categories": ["cat1", "cat2", "cat3", ...]
}

items - ([]string) list of item ids on which to remove categories.
categories - ([]string) Array of category names to remove from the items.

Bulk Remove Response

{
    "successes": [
        {
            "item_id": "item1",
            "categories": [
                "foo"
            ]
        }
    ],
    "failures": [
        {
            "item_id": "item2",
            "error": "some error"
        }
    ]
}

Bulk Remove Response Codes

StatusCreated (200) - OK. Check failures in response for any individual failures.
StatusUnprocessableEntity (403) - Attempting to access one or more items to which you do not have access.
StatusUnprocessableEntity (422) - Bad input data.
StatusInternalServerError (500) - Unexpected error.

This documentation is generated from the latest version of GrayMeta Platform. For documentation relevant to your own deployed version, please use the documentation inside the application.

Table of contents