Collections API

Complete reference for the Collections endpoint. Learn how to create, list, update, and delete collections programmatically.

List Collections

Retrieve a list of all collections belonging to the authenticated user.

GET https://api.optimage.com/api/v1/collections

Response (200 OK)

[
  {
    "id": "col_abc123",
    "name": "My Website",
    "description": "Images for my personal website",
    "imageCount": 42,
    "createdAt": "2025-12-04T10:30:00Z"
  },
  {
    "id": "col_xyz789",
    "name": "E-Commerce Store",
    "description": "Product images",
    "imageCount": 156,
    "createdAt": "2025-11-15T08:00:00Z"
  }
]

Example (JavaScript)

const response = await fetch('https://api.optimage.com/api/v1/collections', {
  credentials: 'include'
});

const collections = await response.json();
console.log(`Total collections: ${collections.length}`);

collections.forEach(col => {
  console.log(`${col.name}: ${col.imageCount} images`);
});

Create Collection

Create a new collection to organize your images.

POST https://api.optimage.com/api/v1/collections

Request Body

{
  "name": "My New Collection",
  "description": "Optional description for the collection"
}

Request Fields

  • •name (required): Collection name, 3-100 characters
  • •description (optional): Description of the collection

Response (201 Created)

{
  "id": "col_newid123",
  "name": "My New Collection",
  "description": "Optional description for the collection",
  "imageCount": 0,
  "createdAt": "2025-12-04T14:00:00Z"
}

Error Responses

400 Bad Request - Invalid name (too short/long or invalid characters)

401 Unauthorized - Not authenticated

409 Conflict - Collection name already exists

Example (cURL)

curl -X POST https://api.optimage.com/api/v1/collections \
  -H "Content-Type: application/json" \
  -b cookies.txt \
  -d '{
    "name": "My New Collection",
    "description": "Product images for 2025"
  }'

Example (JavaScript)

const response = await fetch('https://api.optimage.com/api/v1/collections', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  credentials: 'include',
  body: JSON.stringify({
    name: 'My New Collection',
    description: 'Product images for 2025'
  })
});

if (response.ok) {
  const collection = await response.json();
  console.log('Collection created:', collection.id);
} else {
  const error = await response.json();
  console.error('Failed:', error.message);
}

Update Collection

Update the name or description of an existing collection. Image URLs are not affected.

PUT https://api.optimage.com/api/v1/collections/:collectionId

URL Parameters

  • •collectionId: The unique identifier of the collection

Request Body

{
  "name": "Updated Collection Name",
  "description": "Updated description"
}

Response (200 OK)

{
  "id": "col_abc123",
  "name": "Updated Collection Name",
  "description": "Updated description",
  "imageCount": 42,
  "createdAt": "2025-12-04T10:30:00Z"
}

Error Responses

400 Bad Request - Invalid name

401 Unauthorized - Not authenticated

403 Forbidden - Collection does not belong to user

404 Not Found - Collection not found

Example (JavaScript)

const collectionId = 'col_abc123';

const response = await fetch(
  `https://api.optimage.com/api/v1/collections/${collectionId}`,
  {
    method: 'PUT',
    headers: {
      'Content-Type': 'application/json',
    },
    credentials: 'include',
    body: JSON.stringify({
      name: 'Updated Collection Name',
      description: 'New description'
    })
  }
);

if (response.ok) {
  const collection = await response.json();
  console.log('Collection updated:', collection.name);
}

Note: Updating a collection's name does not change image URLs. All existing image links continue to work as they use the collection ID.

Delete Collection

Permanently delete a collection and all images within it. This action cannot be undone.

DELETE https://api.optimage.com/api/v1/collections/:collectionId

URL Parameters

  • •collectionId: The unique identifier of the collection to delete

Response (200 OK)

{
  "message": "Collection deleted successfully"
}

Error Responses

401 Unauthorized - Not authenticated

403 Forbidden - Collection does not belong to user

404 Not Found - Collection not found

Example (cURL)

curl -X DELETE https://api.optimage.com/api/v1/collections/col_abc123 \
  -b cookies.txt

Example (JavaScript)

const collectionId = 'col_abc123';

const response = await fetch(
  `https://api.optimage.com/api/v1/collections/${collectionId}`,
  {
    method: 'DELETE',
    credentials: 'include'
  }
);

if (response.ok) {
  console.log('Collection deleted successfully');
} else {
  console.error('Failed to delete collection');
}

Warning: Deleting a collection permanently removes all images within it. All image URLs will immediately stop working. This action cannot be undone. Deleted images do not restore your monthly quota.

Get Collection by ID

Retrieve details about a specific collection, including its images.

GET https://api.optimage.com/api/v1/collections/:collectionId

Response (200 OK)

{
  "id": "col_abc123",
  "name": "My Website",
  "description": "Images for my personal website",
  "imageCount": 42,
  "createdAt": "2025-12-04T10:30:00Z",
  "images": [
    {
      "id": "img_123",
      "slug": "hero-banner",
      "checksum": "a1b2c3...",
      "createdAt": "2025-12-04T11:00:00Z"
    },
    {
      "id": "img_456",
      "slug": "about-photo",
      "checksum": "d4e5f6...",
      "createdAt": "2025-12-04T11:05:00Z"
    }
  ]
}

Example (JavaScript)

const collectionId = 'col_abc123';

const response = await fetch(
  `https://api.optimage.com/api/v1/collections/${collectionId}`,
  {
    credentials: 'include'
  }
);

if (response.ok) {
  const collection = await response.json();
  console.log(`Collection: ${collection.name}`);
  console.log(`Images: ${collection.images.length}`);

  collection.images.forEach(img => {
    console.log(`- ${img.slug}`);
  });
}