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.

Response

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

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.

Response

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

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.

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

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.

Query Parameters:

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

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",
            "thumbnail_type": "sprite",
            "thumbnail_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": ""
}

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.

Response

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

Codes

  • StatusAccepted (200) - Category successfully deleted.
  • StatusBadRequest (400) - Request missing item id or category name.
  • 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.