Table of contents

Containers API

A Container houses many Items. Harvesting can be initiated on Containers using the Containers API.

Container Object

A Container Object has the following structure:

{
	"id": "something123",
	"location_id": "AVhdTJJguT9afTJxvbUD",
	"version": 34,
	"enabled": true,
	"last_harvested": "2016-09-14T12:19:36.660671975Z",
	"request_id": "57d9405828e65b67d978a8b5be9d272a",
	"harvest_success_count": 26,
	"harvest_failure_count": 0,
	"last_harvested_failure": "0001-01-01T00:00:00Z",
	"groups": []
}
  • id - (string) The ID of this container (unique to the Location)
  • location_id - (string) ID of the location
  • version - (int) Number of times this Container has been harvested
  • enabled - (bool) Whether harvested is enabled for this container or not
  • last_harvested - (timestamp) When the container was last harvested
  • request_id - (string) Optional ID of the request that caused this Container to be harvested
  • harvest_success_count - (int) The number of items that were successfully harvested
  • harvest_failure_count - (int) The number of items where harvesting failed
  • groups - (array) Groups associated with this container (see Users and Groups API).

Reading Containers from a Location

To access the Containers at a Location, you can make the following request:

GET /api/data/locations/{id}/containers?prefix={prefix}&cursor={cursor}
  • {id} - (string) The ID of the Location
  • {prefix} - (string) Optional string prefix; only Containers with the specified prefix will be returned
  • {cursor} - (string) Optional cursor indicating the start of the items to get - must be value of next_cursor from previous request

You will be presented with a page of Container Objects wrapped inside an object that provides some context about the response:

{
	"containers": [
		{container-objects},
		{container-objects},
		{container-objects}
	],
	"prefix": "{prefix}",
	"next_cursor": "{next_cursor}"
}
  • container-objects - (array) List of Container Objects
  • prefix - (string) Optional prefix string used to find this page of Containers
  • next_cursor - (string) The cursor to use to get the next page of results - if empty (""), you have reached the end of the list

Enabling Containers for harvest

Containers that are enabled will be harvested by GrayMeta Platform. This can be toggled using the following API request:

PUT /api/data/containers
{
	"id": "{id}",
	"location_id": "{location_id}",
	"enabled": "{enabled}"
}
  • id - (string) ID of the Container (see Reading Containers from a Location above)
  • location_id - (string) ID of the Location of this Container
  • enabled - (bool) Whether this Container should be harvested or not (true for yes, false for no)

Reading enabled Containers

An enabled Container is one that is actively being harvested by GrayMeta Platform. You can obtain a filtered list with the following API:

GET /api/data/containers/enabled

You will receive an array of enabled Containers:

[
	{container-objects},
	{container-objects},
	{container-objects}
]
  • container-objects - (array) List of Container Objects

Get the name of a Container

This endpoint retrieves the Stow container name for a given container.

GET /api/data/v3/containers/{id}/name
  • id - This is the hash id of the container, not the Stow container id.

Get container name response

{
    "name": "bmp13"
}
  • name (string) The Stow container name

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.