Manage Screenshot Metadata

The Screenshot Metadata Management API provides endpoints for reading and writing PNG metadata on images stored in your cloud storage (Amazon S3 or Cloudflare R2). These endpoints enable you to extract image information, manage metadata fields, and maintain consistency across your screenshot library.

Overview

The metadata endpoints support:

• Batch Processing: Process up to 100 images per request
• API Key Authentication: Uses the same x-api-key authentication as other screenshot endpoints
• Multi-Cloud Support: Works with both Amazon S3 and Cloudflare R2
• Graceful Error Handling: Failed images return error details without stopping the batch
• Image Analysis: Extracts dimensions, file size, type, and pixel hash

Read Image Metadata

Reads image information and metadata from cloud storage.

GET /screenshot/metadata

Request

See Example

[
  {
    "fileObject": "path/to/image.png"
  },
  {
    "fileObject": "path/to/image2.png"
  }
]

Request Parameters

Parameter	Type	Required	Description
url	string	Yes	Path to the image in your cloud storage bucket

Success Response

Condition: If everything is OK

Code: 200

See Example

[
  {
    "name": "image.png",
    "type": "png",
    "width": 3034,
    "height": 746,
    "size": 132122,
    "statusCode": 200,
    "hash": "69043862ba9192dfb0eb81a2a580e7cc49a9d3505545ead6ff31a0540b89a997",
    "metadata": {
      "Software": "LaunchBrightly",
      "ImageDescription": "Screenshot Title",
      "OriginalDocumentID": "abc123",
      "ImageUniqueID": "xyz789"
    }
  },
  {
    "name": "image2.png",
    "type": "png",
    "width": 1920,
    "height": 1080,
    "size": 245000,
    "statusCode": 200,
    "hash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
    "metadata": {}
  }
]

Response Fields

Field	Type	Description
name	string	Filename of the image
type	string	Image type (png, jpeg, gif, etc.)
width	number	Image width in pixels
height	number	Image height in pixels
size	number	File size in bytes
statusCode	number	HTTP status code (200, 404, 500, etc.)
hash	string	Pixel hash for image deduplication and comparison
metadata	object	PNG metadata (tEXt chunks per PNG specification)

Error Response

Condition: Image not found or other errors

Code: 200 (batch returns individual status codes)

See Example

[
  {
    "name": "success.png",
    "type": "png",
    "width": 1920,
    "height": 1080,
    "size": 245000,
    "statusCode": 200,
    "hash": "abc123def456...",
    "metadata": {
      "Software": "LaunchBrightly"
    }
  },
  {
    "name": "missing.png",
    "type": "",
    "width": 0,
    "height": 0,
    "size": 0,
    "statusCode": 404,
    "hash": "",
    "metadata": {},
    "error": {
      "message": "Image not found in S3: public/missing.png",
      "type": "IMAGE_NOT_FOUND_IN_S3"
    }
  }
]

Write Image Metadata

Writes or updates metadata to PNG images in cloud storage. Returns pre-signed URLs (24-hour expiry) for the updated images.

POST /screenshot/metadata

Request

See Example

[
  {
    "fileObject": "path/to/image.png",
    "metadata": {
      "Software": "LaunchBrightly",
      "ImageDescription": "Updated Title",
      "OriginalDocumentID": "doc-123",
      "ImageUniqueID": "unique-456"
    }
  },
  {
    "fileObject": "path/to/image2.png",
    "metadata": {
      "ImageDescription": "Another Screenshot"
    }
  }
]

Request Parameters

Parameter	Type	Required	Description
url	string	Yes	Path to the image in your cloud storage bucket
metadata	object	Yes	Key-value pairs of metadata to write/update

Common Metadata Fields

Field	Description
Software	Software used to create the image
ImageDescription	Human-readable description or title
OriginalDocumentID	Reference to the original document or source
ImageUniqueID	Unique identifier for the image

TIP

PNG metadata is stored as tEXt chunks according to the PNG specification. You can use any custom key-value pairs that suit your needs.

Success Response

Condition: If everything is OK

Code: 200

See Example

[
  {
    "url": "https://bucket.s3.us-east-1.amazonaws.com/path/to/image.png?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Content-Sha256=UNSIGNED-PAYLOAD&X-Amz-Credential=AKIAIOSFODNN7EXAMPLE%2F20231201%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Date=20231201T120000Z&X-Amz-Expires=86400&X-Amz-Signature=example-signature&X-Amz-SignedHeaders=host",
    "name": "image.png",
    "type": "png",
    "width": 3034,
    "height": 746,
    "size": 132200,
    "statusCode": 200,
    "hash": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2",
    "metadata": {
      "Software": "LaunchBrightly",
      "ImageDescription": "Updated Title",
      "OriginalDocumentID": "doc-123",
      "ImageUniqueID": "unique-456"
    }
  },
  {
    "url": "https://bucket.s3.us-east-1.amazonaws.com/path/to/image2.png?X-Amz-Algorithm=...",
    "name": "image2.png",
    "type": "png",
    "width": 1920,
    "height": 1080,
    "size": 245100,
    "statusCode": 200,
    "hash": "b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0c1d2e3f4a5b6c7d8e9f0a1b2c3",
    "metadata": {
      "ImageDescription": "Another Screenshot"
    }
  }
]

