Hash lists API reference

Hash lists hold PDQ perceptual hashes of images a project never wants again. Image uploads are compared with every list in the project: a flag list records matches, and a block list also blocks close ones.

Guide: Hash lists.

Endpoints

EndpointDescription
GET /projects/:projectId/hash-listsList every hash list in a project
POST /projects/:projectId/hash-listsCreate a hash list.
GET /hash-lists/:hashListIdGet a hash list by ID
PATCH /hash-lists/:hashListIdRename a hash list or change what its matches do.
DELETE /hash-lists/:hashListIdDelete a hash list and every entry in it.
GET /hash-lists/:hashListId/entriesGet a page of the hashes in a hash list, newest first
POST /hash-lists/:hashListId/entriesAdd a PDQ hash to a hash list, either as a hash or from an image asset.
DELETE /hash-list-entries/:entryIdRemove a hash from its hash list.

The hash list object

idstring
Unique hash list ID
projectIdstring
ID of the project that owns the list
namestring
Display name
actionActionEnum
What a match does: flag reports it without changing the decision, block blocks matches 16 bits apart or fewer and flags looser ones
Allowed values
flagblock
createdAtnumber
When the list was created, in milliseconds since the Unix epoch
descriptionstring (optional)
What the list is for, such as the policy it enforces
createdByUserIdstring (optional)
ID of the user who created the list
updatedAtnumber (optional)
When the list was last updated, in milliseconds since the Unix epoch

The hash list entry object

idstring
Unique entry ID
projectIdstring
ID of the project that owns the entry
hashListIdstring
ID of the list the entry belongs to
hashstring
PDQ hash of the listed image, as 64 hexadecimal characters
qualitynumber (optional)
PDQ quality of the hash from 0 to 100, or null when it was added without one. Entries below 50 are never matched.
createdAtnumber
When the entry was added, in milliseconds since the Unix epoch
labelstring (optional)
Your own note or reference for the entry
sourceAssetIdstring (optional)
ID of the asset the hash was taken from, when it was added from an asset
createdByUserIdstring (optional)
ID of the user who added the entry

Endpoint details

List Hash Lists

List every hash list in a project

OpenAPI YAML
GET
https://api.calmlens.com/v1/projects/
/hash-lists
const response = await client.hashLists.list();

Response

Error Codes

401auth/missing-token
Authentication required. Send your project API key in the X-Api-Key header.
401auth/invalid-api-key
The API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403auth/project-mismatch
This API key belongs to a different project. Use a key created for the project that owns this resource.
404project/not-found
Project not found

Create Hash List

Create a hash list. Image uploads are compared with every list in the project: a `flag` list reports matches, a `block` list also blocks close matches.

OpenAPI YAML
POST
https://api.calmlens.com/v1/projects/
/hash-lists
const response = await client.hashLists.create({
  "name": "Banned images",
  "action": "block"
});

Request Body

Edit any value to update the generated request examples.

string
Display name
ActionEnum
What a match does: flag reports it without changing the decision, block blocks matches 16 bits apart or fewer and flags looser ones
Allowed values
flagblock
string (optional)
What the list is for, such as the policy it enforces

Response

idstring
Unique hash list ID
projectIdstring
ID of the project that owns the list
namestring
Display name
actionActionEnum
What a match does: flag reports it without changing the decision, block blocks matches 16 bits apart or fewer and flags looser ones
Allowed values
flagblock
createdAtnumber
When the list was created, in milliseconds since the Unix epoch
descriptionstring (optional)
What the list is for, such as the policy it enforces
createdByUserIdstring (optional)
ID of the user who created the list
updatedAtnumber (optional)
When the list was last updated, in milliseconds since the Unix epoch

Error Codes

401auth/missing-token
Authentication required. Send your project API key in the X-Api-Key header.
401auth/invalid-api-key
The API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403auth/project-mismatch
This API key belongs to a different project. Use a key created for the project that owns this resource.
404project/not-found
Project not found
409hash-list/limit-reached
This project has the most hash lists it can hold. Delete a list to add another.

Get Hash List

Get a hash list by ID

OpenAPI YAML
GET
https://api.calmlens.com/v1/hash-lists/
const response = await client.hashLists.retrieve({
  "hashListId": "123e4567-e89b-42d3-a456-426614174000"
});

Response

idstring
Unique hash list ID
projectIdstring
ID of the project that owns the list
namestring
Display name
actionActionEnum
What a match does: flag reports it without changing the decision, block blocks matches 16 bits apart or fewer and flags looser ones
Allowed values
flagblock
createdAtnumber
When the list was created, in milliseconds since the Unix epoch
descriptionstring (optional)
What the list is for, such as the policy it enforces
createdByUserIdstring (optional)
ID of the user who created the list
updatedAtnumber (optional)
When the list was last updated, in milliseconds since the Unix epoch

Error Codes

401auth/missing-token
Authentication required. Send your project API key in the X-Api-Key header.
401auth/invalid-api-key
The API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403auth/project-mismatch
This API key belongs to a different project. Use a key created for the project that owns this resource.
404hash-list/not-found
Hash list not found. Check the list ID in the portal.

Update Hash List

Rename a hash list or change what its matches do. The new action applies to later uploads.

OpenAPI YAML
PATCH
https://api.calmlens.com/v1/hash-lists/
const response = await client.hashLists.update({
  "hashListId": "123e4567-e89b-42d3-a456-426614174000",
  "name": "Removed images"
});

Request Body

Edit any value to update the generated request examples.

