Micrio Knowledge Base

Appearance

Server API reference v2 Enterprise ​

This page is for the Server API connected to the Micrio Dashboard version 3. Use the links below to navigate to alternative versions.

INFO

This feature is available for Enterprise subscription accounts only.

With an Enterprise Micrio subscription, you can request an API Key and server endpoint from us, which you can then use to connect to our processing servers directly, allowing you to add or migrate images into the Micrio platform.

Use cases ​

If you have your own current CMS or digital asset mananagement system, it's possible to link those to the Micrio servers. This will allow the automatic adding and processing of your uploads into the Micrio ecosystem.

This can be done for single images, or for (large) batch operations, in the case of fully migrating existing image collections to Micrio.

TIP

If you have large (> 5,000) image collections that you want to add to Micrio at once, please let us know in advance, so we can scale up our processing servers temporarily, allowing for a quicker migration process.

Setting up your API Keys ​

If you would like to have server access, Contact us to have this set up. You will receive an API Key (uuid format), and API Endpoint URLs which you can use.

The API ​

Adding one or multiple images ​

To add images to Micrio, it is necessary that you provide Micrio with a URL of the original asset, which is accessible by our servers.

You can use the API call /v2/images/add to add an image to your account.

This is a POST call, which expects the following values as JSON body:

ts
{
	/** Your organisation uuid */
	organisationId: uuid;
	/** Your organisation's API Key */
	apiKey: uuid;
	/** Images to be added */
	images : {
		/** The image name / your ID, defaults to url filename */
		name?: string;
		/** The original image source url */
		sourceUrl: string;
	}[];
	/** The folder ID to put the images in (6 chars) */
	folderId: string;
	/** User email, defaults to tiler@micr.io */
	userEmail?: string;
}

This will add your images to the processing queue, and you will be able to check the tiling status.

The response result is an array of Micrio images of the same order as the input:

ts
{
	result: {
		images: {
			/** The Micrio ID */
			id: string;
			/** Image name / your ID */
			name: string;
			/** Processing status */
			status: ( 'queued' | 'downloading' | 'processing' | 'tiling' | 'storing' | 'ready' | 'error' )
		}[]
	}
}

Requesting image status ​

You can use the /v2/image/status API call to request the processing status of individual images.

This is a POST call, which expects the following parameters:

ts
{
	/** Organisation ID */
	organisationId: uuid;
	/** API Key */
	apiKey: uuid;
	/** Image IDs to request status -- max 100 */
	imageIds : string[];
}

This will return the following object, where result is an array of images:

ts
{
	result: {
		images: {
			/** Micrio ID */
			id: string;
			/** Image name / your ID */
			name: string;
			/** Processing status */
			status: ( 'queued' | 'downloading' | 'processing' | 'tiling' | 'storing' | 'ready' | 'error' );
			/** If error, error message */
			error?: ( 'originalNotFound' | 'invalidImage' | 'uploadError' | 'statusUpdateError' | 'unknown' );
			/** Image width, if available */
			width?: number;
			/** Image width, if available */
			height?: number;
			/** Image thumbnail URL, available when status == 'ready' */
			thumbnail?: string;
		}[]
	}
}

Once an image has status as ready, you can immediately use the id ID to embed the Micrio image into your site, or use the thumbnail to show in your own environment.

Requesting batch processing progress ​

If you have a large migration running, you can also request the amount of images done in the entire batch for a quick global overview of the progress. For this you can use the /v2/folder/status call, which will return statistics on the current tiling process for the entire folder.

The required arguments:

ts
{
	/** Organisation ID */
	organisationId: uuid;
	/** API Key */
	apiKey: uuid;
	/** Target folder ID */
	folderId : string;
}

This returns:

ts
{
	result: {
		/** Number of total images in this folder */
		numTotal:number;
		/** Number of images which are available */
		numComplete: number;
		/** IDs of images still queued or are being processed */
		processingIds: string[];
		/** Errored IDs */
		erroredIds: string[];
	}
}

Creating a folder, album or 360 tour container ​

You can use /v2/folder/create to create subfolders, albums, and 360 tour container (spaces).

The required arguments:

ts
{
	/** Organisation ID */
	organisationId: uuid;
	/** API Key */
	apiKey: uuid;
	/** Parent folder ID */
	parentId: string;
	/** (optional) Folder name, defaults to type of the folder */
	name?: string;
	/** (optional) Folder type, defaults to 'folder' */
	type?: ('folder'|'album'|'space');
}

This returns:

ts
{
	result: {
		/** The ID of the newly created folder */
		id: string;
	}
}

Bespoke wishes ​

If you have specific needs to connect your existing system to Micrio, please do not hesitate to contact us. We are open to any ideas and can offer bespoke work to your requirements.

Processing time ​

Depending on the image size, processing time varies. For medium-sized images (<= 250MPix), this will be quick, and our servers will take less than 10 seconds per image.

For very large, or layered images (which is not recommended, see this article), tiling could take longer, up to 5-10 minutes.

If you have extremely large images (> 5GB), please contact us, so we can connect you to our heavy-duty tiling servers, which are specialized for these images.

CLI Micrio tiler app ​

Alternatively, if you want to use your own servers for processing your Micrio uploads, you can use the Micrio CLI tool NodeJS package.