API Reference

Authentication

There are two types of authentication used in the Icefiery API:

API Keys

For backend operations like saving and managing images, use an API key in the X-API-Key header:

bash

X-API-Key: private_abc123def456...

See Managing API Keys for more information about API keys.

Upload Keys

For temporary image uploads from frontend applications, use upload keys in the URL path:

javascript

const uploadKey = "upl_abc123def456...";
const response = await fetch(`/api/v1/upload-temporary-image/${uploadKey}`, {
  method: "POST",
  headers: { "X-Original-Filename": file.name },
  body: file,
});

See Managing Upload Keys for more information about upload keys.

Rate Limits

See Rate Limiting and Usage Quotas

URLs vs IDs

Most API endpoints accept properties like imageUrl or temporaryImageUrl. You can usually use either the full URL of the image or just the ID of it.

This is for your convenience, so you don't necessarily need to store Icefiery IDs in your database, just the image URLs.

POST /api/v1/upload-temporary-image/{uploadKey}

Upload a temporary image from a frontend application. This endpoint uses upload keys for authentication.

Request Method

POST

Request URL

https://api.icefiery.com/api/v1/upload-temporary-image/{uploadKey}

Request URL Parameters

Parameter	Place	Type	Required	Description
`uploadKey`	URL	string	Yes	The upload key in the URL path

Request Headers

Parameter	Type	Required	Description
`Content-Type`	string	Yes	See Upload Formats for allowed MIME Types
`X-Original-Filename`	string	No	The original filename of the uploaded file

Request Body

The file to upload

Example Request

bashjavascript

bash

curl -X POST \
  -H "Content-Type: image/jpeg" \
  --data-binary @your-image.jpg \
  https://api.icefiery.com/api/v1/upload-temporary-image/YOUR_UPLOAD_KEY

javascript

const uploadKey = "upl_abc123def456...";

const file = event.files.[0];

const response = await fetch(`/api/v1/upload-temporary-image/${uploadKey}`, {
  method: "POST",
  headers: { "X-Original-Filename": file.name },
  body: file,
});

Response

json

{
  "temporaryImageUrl": "https://cdn.icefiery.com/temporary/tmp_123456789"
}

POST /api/v1/save-temporary-image

Save a temporary image permanently to your project.

Request Method

POST

Request URL

https://api.icefiery.com/api/v1/save-temporary-image

Request Headers

Parameter	Type	Required	Description
`X-API-Key`	string	Yes	Your API key starting with `private_`
`Content-Type`	string	Yes	Must be `application/json`

Request Body

Parameter	Type	Required	Description
`temporaryImageUrl`	string	Yes	The CDN URL or the ID of the temporary image
`metadata`	object	No	Optional key-value metadata (Updating Image Metadata)

Examples

json

{
  "temporaryImageUrl": "https://cdn.icefiery.com/temporary/tmp_123456789"
}

json

{
  "temporaryImageUrl": "tmp_123456789"
}

json

{
  "temporaryImageUrl": "https://cdn.icefiery.com/temporary/tmp_123456789",
  "metadata": {
    "productId": "..."
  }
}

Example Request

bashjavascript

bash

curl -X POST \
  -H "X-API-Key: private_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{"temporaryImageUrl":"https://cdn.icefiery.com/temporary/tmp_123456789"}' \
  https://api.icefiery.com/api/v1/save-temporary-image

javascript

const response = await fetch(
  "https://api.icefiery.com/api/v1/save-temporary-image",
  {
    method: "POST",
    headers: {
      "X-API-Key": "private_abc123def456...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      temporaryImageUrl: "https://cdn.icefiery.com/temporary/tmp_123456789",
    }),
  }
);

Response

json

{
  "imageId": "img_abc123",
  "imageUrl": "https://cdn.icefiery.com/res/img_abc123.jpg"
}

POST /api/v1/update-image-metadata

Update image metadata.

You can use add to append new values or set to set complete metadata clearing other values.

Set a value to null to delete it.

Request Method

POST

Request URL

https://api.icefiery.com/api/v1/update-image-metadata

Request Headers

