Skip to content

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 enable external API access for your organisation. Once enabled, group administrators can self-manage their keys directly from the dashboard:

  • Open the dashboard's Settings tab and scroll to the API keys section -- see Group settings & users for the full walkthrough.
  • You can create multiple keys per organisation (one per integration is recommended), give each one a name and an optional ending date, and revoke keys individually at any time.
  • A newly created key is shown only once in plaintext; we only store a hash. Make sure to copy it into your secret manager immediately.
  • Each authenticating request keeps the key's lastUsed timestamp up to date so you can spot stale or unused keys.

Both newly created keys and any pre-existing legacy key (migrated from the previous single-key model) work with the same apiKey field below; the API does not distinguish between them.

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/image/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;
		/** Provide your own custom ID to this image. See below for remarks. */
		customId?: 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 customId field

Using the customId field for images, you can provide your own Custom IDs, which you can use instead of the Micrio-provided IDs.

Use this in the <micr-io> viewer embed by using the attribute id="external/{your-group-slug}/{your-custom-image-id}, for example <micr-io id="external/my-group/image0001"></micr-io>.

However, this field can only be used when your organisation supports it. To request this functionality, please contact us.

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.

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[];
	/** When supported by your organisation, an array of custom Image IDs -- max 100 */
	imageCustomIds : 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.

Deleting images ​

To soft-delete one or more images, use the /v2/image/delete API call. Deleted images will no longer be publicly available or returned in other API calls.

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

ts
{
	/** Organisation ID */
	organisationId: uuid;
	/** API Key */
	apiKey: uuid;
	/** Image IDs to delete -- max 100 */
	imageIds?: string[];
	/** When supported by your organisation, an array of custom Image IDs -- max 100 */
	imageCustomIds?: string[];
}

You must provide at least one of imageIds or imageCustomIds, or both. The combined total may not exceed 100.

This returns the deleted images:

ts
{
	result: {
		images: {
			/** Micrio ID */
			id: string;
			/** Custom ID, if set */
			customId?: string;
		}[]
	}
}

If no matching (non-deleted) images are found, a 404 error is returned.

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;
	}
}

Adding a PDF as an album ​

PDF files are added as image albums with /v2/album/add. This is a POST call which expects:

ts
{
	/** Organisation ID */
	organisationId: uuid;
	/** API Key */
	apiKey: uuid;
	/** Required; currently only 'pdf' is supported */
	type: 'pdf';
	/** Publicly reachable HTTPS URL of the PDF */
	sourceUrl: string;
	/** Project or folder ID to create the album in */
	parentId: string;
	/** (optional) Album name, defaults to the source filename */
	name?: string;
	/** (optional) Uploader email, defaults to the external tiler user */
	userEmail?: string;
}

The destination is validated before anything is created. Adding an album inside another album, or inside a 360 tour container, returns a 400 error without creating the album.

The response uses the same shape as /v2/album/status, with a single album in result.albums:

ts
{
	result: {
		albums: {
			/** The album/folder ID */
			id: string;
			/** Album name */
			name: string;
			/** Processing status */
			status: ('notstarted' | 'queued' | 'downloading' | 'processing' | 'tiling' | 'storing' | 'resizing' | 'ready' | 'error');
			/** Number of pages/images, 0 until page records exist */
			numTotal: number;
			/** Number of pages/images which are ready */
			numComplete: number;
			/** Micrio ID of the first page, only when fully complete */
			firstImageId?: string;
			/** Deep link to this album in the Micrio Dashboard */
			dashboardUrl: string;
			/** Human-readable error, when status is 'error' */
			error?: string;
		}[];
	}
}

The individual page Micrio IDs are generated during tiling, so the creation response cannot include them yet. Use /v2/album/status to follow progress. When the status is ready, firstImageId contains the Micrio ID of the first page. You can use that ID to embed the album in the viewer:

html
<micr-io id="FIRST_IMAGE_ID"></micr-io>

Requesting album status ​

/v2/album/status works for any album, including albums created manually in the dashboard. It is a POST call which expects:

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

Every requested ID must be an album in your organisation. If any ID is not a real album, belongs to another organisation, or is a folder, the call returns a 403 error listing those IDs.

This returns the same result.albums array as above:

ts
{
	result: {
		albums: {
			id: string;
			name: string;
			status: ('notstarted' | 'queued' | 'downloading' | 'processing' | 'tiling' | 'storing' | 'resizing' | 'ready' | 'error');
			numTotal: number;
			numComplete: number;
			firstImageId?: string;
			dashboardUrl: string;
			error?: string;
		}[];
	}
}

Status is derived entirely from the images in the album:

  • numTotal counts the album's pages/images and is 0 until page records exist.
  • numComplete counts pages/images with status ready.
  • If any page failed, status is error and error describes how many pages could not be processed.
  • firstImageId is only returned when all pages are ready.
  • An album with no pages reports notstarted with numTotal: 0.
  • A PDF that fails before any page can be created (for example an invalid or unreadable file) leaves the album without pages, so it also reports notstarted with numTotal: 0. Delete it with /v2/album/delete if needed.

Deleting albums ​

/v2/album/delete soft-deletes albums and all images inside them. This works for PDF albums and manually created albums.

ts
{
	/** Organisation ID */
	organisationId: uuid;
	/** API Key */
	apiKey: uuid;
	/** Album IDs to delete -- max 100 */
	albumIds: string[];
}

All IDs must be albums in your organisation. If any ID is invalid, the call returns a 404 error and deletes nothing. The error message lists the offending IDs, for example: No matching albums found or not part of group: abc12, xyz98.

This returns the deleted albums:

ts
{
	result: {
		albums: {
			/** The album/folder ID */
			id: string;
			/** Album name */
			name: string;
		}[];
	}
}

Deleted albums and images are no longer available through the public viewer or other API calls. This API only marks records as deleted; it does not immediately purge storage.

INFO

Only albums created in Dashboard version 3 (Cloudflare-native, non-legacy albums) are addressable through these calls.

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.