Table of contents

Items API

Once harvesting has begun, you will be able to access the item data using the Items API.

Item Object

The data that makes up an Item is outlined in the Item Object documentation.

Getting all metadata

To get all metadata of an item by its ID, you make the following request:

GET /api/data/items/{id}
  • {id} - (string) ID of the Item to get
  • Do not include the only parameter

The response will be a JSON document containing ALL metadata for the item.

Get the metadata.json file for an item

GET /files/{item_id}/metadata2.json

The response will be a JSON document containing the same data as the metadata.json file.

Selective data

The Items API allows you to be selective about what data you get. You may:

  • Use only parameter to get specific leaf fields, or
  • Use the include parameter to specify root objects to include

You cannot use both only and include parameters at the same time.

Getting specific leaf fields

To get only a list of specific fields, you may specify them using the only parameter.

GET /api/data/items/{id}?only=field1,field2,field3
  • field1,field2,field3 - (comma separated list) List of fields to include
  • Only leaf fields are supported, so you must know the full path to the fields to get
  • If you need to get entire groups of data, consider using the include parameter
  • This endpoint is extremely efficient and is preferred over include
  • For a complete list of acceptable fields, perform a GET request without any parameters to see the entire data payload

Getting specific groups of data

You can get groups of data at a time using the include parameter.

GET /api/data/items/{id}?include=obj1,obj2,obj3
  • obj1,obj2,obj3 - (comma separated list) List of fields to include
  • Only root fields are supported. If you wish to get only fields from within objects, use the only parameter instead
  • This endpoint is not as efficient as using the only parameter but is more convenient
  • For a complete list of acceptable fields, see the Item Object documentation

Large data

Some data is considered too large to go into the main item API, and such data is not returned unless you explicitly ask for it.

Speech to text

summary.speech_to_text data can be obtained by using the only parameter:

GET /api/data/items/{id}?only=summary.speech_to_text

speech_to_text data can be edited with

PUT | DELETE /api/data/items/{id}/speech_to_text
[
	{
		"source": "speech to text source",
		"transcript": [
			{
				"start_at": 0.5,
				"end_at": 4.5,
				"text": "edited text / text to delete"
			},
			...
		]
	},
	...
]

PUT will replace the speech to text lines, and DELETE will remove them.

Categories

An item could be associated with one or many categories. One can associate an item with categories using

POST /api/data/items/{id}/categories
{
	"categories": ["cat1", "cat2"]
}

To disassociate categories from an Item use

DELETE /api/data/items/{id}/categories/{categories}

where {categories} is a url-encoded, comma separated list of categories e.g. cat1,other%20category

Identifying items

To determine the GrayMeta Platform ID and Stow URL for an item, you need to know the location ID, container ID and the identifier for the item itself within the container. For more information about item IDs, see the Stow project.

You can make the following request:

POST /api/control/item-id
{
	"location_id": "abc123",
	"container_id": "MyContainer",
	"item_id": "MyItem"
}
  • location_id - (string) The GrayMeta Platform location ID that indicates which storage location the item is in
  • container_id - (string) The container ID where the item is (usually bucket name)
  • item_id - (string) The identifier of the item (usually its name within the storage)

Provided the location, container and item values are all valid, you will be given the following response:

{
	"stow_url": "s3://unique/url/to/item",
	"gm_item_id": "67779468b22af637e2dd6a2616264b6c"
}
  • stow_url - (string) The Stow URL for the item
  • gm_item_id - (string) The internal GrayMeta Platform ID for this item

It is not necessary for the item to have been harvested in order for the ID to be returned, but once harvested you can trust that the ID will match the gm_item_id returned.

Once you have obtained the identifiers for an item, you can use them in the Harvest API.

Item Descriptions

Get descriptions for an item

GET /api/data/v3/items/{id}/descriptions?page-token={page_token}&limit={limit}&offset={offset}
  • page_token is the next page token provided to page the results.
  • limit is the limit to the number of records returned.
  • offset is the offset to start from for the records to be returned.

If none are set, the full collection will be returned without pagination. A valid page_token can be used without the addition of limit and offset. Using limit to establish the page size is encouraged. Offset is for getting very specific for that first page of results. After that first page of results use the next page token returned to request more pages.

Response

A successful call will return a Status OK (200) with the following response body:

{
	"next_page_token": string,
	"descriptions": [
		{
			"id": string,
			"item_id": string,
			"segment_index": float64,
			"image_index": int,
			"metadata_id": string,
			"metadata_type": ENUM["item"|"segment"|"image"],
			"confidence": float64,
			"language": string,
			"language_confidence": float64,
			"source": string,
			"text": string,
			"thumbnail": string,
			"thumbnail_width": int,
			"thumbnail_height": int,
			"created_at": zulu timestamp,
			"updated_at": zulu timestamp
		}
		...
	]
}

The next page token will provide a stringified token that can be used to retrieve the next page of results. If the next page token is an empty string, then there are no more results.

If any unexpected errors happen in the process of fulfilling this req/response cycle a Status Internal Server Error (500) will be returned.

Curate a description for an item

To create a curated description you can post to the endpoint below with a valid request body.

POST รง
{
	"segment_index": float64,
	"image_index": int,
	"text": string
}
  • text must not be an empty string

Response

A successful call will return a Status Create (201) with the following response body that includes the related metadata data associated with that segment/image index:

{
	"description": {
		"id": string,
		"item_id": string,
		"segment_index": float64,
		"image_index": int,
		"metadata_id": string,
		"metadata_type": ENUM["item"|"segment"|"image"],
		"confidence": float64,
		"language": string,
		"language_confidence": float64,
		"source": "user",
		"text": string,
		"thumbnail": string,
		"thumbnail_width": int,
		"thumbnail_height": int,
		"created_at": zulu timestamp,
		"updated_at": zulu timestamp
	}
}

If there is a conflict with the segment and/or image index, you’ll recieve a Status Unprocessable Entity (422). If any unexpected errors happend in the process of fulfilling this req/response cycle a Status Internal Server Error (500) will be returned.

Edit a description

To edit an existing descriptions text use the following request:

PATCH /api/data/v3/items/{id}/descriptions/{desc_id}
{
	"text": string
}
  • id is the item id
  • desc_id is the description id
  • text must not be an empty string

Response

A successful call with return a Status OK (200) with the new description after updating.

{
	"description": {
		"id": string,
		"item_id": string,
		"segment_index": float64,
		"image_index": int,
		"metadata_id": string,
		"metadata_type": ENUM["item"|"segment"|"image"],
		"confidence": float64,
		"language": string,
		"language_confidence": float64,
		"source": string,
		"text": string,
		"thumbnail": string,
		"thumbnail_width": int,
		"thumbnail_height": int,
		"created_at": zulu timestamp,
		"updated_at": zulu timestamp
	}
}

If the description by the desc id is not found, you’ll receive a Status Not Found (404). If any unexpected errors happend in the process of fulfilling this req/response cycle a Status Internal Server Error (500) will be returned.

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.