Parameter	Type	Required	Description
`X-API-Key`	string	Yes	Your API key starting with `private_`
`Content-Type`	string	Yes	Must be `application/json`

Request Body

Parameter	Type	Required	Description
`imageUrl`	string	Yes	The CDN URL or the ID of the temporary image
`add`	object	No	Add metadata from this object without clearing other values
`set`	object	No	Clear existing metadata and set from this object

Examples

json

{
  "imageUrl": "https://cdn.icefiery.com/img_123456789",
  "add": {
    "productId": "product_123"
  }
}

json

{
  "imageUrl": "https://cdn.icefiery.com/img_123456789",
  "set": {
    "productId": "product_123"
  }
}

json

{
  "imageUrl": "https://cdn.icefiery.com/img_123456789",
  "set": {
    "productId": null
  }
}

Example Request

bashjavascript

bash

curl -X POST \
  -H "X-API-Key: private_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "imageUrl":"https://cdn.icefiery.com/img_123456789",
    "set": {
      "productId": "product_123"
    }
  }' \
  https://api.icefiery.com/api/v1/update-image-metadata

javascript

const response = await fetch(
  "https://api.icefiery.com/api/v1/update-image-metadata",
  {
    method: "POST",
    headers: {
      "X-API-Key": "private_abc123def456...",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      imageUrl: "https://cdn.icefiery.com/img_123456789",
      set: {
        productId: "product_123",
      },
    }),
  }
);

Response

json

{
  "message": "metadata_updated",
  "metadata": {
    "productId": "product_123"
  }
}

POST /api/v1/delete-image

Delete an image permanently. This marks the image for deletion and removes it from the CDN.

Request Method

POST

Request URL

https://api.icefiery.com/api/v1/delete-image

Request Headers

Parameter	Type	Required	Description
`X-API-Key`	string	Yes	Your API key starting with `private_`
`Content-Type`	string	Yes	Must be `application/json`

Request Body

Parameter	Type	Required	Description
`imageId`	string	Yes	The CDN URL or the ID of the image to delete

Examples

json

{
  "imageId": "img_abc123def456"
}

json

{
  "imageId": "https://cdn.icefiery.com/res/img_abc123def456.jpg"
}

Example Request

bashjavascript

bash

curl -X POST \
  -H "X-API-Key: private_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{"imageId":"img_abc123def456"}' \
  https://api.icefiery.com/api/v1/delete-image

javascript

const response = await fetch("https://api.icefiery.com/api/v1/delete-image", {
  method: "POST",
  headers: {
    "X-API-Key": "private_abc123def456...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    imageId: "img_abc123def456",
  }),
});

Response

json

{
  "message": "image_marked_for_deletion"
}

API Reference ​

Authentication ​

API Keys ​

Upload Keys ​

Rate Limits ​

URLs vs IDs ​

POST /api/v1/upload-temporary-image/{uploadKey} ​

Request Method ​

Request URL ​

Request URL Parameters ​

Request Headers ​

Request Body ​

Example Request ​

Response ​

POST /api/v1/save-temporary-image ​

Request Method ​

Request URL ​

Request Headers ​

Request Body ​

Examples ​

Example Request ​

Response ​

POST /api/v1/update-image-metadata ​

Request Method ​

Request URL ​

Request Headers ​

Request Body ​

Examples ​

Example Request ​

Response ​

POST /api/v1/delete-image ​

Request Method ​

Request URL ​

Request Headers ​

Request Body ​

Examples ​

Example Request ​

Response ​

API Reference

Authentication

API Keys

Upload Keys

Rate Limits

URLs vs IDs

POST /api/v1/upload-temporary-image/{uploadKey}

Request Method

Request URL

Request URL Parameters

Request Headers

Request Body

Example Request

Response

POST /api/v1/save-temporary-image

Request Method

Request URL

Request Headers

Request Body

Examples

Example Request

Response

POST /api/v1/update-image-metadata

Request Method

Request URL

Request Headers

Request Body

Examples

Example Request

Response

POST /api/v1/delete-image

Request Method

Request URL

Request Headers

Request Body

Examples

Example Request

Response