Table of contents

Categories API

Categries are a way of grouping items. They can be added/updated/delete 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.

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",
            "item_ids": [
                "3ab26f33b512d6dde6a217e96d25cdd5"
            ]
        },
        {
            "category": "test-category2",
            "item_ids": [
                "3ab26f33b512d6dde6a217e96d25cdd5"
            ]
        },
        {
            "category": "test-category4",
            "item_ids": [
                "3ab26f33b512d6dde6a217e96d25cdd5"
            ]
        },
        {
            "category": "test-category5",
            "item_ids": [
                "3ab26f33b512d6dde6a217e96d25cdd5"
            ]
        }
    ]
}

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

{
    "items": [
        {
            "id": "3ab26f33b512d6dde6a217e96d25cdd5",
            "location_id": "5cddc9b7a860dce2342ea6d2a384c572",
            "container_id": "e71a6095271bc669aca8e4505df9606e",
            "gm_item_type": "video",
            "file_size": 14766799,
            "etag": "2019-01-24 21:11:51 +0000 UTC",
            "file_extension": "mp4",
            "path": "",
            "file_path": "",
            "folder_path": "",
            "hash_c4id": "c43wV1a5AC935ds1uQkUDDqYeYCTKt6UWyvUxCUGTVm28DXpq6pBVVUxoNNjGh8Mb2haBCH6zGNwhMCiiNV5eDgPth",
            "hash_md5": "aacee17554886486bcad19cbd1a0c861",
            "hash_sha1": "a4fbeaf374fbfb517dedadd78c46e7bb509b784f",
            "hash_sha512": "7eb1631d45f4c547a913876cf874df7f270585d6c6199c55a156d648588bb06c0fe9b2404447bf034cb0c45f4bdbd08501b0a2945185f4ae4f76e635ef269612",
            "harvester_version": "dev",
            "last_harvested": "2019-05-16T20:47:11.083064Z",
            "last_modified": "2019-01-24T21:11:51Z",
            "location_kind": "local",
            "location_name": "local",
            "mime_type": "video/mp4",
            "mime_category": "video",
            "name": "kim.mp4",
            "parent_id": "",
            "root_id": "3ab26f33b512d6dde6a217e96d25cdd5",
            "shared_link": "",
            "stow_container_id": "/data/videos",
            "stow_container_name": "",
            "stow_url": "file:///data/videos/kim.mp4",
            "thumbnail": {
                "path": "thumbnailer/sprite.jpg",
                "type": "sprite",
                "frame_count": 30,
                "height": 152,
                "width": 270
            },
            "segment_interval": 2,
            "drm": false,
            "created_at": "2019-05-16T20:47:11.182964Z",
            "updated_at": "2019-05-16T20:47:11.182964Z",
            "in_progress": false,
            "categories": [
                "cat1",
                "cat3"
            ]
        }
    ],
    "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.