string (optional)
Display name
string (optional)
ActionEnum (optional)
Allowed values
flagblock

Response

idstring
Unique hash list ID
projectIdstring
ID of the project that owns the list
namestring
Display name
actionActionEnum
What a match does: flag reports it without changing the decision, block blocks matches 16 bits apart or fewer and flags looser ones
Allowed values
flagblock
createdAtnumber
When the list was created, in milliseconds since the Unix epoch
descriptionstring (optional)
What the list is for, such as the policy it enforces
createdByUserIdstring (optional)
ID of the user who created the list
updatedAtnumber (optional)
When the list was last updated, in milliseconds since the Unix epoch

Error Codes

401auth/missing-token
Authentication required. Send your project API key in the X-Api-Key header.
401auth/invalid-api-key
The API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403auth/project-mismatch
This API key belongs to a different project. Use a key created for the project that owns this resource.
404hash-list/not-found
Hash list not found. Check the list ID in the portal.

Delete Hash List

Delete a hash list and every entry in it. Later uploads are no longer compared with it.

OpenAPI YAML
DELETE
https://api.calmlens.com/v1/hash-lists/
const response = await client.hashLists.delete({
  "hashListId": "123e4567-e89b-42d3-a456-426614174000"
});

Error Codes

401auth/missing-token
Authentication required. Send your project API key in the X-Api-Key header.
401auth/invalid-api-key
The API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403auth/project-mismatch
This API key belongs to a different project. Use a key created for the project that owns this resource.
404hash-list/not-found
Hash list not found. Check the list ID in the portal.

List Hash List Entries

Get a page of the hashes in a hash list, newest first

OpenAPI YAML
GET
https://api.calmlens.com/v1/hash-lists/
/entries
const response = await client.hashLists.listEntries({
  "hashListId": "123e4567-e89b-42d3-a456-426614174000",
  "pageSize": 50
});

Query Parameters

Edit any value to update the generated request examples.

string (optional)
The previous page’s nextCursor; omit for the first page
number (optional)

Response

nextCursorstring (optional)
Pass as cursor for the next page; null when no more items remain
pageSizenumber
hasMoreboolean

Error Codes

401auth/missing-token
Authentication required. Send your project API key in the X-Api-Key header.
401auth/invalid-api-key
The API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403auth/project-mismatch
This API key belongs to a different project. Use a key created for the project that owns this resource.
400validation/invalid-cursor
The cursor is invalid or belongs to a different query.
404hash-list/not-found
Hash list not found. Check the list ID in the portal.

Add Hash List Entry

Add a PDQ hash to a hash list, either as a hash or from an image asset. Adding a hash the list already holds returns the existing entry.

OpenAPI YAML
POST
https://api.calmlens.com/v1/hash-lists/
/entries
const response = await client.hashLists.addEntry({
  "hashListId": "123e4567-e89b-42d3-a456-426614174000",
  "assetId": "8f7d2c1e-4b3a-4c5d-9e8f-1a2b3c4d5e6f",
  "label": "Reported spam"
});

Request Body

Edit any value to update the generated request examples.

string (optional)
A PDQ hash to add, as 64 hexadecimal characters. Send this or assetId.
number (optional)
PDQ quality of hash, from 0 to 100. Hashes below 50 are never matched.
string (optional)
An image asset in the same project whose perceptual hash to add. Send this or hash.
string (optional)
Your own note or reference for the entry

Response

idstring
Unique entry ID
projectIdstring
ID of the project that owns the entry
hashListIdstring
ID of the list the entry belongs to
hashstring
PDQ hash of the listed image, as 64 hexadecimal characters
qualitynumber (optional)
PDQ quality of the hash from 0 to 100, or null when it was added without one. Entries below 50 are never matched.
createdAtnumber
When the entry was added, in milliseconds since the Unix epoch
labelstring (optional)
Your own note or reference for the entry
sourceAssetIdstring (optional)
ID of the asset the hash was taken from, when it was added from an asset
createdByUserIdstring (optional)
ID of the user who added the entry

Error Codes

401auth/missing-token
Authentication required. Send your project API key in the X-Api-Key header.
401auth/invalid-api-key
The API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403auth/project-mismatch
This API key belongs to a different project. Use a key created for the project that owns this resource.
404hash-list/not-found
Hash list not found. Check the list ID in the portal.
404asset/not-found
Asset not found
409hash-list/asset-not-hashed
This asset has no perceptual hash. Only image assets that finished processing can be added.
409hash-list/entry-limit-reached
This project's hash lists hold the most entries they can. Remove entries to add more.

Remove Hash List Entry

Remove a hash from its hash list. Later uploads no longer match it.

OpenAPI YAML
DELETE
https://api.calmlens.com/v1/hash-list-entries/
const response = await client.hashLists.removeEntry({
  "entryId": "123e4567-e89b-42d3-a456-426614174000"
});

Error Codes

401auth/missing-token
Authentication required. Send your project API key in the X-Api-Key header.
401auth/invalid-api-key
The API key is invalid, revoked or expired. Create a key under Developer → API Keys.
403auth/project-mismatch
This API key belongs to a different project. Use a key created for the project that owns this resource.
404hash-list/entry-not-found
Hash list entry not found.

Signing in

Signing out

Cookies on CalmLens

We use essential cookies for sign-in and security. With your permission, functional cookies remember your preferences and Google Analytics measures website use and signups. Optional ad measurement cookies link Google ad clicks to signups. Personalised advertising stays off. Manage cookies