Image Library API

Manage image collections for use in Word document templates and email campaigns.

---

Base URL

https://app.datapublisher.io/api/image-library

---

Authentication

All endpoints require JWT authentication via Authorization: Bearer header.

---

Overview

The Image Library API allows you to:

Create named image libraries

Upload images to libraries (JPEG, PNG, SVG, GIF)

Organize images by library and category

Retrieve image URLs for document insertion

Delete images and libraries

Supported Formats:

JPEG (.jpg, .jpeg)

PNG (.png)

SVG (.svg)

GIF (.gif)

Use Cases:

Company logos in templates

Product images for catalogs

Charts and diagrams

Email campaign assets

---

Library Management

Create Image Library

Create a new image library container.

Endpoint: POST /libraries

Headers:

Authorization: Bearer

Content-Type: application/json

Request Body:

{ "name": "Product Images", "description": "Product catalog photos", "category": "products"

}

Response (200 OK):

{ "success": true, "library": { "id": "library-uuid", "name": "Product Images", "description": "Product catalog photos", "category": "products", "imageCount": 0, "createdAt": "2026-02-12T10:30:00Z" }, "message": "Image library created successfully"

}

---

List Image Libraries

Get all image libraries for the user.

Endpoint: GET /libraries

Headers:

Authorization: Bearer

Query Parameters:

category (optional): Filter by category

Response (200 OK):

{ "success": true, "libraries": [ { "id": "library-uuid-1", "name": "Product Images", "description": "Product catalog photos", "category": "products", "imageCount": 15, "totalSize": 2500000, "createdAt": "2026-02-12T10:30:00Z", "updatedAt": "2026-02-12T11:00:00Z" }, { "id": "library-uuid-2", "name": "Company Logos", "description": "Brand assets", "category": "branding", "imageCount": 8, "totalSize": 450000, "createdAt": "2026-01-15T09:00:00Z", "updatedAt": "2026-02-01T14:30:00Z" } ], "totalCount": 2

}

---

Get Library Details

Get detailed information about a specific library.

Endpoint: GET /libraries/:libraryId

Headers:

Authorization: Bearer

Path Parameters:

libraryId: Library UUID

Response (200 OK):

{ "success": true, "library": { "id": "library-uuid", "name": "Product Images", "description": "Product catalog photos", "category": "products", "imageCount": 15, "totalSize": 2500000, "images": [ { "id": "image-uuid-1", "fileName": "widget-pro.jpg", "description": "Widget Pro product photo", "fileSize": 150000, "width": 1920, "height": 1080, "format": "JPEG", "url": "https://app.datapublisher.io/images/user-uuid/library-uuid/widget-pro.jpg", "uploadedAt": "2026-02-12T10:45:00Z" } ], "createdAt": "2026-02-12T10:30:00Z", "updatedAt": "2026-02-12T11:00:00Z" }

}

---

Delete Library

Remove an image library (and all its images).

Endpoint: DELETE /libraries/:libraryId

Headers:

Authorization: Bearer

Response (200 OK):

{ "success": true, "message": "Image library deleted successfully", "deletedImages": 15

}

---

Image Operations

Upload Image

Upload an image to a library.

Endpoint: POST /libraries/:libraryId/images

Headers:

Authorization: Bearer

Content-Type: multipart/form-data

Form Data:

image: File (required) - Image file

description: String (optional) - Image description

tags: String (optional) - Comma-separated tags

Request Example:

const formData = new FormData();
formData.append('image', imageFile);

formData.append('description', 'Widget Pro product photo');

formData.append('tags', 'product,widget,electronics');

Response (200 OK):

{ "success": true, "image": { "id": "image-uuid", "libraryId": "library-uuid", "fileName": "widget-pro.jpg", "description": "Widget Pro product photo", "tags": ["product", "widget", "electronics"], "fileSize": 150000, "width": 1920, "height": 1080, "format": "JPEG", "url": "https://app.datapublisher.io/images/user-uuid/library-uuid/widget-pro.jpg", "uploadedAt": "2026-02-12T10:45:00Z" }, "message": "Image uploaded successfully"

}

Error Responses:

400 Bad Request - Invalid file:

{
  "error": "Only image files are allowed (JPEG, PNG, SVG, GIF)"

}

413 Payload Too Large:

{
  "error": "File size exceeds 50MB limit"

}

---

List Images in Library

Get all images in a specific library.

Endpoint: GET /libraries/:libraryId/images

Headers:

Authorization: Bearer

Query Parameters:

tag (optional): Filter by tag

format (optional): Filter by format (jpeg, png, svg, gif)

Response (200 OK):

{ "success": true, "libraryId": "library-uuid", "libraryName": "Product Images", "images": [ { "id": "image-uuid-1", "fileName": "widget-pro.jpg", "description": "Widget Pro product photo", "tags": ["product", "widget", "electronics"], "fileSize": 150000, "width": 1920, "height": 1080, "format": "JPEG", "url": "https://app.datapublisher.io/images/user-uuid/library-uuid/widget-pro.jpg", "uploadedAt": "2026-02-12T10:45:00Z" } ], "totalCount": 1

}

