Introduction
The Verify API provides a programmatic interface to monitor your images. Add an image, and Verify looks for places where it appears online. Retrieve the matches whenever you need them, together with interaction counts for the posts they were found in.
Depending on your plan, the API is available at a regional endpoint. Each regional endpoint requires its own API key. These endpoints are currently available:
- Europe (europe-west4):
https://api.frameseek.ai/
Authentication
Every request must be authenticated with a key in the X-Api-Key HTTP header.
When you sign up for API access, you receive a key. Only you and Verify should have access to it. Always call the API from your server, so the key is never exposed in a browser or app.
Example request
curl https://api.frameseek.ai/usage \
-H "X-Api-Key: $FRAMESEEK_API_KEY"Add image
POSThttps://api.frameseek.ai/add
Adds an image to monitoring. Verify downloads the image from the URL you supply and stores a copy in the FrameSeek storage bucket.
The maximum file size is 50 MB.
Example request
curl https://api.frameseek.ai/add \
-H "X-Api-Key: $FRAMESEEK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://www.example.com/images/example.jpg",
"source_id": "example-image-123"
}'Request body
urlstringRequired- The URL of the image to monitor. Supported formats are PNG, JPEG, GIF and WebP. Verify downloads the image from this URL and stores a copy in the FrameSeek storage bucket.
source_idstringOptional- Your own unique ID for the image. Use it to retrieve monitoring results or to remove the image from monitoring.If you omit source_id or send an empty string (""), Verify generates a unique source_id and returns it in the response. Store this ID to retrieve results or remove the image later.
Return body
idstring- The source ID of the image. If you did not supply a source_id, this is the generated ID.
Response
{
"id": "303e392b"
}Remove image
DELETEhttps://api.frameseek.ai/remove
Removes an image from monitoring. The image and its data are also deleted from the FrameSeek storage bucket.
Example request
curl https://api.frameseek.ai/remove \
-X DELETE \
-H "X-Api-Key: $FRAMESEEK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"source_id": "example-image-123"
}'Request body
source_idstringRequired- The source ID of the image to remove. It must match the source_id used when the image was added.
Return body
Returns status code 200 when the image has been removed.
Monitor results
POSThttps://api.frameseek.ai/results
Retrieves the monitoring results for an image you added earlier: the pages where it was found online.
Example request
curl https://api.frameseek.ai/results \
-H "X-Api-Key: $FRAMESEEK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"source_id": "example-image-123",
"start": 10,
"rows": 5
}'Request body
source_idstringRequired- The source ID of the image whose results you want. It must match the source_id used when the image was added.
startintegerOptional- Index of the first row to return.
rowsintegerOptional- Number of rows to return, between 1 and 1000.
Return body
matches_countinteger- Number of matches found.
rows_countinteger- Number of rows returned.
matchesarray- List of match objects.
Match object
page_urlstring- URL of the web page where the image was found.
image_urlstring- URL of the image on that page.
datestring- Date the match was added to the monitoring index.
source_idstring- The source ID of your image.
interactionsobject- Interaction counts for the post, where available (interactions object).
Interactions object
views_countinteger- Number of views the post received (video posts).
likes_countinteger- Number of likes the post received.
shares_countinteger- Number of shares the post received.
comments_countinteger- Number of comments the post received.
Response
{
"matches_count": 100,
"rows_count": 3,
"matches": [
{
"page_url": "https://example.com/news/example.html",
"image_url": "https://example.com/wp-content/uploads/2018/10/example.jpg",
"date": "10-02-2022",
"source_id": "example-image-123",
"interactions": {
"views_count": 15000,
"likes_count": 1232,
"shares_count": 54,
"comments_count": 27
}
}
]
}Usage
GEThttps://api.frameseek.ai/usage
Retrieves your usage: how many images are monitored and how many your subscription allows.
Example request
curl https://api.frameseek.ai/usage \
-H "X-Api-Key: $FRAMESEEK_API_KEY"Return body
image_countinteger- Number of images currently monitored and billed.
image_quotainteger- Maximum number of images in your current subscription.
renewal_subscription_datestring- Date your subscription renews.
Response
{
"image_count": 320,
"image_quota": 2000,
"renewal_subscription_date": "10-02-2025"
}Need help?
Questions about API access, keys or regional endpoints? Book a demo or contact our team, and we will help you get set up. Contact us.