Documentation Menu

Getting Started

This guide will walk you through setting up Akator Image Matcher and making your first API calls.

Prerequisites

  • An API key (contact us at info@akator.de to get started)
  • A tool for making HTTP requests (curl, Postman, or your application code)

Step 1: Verify Your API Key

First, let's verify that your API key is working by listing your collections:

curl -X GET "https://matching.akator.de/api/v1.1/collections" \
  -H "Authorization: Bearer YOUR_API_KEY"

You should receive a response like:

{
  "collections": [],
  "total": 0
}

Step 2: Create a Collection

Collections hold your blocklist images. Create one for your copyright-reported content: 

curl -X POST "https://matching.akator.de/api/v1.1/collections" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "copyright-blocklist"}'

Response:

{
  "id": "col_abc123",
  "name": "copyright-blocklist",
  "image_count": 0,
  "created_at": "2025-01-19T10:00:00Z"
}

Save the id — you'll need it for all subsequent operations.

Step 3: Add an Image to the Blocklist

When a rightsholder reports a copyright infringement, add the reported image to your collection: 

curl -X POST "https://matching.akator.de/api/v1.1/collections/col_abc123/images" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@reported-image.jpg" \
  -F 'metadata={"reported_by": "rightsholder@example.com", "reported_at": "2025-01-19"}'

Response:

{
  "id": "img_xyz789",
  "collection_id": "col_abc123",
  "metadata": {
    "reported_by": "rightsholder@example.com",
    "reported_at": "2025-01-19"
  },
  "created_at": "2025-01-19T10:05:00Z"
}

Step 4: Check User Uploads

Integrate the match endpoint into your upload workflow. When a user uploads an image, check it against your blocklist: 

curl -X POST "https://matching.akator.de/api/v1.1/collections/col_abc123/match" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "image=@user-upload.jpg"

No Match Found

If the image doesn't match anything in your blocklist:

{
  "matches": [],
  "checked_at": "2025-01-19T10:10:00Z",
  "collection_size": 1
}

The upload can proceed normally.

Match Found

If a match is found:

{
  "matches": [
    {
      "image_id": "img_xyz789",
      "score": 0.947,
      "transformations_detected": ["resize", "crop"],
      "metadata": {
        "reported_by": "rightsholder@example.com",
        "reported_at": "2025-01-19"
      }
    }
  ],
  "checked_at": "2025-01-19T10:10:00Z",
  "collection_size": 1
}

The score indicates similarity (0-1, where 1 is identical). You should block the upload or flag it for manual review.

Integration Example

Here's a simple integration example in JavaScript:

async function checkUpload(imageFile, collectionId) {
  const formData = new FormData();
  formData.append('image', imageFile);

  const response = await fetch(
    `https://matching.akator.de/api/v1.1/collections/${collectionId}/match`,
    {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${process.env.AKATOR_API_KEY}`
      },
      body: formData
    }
  );

  const result = await response.json();

  if (result.matches.length > 0) {
    // Match found - block or flag for review
    const topMatch = result.matches[0];
    console.log(`Match found: ${topMatch.score * 100}% similarity`);
    return { allowed: false, match: topMatch };
  }

  // No match - allow upload
  return { allowed: true };
}

Next Steps