Categories API in Wasabi AiR

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

Category Object

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

Setting Categories for an Item

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

• {id} - (string) The ID of the item to set categories.
• categories - ([]string) An array of category names to set on an item.

Response

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

Response codes:

• StatusCreated (201) - The category deleted successfully.
• StatusNotFound (404) - No category was found by the specified ID.
• StatusUnprocessableEntity (422) - The request is missing the category id.
• StatusInternalServerError (500) - An unexpected error.

Listing Categories for an Item

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

• {id} - (string) The ID of the item to list categories.

Response

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

Response codes:

• StatusOK (200) - The category listed successfully.
• StatusBadRequest (400) - The request was missing the item id.
• StatusInternalServerError (500) - An unexpected error.

Updating Categories for an Item

This endpoint merges previous categories with additional categories for an item.

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

• {id} - (string) The ID of the item to set categories.
• categories - ([]string) An array of category names to set on the item.

Response

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

Response codes:

• StatusCreated (201) - The category was deleted successfully.
• StatusNotFound (404) - No category was found by the specified ID.
• StatusUnprocessableEntity (422) - The request was missing the category id.
• StatusInternalServerError (500) - An unexpected error.

Searching Categories

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

• {query} - (string) The search term for category names.

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
        }
    ]
}

Response codes:

• StatusOK (200) - The category listed successfully.
• StatusInternalServerError (500) - An unexpected error.

Category Items

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

• {category_name} - (string) The name of the category for which to get items.

Query Parameters

• limit (default: 10, min: 1, max: 100)
• offset

Response

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

Deleting a Category for an Item by Name

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

• {id} - (string) The ID of the item to set categories.
• {name} - (string) The name of the category to be deleted.

Response

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

Response codes:

• StatusAccepted (200) - The category deleted successfully.
• StatusBadRequest (400) - The request was missing the item id or category name.
• StatusInternalServerError (500) - An unexpected error.

Adding Categories in Bulk to Multiple Items

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

• items - ([]string) A list of item IDs on which to add categories.
• categories - ([]string) An array of category names to add to the items.

Response

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

Response codes:

• StatusCreated (200) - OK. Check failures in the 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) - An unexpected error.

Removing Categories in Bulk From Multiple Items

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

• items - ([]string) A list of item IDs on which to remove categories.
• categories - ([]string) An array of category names to remove from the items.

Response

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

Response codes:

• StatusCreated (200) - OK. Check failures in the 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) - An unexpected error.