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": [
                "304cdd978474e4a1148abe1137d05164"
            ]
        },
        {
            "category": "test-category2",
            "item_ids": [
                "304cdd978474e4a1148abe1137d05164"
            ]
        },
        {
            "category": "test-category4",
            "item_ids": [
                "304cdd978474e4a1148abe1137d05164"
            ]
        },
        {
            "category": "test-category5",
            "item_ids": [
                "304cdd978474e4a1148abe1137d05164"
            ]
        }
    ],
    "items": [
        {
            "id": "304cdd978474e4a1148abe1137d05164",
            "location_id": "5cd0875a239257ddeb081bc15318946b",
            "container_id": "10bcc160be7f54f8259bce1cb1e26bb9",
            "gm_item_type": "image/raster",
            "file_size": 367996,
            "etag": "2018-11-13 17:24:03 +0000 UTC",
            "file_extension": "jpg",
            "path": "",
            "file_path": "",
            "folder_path": "",
            "hash_c4id": "c44jtETpmTMtH2vHWbR5HbYMFPFFcUndrZukwBPd3fWkr1s4WkRn2mRNUgok83qhCzkRVYPUL4rBU1JYTtXTcEFdvZ",
            "hash_md5": "093350a1e14bda77a328982ecd12af9e",
            "hash_sha1": "621c338207cc5f7b558a59c0272cb625453a69e1",
            "hash_sha512": "a5fc2407e9a590d78213c6b6a5350422a658202d0179d935f619b03866c0e0b0c11a9a6ed6fbccfc72acdfeae010e2392ed918019678fdb6aa2e5b252ce87813",
            "harvester_version": "dev",
            "last_harvested": "2019-05-06T19:13:45.674284Z",
            "last_modified": "2018-11-13T17:24:03Z",
            "location_kind": "local",
            "location_name": "local",
            "mime_type": "image/jpeg",
            "mime_category": "image",
            "name": "IMG_1026.jpg",
            "parent_id": "",
            "root_id": "304cdd978474e4a1148abe1137d05164",
            "shared_link": "",
            "stow_container_id": "/data/me",
            "stow_container_name": "",
            "stow_url": "file:///data/me/IMG_1026.jpg",
            "thumbnail_path": "thumbnailer/thumb.jpg",
            "thumbnail_type": "image",
            "thumbnail_width": 1600,
            "segment_interval": 0,
            "drm": false,
            "created_at": "2019-05-06T19:13:45.73937Z",
            "updated_at": "2019-05-06T19:13:45.73937Z",
            "in_progress": false
        }
    ]
}

Codes

  • StatusOK (200) - Category successfully listed.
  • 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.