Skip to main content

API Documentation

Quick Start​

GoDiffy has a simple REST API for uploading images and comparing folders. You only need two operations:

  1. Upload images with folder paths
  2. Compare two folders to get similarity results

Authentication​

All requests require your API key in the Authorization header:

curl -H "Authorization: your-api-key-here" ...

Get your API key from the GoDiffy dashboard → Settings → API Keys.

Before uploading images, you must first create a site in the dashboard to get a valid siteId.

Upload Images​

Upload images one by one with a folder path structure.

Endpoint: POST https://api.diffy.app/api/v1/uploads

Basic Upload​

curl -X POST "https://api.diffy.app/api/v1/uploads" \
  -H "Authorization: your-api-key" \
  -F "image=@screenshot1.png" \
  -F "siteId=your-site-id" \
  -F "branch=master" \
  -F "commit=abc123" \
  -F "path=demo-site/master/abc123/homepage.png"

Important: The siteId must be an existing site. If the site doesn't exist, the upload will be rejected with a 404 error.

Upload Multiple Images​

#!/bin/bash
API_KEY="your-api-key"
FOLDER_PATH="demo-site/feature-branch/def456"
BASE_URL="https://api.diffy.app/api/v1"

# Upload all PNG files in current directory
for file in *.png; do
  echo "Uploading $file..."
  curl -X POST "$BASE_URL/uploads" \
    -H "Authorization: $API_KEY" \
    -F "image=@$file" \
    -F "siteId=your-site-id" \
    -F "branch=feature-branch" \
    -F "commit=def456" \
    -F "path=$FOLDER_PATH/$file"
done
#!/bin/bash
API_KEY="your-api-key"
FOLDER_PATH="demo-site/master/abc123"
BASE_URL="https://api.diffy.app/api/v1"

# Upload from a screenshots directory
for file in screenshots/*.png; do
  filename=$(basename "$file")
  echo "Uploading $filename..."
  curl -X POST "$BASE_URL/uploads" \
    -H "Authorization: $API_KEY" \
    -F "image=@$file" \
    -F "siteId=your-site-id" \
    -F "branch=master" \
    -F "commit=abc123" \
    -F "path=$FOLDER_PATH/$filename"
done

Path Structure​

Use any folder structure that makes sense for your project:

  • demo-site/master/abc123/homepage.png
  • demo-site/feature-ui/def456/homepage.png
  • my-app/production/v1.2.3/login-page.png
  • website/staging/commit-hash/checkout-flow.png

Compare Folders​

Compare all images in two folders to get similarity scores.

Endpoint: POST https://api.diffy.app/api/v1/comparisons

Basic Comparison​

curl -X POST "https://api.diffy.app/api/v1/comparisons" \
  -H "Authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "source_folder": "demo-site/master/abc123",
    "target_folder": "demo-site/feature-ui/def456"
  }'

Response:

{
  "comparison_id": "comp_123456",
  "status": "processing",
  "message": "Comparison started"
}

Get Comparison Results​

curl -H "Authorization: your-api-key" \
  "https://api.diffy.app/api/v1/comparisons/comp_123456"

Response:

{
  "comparison_id": "comp_123456",
  "status": "completed",
  "source_folder": "demo-site/master/abc123",
  "target_folder": "demo-site/feature-ui/def456",
  "results": [
    {
      "image_name": "homepage.png",
      "similarity": 0.987,
      "passed": true
    },
    {
      "image_name": "about.png", 
      "similarity": 0.923,
      "passed": true
    },
    {
      "image_name": "contact.png",
      "similarity": 0.834,
      "passed": false
    }
  ],
  "summary": {
    "total_images": 3,
    "passed": 2,
    "failed": 1,
    "overall_passed": false
  }
}

Complete Example​

Here's a complete workflow:

#!/bin/bash
API_KEY="your-api-key"
BASE_URL="https://api.diffy.app/api/v1"

# 1. Upload master branch images
echo "Uploading master branch..."
curl -X POST "$BASE_URL/uploads" \
  -H "Authorization: $API_KEY" \
  -F "image=@homepage.png" \
  -F "path=demo-site/master/abc123/homepage.png"

curl -X POST "$BASE_URL/uploads" \
  -H "Authorization: $API_KEY" \
  -F "image=@about.png" \
  -F "path=demo-site/master/abc123/about.png"

# 2. Upload feature branch images  
echo "Uploading feature branch..."
curl -X POST "$BASE_URL/uploads" \
  -H "Authorization: $API_KEY" \
  -F "image=@homepage.png" \
  -F "path=demo-site/feature-ui/def456/homepage.png"

curl -X POST "$BASE_URL/uploads" \
  -H "Authorization: $API_KEY" \
  -F "image=@about.png" \
  -F "path=demo-site/feature-ui/def456/about.png"

# 3. Compare the folders
echo "Starting comparison..."
COMPARISON=$(curl -s -X POST "$BASE_URL/comparisons" \
  -H "Authorization: $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source_folder": "demo-site/master/abc123",
    "target_folder": "demo-site/feature-ui/def456"
  }')

COMPARISON_ID=$(echo $COMPARISON | jq -r '.comparison_id')
echo "Comparison ID: $COMPARISON_ID"

# 4. Wait for results (in practice, use webhooks or polling)
sleep 5

# 5. Get results
echo "Getting results..."
curl -H "Authorization: $API_KEY" \
  "$BASE_URL/comparisons/$COMPARISON_ID"

Rate Limits​

  • 100 requests per minute per API key
  • Rate limit headers included in responses
  • Contact support for higher limits

Support​

That's it! Simple image uploads and folder comparisons - everything you need for visual regression testing.