POST /v1/lookup

POST /v1/lookup

Look up an asset by its fingerprint. Useful when a file has been stripped of its C2PA manifest but may still carry a watermark, or when you have a modified copy (cropped, recompressed) and want to find the original signed record.

POST https://api.verbitas.io/v1/lookup
Authorization: Bearer vb_live_...
Content-Type: multipart/form-data  (file upload)
  -- or --
Content-Type: application/json     (pre-computed fingerprint)

Lookup modes

Three lookup strategies run in order of confidence. The API returns all matches across all strategies.

Mode	How it works	Confidence
exact_watermark	Decode TrustMark/AudioSeal watermark; match on watermark_id	Highest
exact_hash	BLAKE3 hash of full file bytes; exact match	High
perceptual_hash	pHash (image) or audio fingerprint; Hamming-distance match	Medium

Request: file upload

curl -X POST https://api.verbitas.io/v1/lookup \
  -H "Authorization: Bearer $VERBITAS_API_KEY" \
  -F "asset=@cropped_image.jpg"

Request: pre-computed fingerprint

If you have already computed the fingerprint client-side:

curl -X POST https://api.verbitas.io/v1/lookup \
  -H "Authorization: Bearer $VERBITAS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "algorithm": "perceptual_hash",
    "binding_hash": "f0e1d2c3b4a59687..."
  }'

Response: 200 OK

{
  "matches": [
    {
      "asset_id": "a_01j...",
      "match_type": "perceptual_hash",
      "confidence": 0.81,
      "distance": 12,
      "manifest_uri": "https://m.verbitas.io/manifests/a_01j.../manifest.c2pa",
      "verifier_url": "https://v.verbitas.io/v/a_01j..."
    }
  ],
  "request_id": "req_01j..."
}

Response fields

Field	Type	Description
matches	array	Ranked list of matches; empty if none found
matches[].asset_id	string	ID of the matching signed asset
matches[].match_type	string	exact_watermark, exact_hash, or perceptual_hash
matches[].confidence	float	0.0–1.0, decayed by distance for pHash matches
matches[].distance	int or null	Hamming distance for pHash; null for exact matches
matches[].manifest_uri	string	URI to the C2PA manifest for this asset
matches[].verifier_url	string	Public verifier URL

Multiple candidates

When more than one match is found with overlapping confidence:

{
  "matches": [
    { "asset_id": "a_01j...", "match_type": "perceptual_hash", "confidence": 0.79, "distance": 14 },
    { "asset_id": "a_02k...", "match_type": "perceptual_hash", "confidence": 0.74, "distance": 18 }
  ],
  "request_id": "req_01j..."
}

A recipe with ambiguous_match_behavior: manual_review will surface the multiple_candidates verification state when this occurs during a verify call. See Verification States.

No match

{
  "matches": [],
  "request_id": "req_01j..."
}

Python SDK example

import verbitas

client = verbitas.Client()
result = client.lookup("cropped_image.jpg")

for match in result.matches:
    print(match.asset_id, match.match_type, match.confidence)
# a_01j... perceptual_hash 0.81

TypeScript SDK example

import { VerbitasClient } from "@verbitas/sdk";

const client = new VerbitasClient();
const result = await client.lookup("cropped_image.jpg");

for (const match of result.matches) {
  console.log(match.assetId, match.matchType, match.confidence);
}

Error codes

HTTP	Code	Meaning
400	verbitas.lookup.no_input	No asset or fingerprint provided
401	verbitas.auth.invalid_key	API key invalid
415	verbitas.lookup.unsupported_file_type	File format not supported
429	verbitas.ratelimit.exceeded	Rate limit exceeded

Scope requirements

Lookup is available to both sign-scoped and verify-scoped keys. No admin scope required.