Response Fields

Field	Type	Description
url	string	Pre-signed URL (24-hour expiry) to download the updated image
name	string	Filename of the image
type	string	Image type (png, jpeg, gif, etc.)
width	number	Image width in pixels
height	number	Image height in pixels
size	number	File size in bytes
statusCode	number	HTTP status code (200, 404, 500, etc.)
hash	string	Pixel hash for image deduplication and comparison
metadata	object	PNG metadata that was written to the image

Error Response

Condition: Storage credentials not configured

Code: 403

See Example

{
  "error": {
    "type": "USER_ACCESS_KEYS_NOT_CONFIGURED",
    "message": "User access keys are not configured. Please set up your cloud storage credentials."
  }
}

Condition: Individual image failures in batch

Code: 200 (batch returns individual status codes)

See Example

[
  {
    "url": "https://bucket.s3.us-east-1.amazonaws.com/path/to/success.png?X-Amz-Algorithm=...",
    "name": "success.png",
    "type": "png",
    "width": 1920,
    "height": 1080,
    "size": 245000,
    "statusCode": 200,
    "hash": "abc123def456...",
    "metadata": {
      "Software": "LaunchBrightly"
    }
  },
  {
    "name": "failed.png",
    "type": "",
    "width": 0,
    "height": 0,
    "size": 0,
    "statusCode": 500,
    "hash": "",
    "metadata": {},
    "error": {
      "message": "Failed to write metadata to image",
      "type": "METADATA_WRITE_FAILED"
    }
  }
]

Authentication

Both endpoints require API key authentication using the x-api-key header:

x-api-key: your-api-key-here

The API key is used to:

• Authenticate your request
• Identify your cloud storage configuration (S3 or R2)
• Determine which bucket to access

WARNING

Users can only access images in their own configured bucket. Make sure you have set up your cloud storage credentials before using these endpoints.

Batch Processing

Both endpoints support batch operations with the following characteristics:

• Maximum Batch Size: 100 images per request
• Concurrency Control: Processes 15 images at a time to prevent rate limiting
• Response Order: The response array maintains the same order as the request array
• Partial Success: Failed images return error details without stopping the batch

Example: Processing Multiple Images

See Example

[
  {
    "url": "screenshots/2024/january/screenshot-1.png",
    "metadata": {
      "ImageDescription": "Login Page",
      "OriginalDocumentID": "doc-001"
    }
  },
  {
    "url": "screenshots/2024/january/screenshot-2.png",
    "metadata": {
      "ImageDescription": "Dashboard",
      "OriginalDocumentID": "doc-002"
    }
  },
  {
    "url": "screenshots/2024/january/screenshot-3.png",
    "metadata": {
      "ImageDescription": "Settings Page",
      "OriginalDocumentID": "doc-003"
    }
  }
]

Error Types

In addition to the common error types, the metadata endpoints may return:

Error Type	Description
USER_ACCESS_KEYS_NOT_CONFIGURED	Cloud storage credentials not configured for this user
IMAGE_NOT_FOUND_IN_S3	The specified image does not exist in cloud storage
METADATA_WRITE_FAILED	Failed to write metadata to the image
INVALID_IMAGE_FORMAT	The file is not a valid PNG image
CLOUD_STORAGE_ERROR	Generic cloud storage operation error

Use Cases

Image Deduplication

Use the pixel hash to identify duplicate or similar images:

// Compare hashes from two images
const image1Hash = "69043862ba9192dfb0eb81a2a580e7cc49a9d3505545ead6ff31a0540b89a997";
const image2Hash = "69043862ba9192dfb0eb81a2a580e7cc49a9d3505545ead6ff31a0540b89a997";

if (image1Hash === image2Hash) {
  console.log("Images are identical or very similar");
}

Screenshot Library Management

Track and organize screenshots with metadata:

{
  "url": "help-center/feature-x/step-1.png",
  "metadata": {
    "Software": "LaunchBrightly",
    "ImageDescription": "Feature X - Step 1: Initial Setup",
    "OriginalDocumentID": "help-article-123",
    "ImageUniqueID": "screenshot-uuid-456",
    "CreatedDate": "2024-01-15",
    "FeatureName": "Feature X",
    "StepNumber": "1"
  }
}

Version Tracking

Maintain version information in metadata:

{
  "metadata": {
    "ImageDescription": "User Dashboard v2.3",
    "Version": "2.3.0",
    "LastUpdated": "2024-12-12",
    "UpdatedBy": "john.doe@example.com"
  }
}

Best Practices

1. Use Descriptive Metadata Keys: Choose clear, consistent key names for your metadata fields
2. Batch Related Operations: Group multiple image operations into a single request for better performance
3. Handle Partial Failures: Check individual statusCode values in the response to identify failed operations
4. Store Image URLs: Save the returned pre-signed URLs if you need immediate access to updated images
5. Set Up Storage Credentials: Configure your cloud storage credentials before using these endpoints

TIP

The pixel hash feature is particularly useful for detecting duplicate screenshots in your library, even if they have different filenames or are stored in different locations.