---

Get Image Details

Get detailed information about a specific image.

Endpoint: GET /images/:imageId

Headers:

Authorization: Bearer

Path Parameters:

imageId: Image UUID

Response (200 OK):

{ "success": true, "image": { "id": "image-uuid", "libraryId": "library-uuid", "libraryName": "Product Images", "fileName": "widget-pro.jpg", "description": "Widget Pro product photo", "tags": ["product", "widget", "electronics"], "fileSize": 150000, "width": 1920, "height": 1080, "format": "JPEG", "url": "https://app.datapublisher.io/images/user-uuid/library-uuid/widget-pro.jpg", "filePath": "/images/user-uuid/library-uuid/widget-pro.jpg", "uploadedAt": "2026-02-12T10:45:00Z", "usageCount": 5 }

}

---

Delete Image

Remove an image from a library.

Endpoint: DELETE /images/:imageId

Headers:

Authorization: Bearer

Response (200 OK):

{
  "success": true,

  "message": "Image deleted successfully"

}

---

Image Categories

Pre-defined categories:

products - Product photos

branding - Logos and brand assets

charts - Charts and diagrams

backgrounds - Background images

icons - Icon sets

other - Miscellaneous images

---

Inserting Images in Word

Using the image URL in Office.js:

// Get image from library
const response = await fetch('https://app.datapublisher.io/api/image-library/images/image-uuid', {

  headers: { 'Authorization': Bearer ${jwtToken} }

});

const { image } = await response.json();


// Insert into Word document

await Word.run(async (context) => {

  const paragraph = context.document.body.insertParagraph('', Word.InsertLocation.end);

  const inlinePicture = paragraph.insertInlinePictureFromBase64(base64Image, Word.InsertLocation.end);


  // Or use URL

  const picture = paragraph.insertPicture(image.url, Word.InsertLocation.end);

  picture.height = 200;

  picture.width = 300;


  await context.sync();

});

---

File Specifications

Max File Size: 50MB per image

Supported Formats: JPEG, PNG, SVG, GIF

Storage: User-specific directories

URL Access: Authenticated URLs (require JWT)

---

Rate Limiting

Upload operations: 50 per 15 minutes

List/Get operations: 1000 per 15 minutes

Delete operations: 100 per 15 minutes

---

Common Error Codes

| Status Code | Description |

|-------------|-------------|

| 400 | Invalid file format or missing fields |

| 401 | Unauthorized - invalid JWT |

| 404 | Library or image not found |

| 413 | File size exceeds 50MB limit |

| 500 | Image processing failed |

---

Usage Examples

JavaScript

// Create library
async function createLibrary(name, description) {

  const response = await fetch('https://app.datapublisher.io/api/image-library/libraries', {

    method: 'POST',

    headers: {

      'Authorization': Bearer ${jwtToken},

      'Content-Type': 'application/json'

    },

    body: JSON.stringify({ name, description, category: 'products' })

  });

  return await response.json();

}


// Upload image

async function uploadImage(libraryId, imageFile, description) {

  const formData = new FormData();

  formData.append('image', imageFile);

  formData.append('description', description);


  const response = await fetch(https://app.datapublisher.io/api/image-library/libraries/${libraryId}/images, {

    method: 'POST',

    headers: { 'Authorization': Bearer ${jwtToken} },

    body: formData

  });

  return await response.json();

}


// List all libraries

async function listLibraries() {

  const response = await fetch('https://app.datapublisher.io/api/image-library/libraries', {

    headers: { 'Authorization': Bearer ${jwtToken} }

  });

  const { libraries } = await response.json();

  return libraries;

}


// Get library images

async function getLibraryImages(libraryId) {

  const response = await fetch(https://app.datapublisher.io/api/image-library/libraries/${libraryId}/images, {

    headers: { 'Authorization': Bearer ${jwtToken} }

  });

  const { images } = await response.json();

  return images;

}


// Delete image

async function deleteImage(imageId) {

  const response = await fetch(https://app.datapublisher.io/api/image-library/images/${imageId}, {

    method: 'DELETE',

    headers: { 'Authorization': Bearer ${jwtToken} }

  });

  return await response.json();

}

---

Best Practices

Optimization: Optimize images before upload (compress, resize)

Naming: Use descriptive file names

Organization: Create separate libraries for different purposes

Tags: Use tags for easy searching

Formats: Use JPEG for photos, PNG for transparency, SVG for logos

Resolution: Upload high-resolution images (can be scaled down)

Cleanup: Delete unused images to save storage

---

Image Library API

Base URL

Authentication

Overview

Library Management

Create Image Library

List Image Libraries

Get Library Details

Delete Library

Image Operations

Upload Image

List Images in Library

Get Image Details

Delete Image

Image Categories

Inserting Images in Word

File Specifications

Rate Limiting

Common Error Codes

Usage Examples

JavaScript

Best Practices

Related Documentation