Micrio Knowledge Base

Appearance

Server API reference v1 Enterprise ​

This page is for the Server API connected to the Micrio Dashboard version 2. 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 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 an image ​

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

Adding one or multiple images ​

You can use the API call NewImage to add an image to your account.

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

{
  Guid apiKey: [your provided organisation API key],
  Guid userId: [a userId which has access to your organisation],
  string[] imageURL: [An array of Micrio-accessible original image URLs],
  string[] customID: [An optional array of internal IDs for each image in the URLs],
  string folderShortId: [The containing folder in Micrio where the images will be placed]
}

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

The result depends on whether you have added a single image, or a batch of images.

In case of a single image, the ImageStatus is returned, detailed in the next section.

Requesting single image status ​

You can use the GetStatus API call to request the processing status of an individual image.

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

{
  Guid apiKey: [your provided organisation API key],
  Guid userId: [a userId which has access to your organisation],
}

And one of the following:

{
   Guid ImageId: [the image GUID as assigned by Micrio],
   string ImageShortId: [the Micrio image Short ID for client-facing embedding]
   string ImageCustomId: [your custom image ID]
}

NOTE

To be able to use ImageCustomId as query parameter, your organisation first needs to have unique custom IDs enabled. Please contact us to set this up for you.

This will return the following object:

{
       Guid id: [the micrio image GUID],
       string customId: [your input custom ID],
       string shortId: [the micrio image ID for client-facing embedding],
       boolean isFinished: [current tiling status],
       boolean hasError: [boolean if something went wrong during processing],
       string errorMessage: [the error message in case something went wrong]
}

Once an image has IsFinished as true, you can immediately use the shortId ID to embed the Micrio image into your site.

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 GetFolderStatus call, which will return statistics on the current tiling process for the entire folder.

The required arguments:

{
  Guid apiKey: [your provided organisation API key],
  string folderShortId: [The folder in Micrio to query]
}

Removing an image ​

To remove an image, you can do a POST call to the RemoveImage API endpoint, with the following arguments:

{
  Guid apiKey: [your provided API key],
  string imageShortId: [The image short ID to delete],
}

This is a direct action, and will immediately unpublish an image, making it no longer publicly available.

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.