Smart Filters (called Fingerprints in the API for legacy reasons) enable concept search over Items in a project.

Methods

Fingerprint CRUD

List Fingerprints

GET https://squirro-endpoint/api/topic/v0/(string: tenant)/projects/(id: project_id)/fingerprints

Returns an array of all fingerprints on the project.

Parameters:	tenant – User tenant. project_id – Project identifier.
Headers:	See Common Headers.
Status Codes:	200 – Array of fingerprint dictionaries is returned. See also Common Status Codes.
Returns:	Array of fingerprints. Only the permanent fingerprints are returned (where `temporary` is `false`). [ { "temporary": false, "name": "WBC-AX", "noise_level": null, "type_id": "lgw6KXANRnKJOTM9MCShpg", "title": "WBC.AX", "manual": false, "locked": false, "type": "project", "tags": "stock" } ]

Create Unnamed Fingerprint

POST https://squirro-endpoint/api/topic/v0/(string: tenant)/fingerprint/{string: type}/{string: type_id}

Creates a new, empty and temporary fingerprint. The fingerprint can be trained separately and to save it permanently, it will need to be moved.

Parameters:	tenant – User tenant. type – Type of the resource to which the fingerprint is attached. Valid values: `project`. type_id – Resource identifier to which the fingerprint is attached. Commonly the project identifier.
JSON Data:	Data is passed in as a JSON object. Valid object keys (all optional): title – Title of the fingerprint, as shown to users in the user interface. tags – Comma-separated list of tags of this fingerprint. These tags can be used for filtering the fingerprints on query time. manual – True if this is a manual fingerprint. Manual fingerprints are not trained through content but have a string field `manual_features` in the config dictionary which contains all the tokens. noise_level – The default noise level to use for this fingerprint. Must be a number between 0 and 1. config – A dictionary with the following possible object keys: smartfilter_query – gdfs_type – default_manual_features_lang – manual_features – max_features_per_language – exclude_features –
Headers:	See Common Headers.
Status Codes:	201 – Fingerprint created. See also Common Status Codes.
Returns:	The created fingerprint. { "config": { "features": {}, "filter_min_score": null, "default_manual_features_lang": null, "gdfs_type": "", "coefficients": { "item_recentness": 0.0, "item_score": 0.0, "item_lang": 0.0, "features_similarity": 1.0 }, "basetopic": [], "smartfilter_query": null, "manual_features": null, "items": [], "max_features_per_language": 30, "exclude_features": {}, "negative_items": [], "features_similarity_score_min": null, "features_similarity_score_max": null, "content": [] }, "temporary": true, "name": "smart-filter-2", "noise_level": null, "tags": null, "type_id": "lgw6KXANRnKJOTM9MCShpg", "manual": false, "title": "WBC.AX", "type": "project", "locked": false }

Get Fingerprint

GET https://squirro-endpoint/api/topic/v0/(string: tenant)/fingerprint/{string: type}/{string: type_id}/{string: name}

Returns details of a fingerprint.

Parameters:	tenant – User tenant. type – Type of the resource to which the fingerprint is attached. Valid values: `project`. type_id – Resource identifier to which the fingerprint is attached. Commonly the project identifier. name – Fingerprint name.
Headers:	See Common Headers.
Status Codes:	200 – Fingerprint returned. See also Common Status Codes.
Returns:	The fingerprint. { "temporary": false, "name": "WBC-AX", "noise_level": null, "tags": null, "type": "project", "title": "WBC.AX", "manual": false, "records": { "positive": [ { "lang": "en", "text": "Westpac Banking Corporation (Westpac), is a banking organization. Westpac provides …", "created_at": "2014-12-16T17:28:58", "id": "L1H8BxRGRgakrrs_Dmbg_A", "source": "content" } ] }, "type_id": "lgw6KXANRnKJOTM9MCShpg", "locked": false, "config": { "smartfilter_query": null, "features": { "en": [ { "weight": 4.7, "value": "\"financial service\"", "label": "\"financial services\"" }, { "weight": 4.6, "value": "\"westpac banking\"", "label": "\"Westpac Banking\"" }, { "weight": 4.4, "value": "westpac", "label": "Westpac" } ] }, "exclude_features": {}, "items": [], "max_features_per_language": 30, "negative_items": [], "content": [ { "lang": "en", "text": "Westpac Banking Corporation (Westpac), is a banking organization. Westpac provides …", "created_at": "2014-12-16T17:28:58", "id": "L1H8BxRGRgakrrs_Dmbg_A", "source": "content" } ], "features_similarity_score_min": null, "filter_min_score": null, "features_similarity_score_max": null, "default_manual_features_lang": null, "gdfs_type": "", "manual_features": null, "coefficients": { "item_recentness": 0.0, "item_score": 0.0, "item_lang": 0.0, "features_similarity": 1.0 }, "basetopic": [] } }

Create Named Fingerprint

POST https://squirro-endpoint/api/topic/v0/(string: tenant)/fingerprint/{string: type}/{string: type_id}/{string: name}

Creates a new, empty and temporary fingerprint with a specific name. The fingerprint can be trained separately and to save it permanently, it will need to be moved.

Parameters:	tenant – User tenant. type – Type of the resource to which the fingerprint is attached. Valid values: `project`. type_id – Resource identifier to which the fingerprint is attached. Commonly the project identifier. name – Fingerprint name. The name is limited to alphanumeric characters and the dash and underscore.
JSON Data:	Data is passed in as a JSON object. The same data is valid as for the Create Unnamed Fingerprint method.
Headers:	See Common Headers.
Status Codes:	201 – Fingerprint created. 209 – A fingerprint of this name already exists. See also Common Status Codes.
Returns:	The created fingerprint. { "config": { "features": {}, "filter_min_score": null, "default_manual_features_lang": null, "gdfs_type": "", "coefficients": { "item_recentness": 0.0, "item_score": 0.0, "item_lang": 0.0, "features_similarity": 1.0 }, "basetopic": [], "smartfilter_query": null, "manual_features": null, "items": [], "max_features_per_language": 30, "exclude_features": {}, "negative_items": [], "features_similarity_score_min": null, "features_similarity_score_max": null, "content": [] }, "temporary": true, "name": "WBC-AX", "noise_level": null, "tags": null, "type_id": "lgw6KXANRnKJOTM9MCShpg", "manual": false, "title": "WBC.AX", "type": "project", "locked": false }

Update Fingerprint

PUT https://squirro-endpoint/api/topic/v0/(string: tenant)/fingerprint/{string: type}/{string: type_id}/{string: name}

Updates a fingerprint.

Parameters:	tenant – User tenant. type – Type of the resource to which the fingerprint is attached. Valid values: `project`. type_id – Resource identifier to which the fingerprint is attached. Commonly the project identifier. name – Fingerprint name.
JSON Data:	Data is passed in as a JSON object. The same data is valid as for the Create Unnamed Fingerprint method.
Headers:	See Common Headers.
Status Codes:	200 – Fingerprint updated. See also Common Status Codes.
Returns:	The modified fingerprint. { "config": { "features": {}, "filter_min_score": null, "default_manual_features_lang": null, "gdfs_type": "", "coefficients": { "item_recentness": 0.0, "item_score": 0.0, "item_lang": 0.0, "features_similarity": 1.0 }, "basetopic": [], "smartfilter_query": null, "manual_features": null, "items": [], "max_features_per_language": 30, "exclude_features": {}, "negative_items": [], "features_similarity_score_min": null, "features_similarity_score_max": null, "content": [] }, "temporary": true, "name": "WBC-AX", "noise_level": null, "tags": null, "type_id": "lgw6KXANRnKJOTM9MCShpg", "manual": false, "title": "WBC.AX", "type": "project", "locked": false }

Delete Fingerprint

DELETE https://squirro-endpoint/api/topic/v0/(string: tenant)/fingerprint/{string: type}/{string: type_id}/{string: name}

Deletes the fingerprint of the given name.

Parameters:

tenant – User tenant.
type – Type of the resource to which the fingerprint is attached. Valid values: project.
type_id – Resource identifier to which the fingerprint is attached. Commonly the project identifier.
name – Fingerprint name.

Headers: See Common Headers.

Status Codes:

204 – Fingerprint deleted.

Copy Fingerprint

POST https://squirro-endpoint/api/topic/v0/(string: tenant)/fingerprint/{string: type}/{string: type_id}/{string: name}/copy

Creates a copy of the fingerprint with a new name. The resulting copy is temporary fingerprint with a specific name. To save it permanently, it needs to be moved.

Parameters:	tenant – User tenant. type – Type of the resource to which the fingerprint is attached. Valid values: `project`. type_id – Resource identifier to which the fingerprint is attached. Commonly the project identifier. name – Fingerprint name.
Headers:	See Common Headers.
Status Codes:	201 – Fingerprint created. 209 – A fingerprint of this name already exists. See also Common Status Codes.
Returns:	The new fingerprint. { "config": { "features": {}, "filter_min_score": null, "default_manual_features_lang": null, "gdfs_type": "", "coefficients": { "item_recentness": 0.0, "item_score": 0.0, "item_lang": 0.0, "features_similarity": 1.0 }, "basetopic": [], "smartfilter_query": null, "manual_features": null, "items": [], "max_features_per_language": 30, "exclude_features": {}, "negative_items": [], "features_similarity_score_min": null, "features_similarity_score_max": null, "content": [] }, "temporary": true, "name": "WBC-AX-copy-4", "noise_level": null, "tags": null, "type_id": "lgw6KXANRnKJOTM9MCShpg", "manual": false, "title": "WBC.AX", "type": "project", "locked": false }

Move Fingerprint

POST https://squirro-endpoint/api/topic/v0/(string: tenant)/fingerprint/{string: type}/{string: type_id}/{string: name}/move

Moves a fingerprint over an existing fingerprint. The resulting copy is temporary fingerprint with a specific name. Moving results in the fingerprint being permanent, so this action needs to be executed on a temporary fingerprint to save it permanently.

Parameters:	tenant – User tenant. type – Type of the resource to which the fingerprint is attached. Valid values: `project`. type_id – Resource identifier to which the fingerprint is attached. Commonly the project identifier. name – Fingerprint name.
JSON Data:	Data is passed in as a JSON object. Valid object keys: target_name (mandatory) – Target name to move the fingerprint to. This can be equal to the current fingerprint name in which case the fingerprint is simply switched from temporary to permanent status.
Headers:	See Common Headers.
Status Codes:	201 – Fingerprint moved. See also Common Status Codes.
Returns:	The fingerprint. { "config": { "features": {}, "filter_min_score": null, "default_manual_features_lang": null, "gdfs_type": "", "coefficients": { "item_recentness": 0.0, "item_score": 0.0, "item_lang": 0.0, "features_similarity": 1.0 }, "basetopic": [], "smartfilter_query": null, "manual_features": null, "items": [], "max_features_per_language": 30, "exclude_features": {}, "negative_items": [], "features_similarity_score_min": null, "features_similarity_score_max": null, "content": [] }, "temporary": false, "name": "WBC-AX", "noise_level": null, "tags": null, "type_id": "lgw6KXANRnKJOTM9MCShpg", "manual": false, "title": "WBC.AX", "type": "project", "locked": false }

Change Fingerprint Locking

PUT https://squirro-endpoint/api/topic/v0/(string: tenant)/fingerprint/{string: type}/{string: type_id}/{string: name}/protection

Changes the locking state of a fingerprint. A locked fingerprint can not be modified, except if the lock is first remove.

Parameters:	tenant – User tenant. type – Type of the resource to which the fingerprint is attached. Valid values: `project`. type_id – Resource identifier to which the fingerprint is attached. Commonly the project identifier. name – Fingerprint name.
JSON Data:	Data is passed in as a JSON object. Valid object keys: locked (mandatory) – Boolean value indicating if the fingerprint should be locked.
Headers:	See Common Headers.
Status Codes:	200 – Locking updated. See also Common Status Codes.

Validate Fingerprint

POST https://squirro-endpoint/api/topic/v0/fingerprint/validate

Validates a fingerprint without saving. This is useful when providing an editing interface for the manual fingerprint to give the user some feedback.

JSON Data:	Data is passed in as a JSON object. Valid object keys: target_name (mandatory) – Target name to move the fingerprint to. This can be equal to the current fingerprint name in which case the fingerprint is simply switched from temporary to permanent status.
Headers:	See Common Headers.
Status Codes:	200 – Fingerprint is valid. 400 – Fingerprint is not valid. A list of errors is returned. See also Common Status Codes.
Returns:	The validation result. In case of success: en empty dictionary. {} In case of an attribute error an error message is returned: {"error": "invalid attribute value"} If the manual features have an error, a list of errors is returned: [ { "line": 1, "value": "foo,en", "error": "weight must be numeric" } ]

Training

Fingerprints are trained with text documents.

Train from Text

POST https://squirro-endpoint/api/topic/v0/(string: tenant)/fingerprint/{string: type}/{string: type_id}/{string: name}/content

Adds a new training document to the fingerprint.

Parameters:	tenant – User tenant. type – Type of the resource to which the fingerprint is attached. Valid values: `project`. type_id – Resource identifier to which the fingerprint is attached. Commonly the project identifier. name – Fingerprint name.
JSON Data:	Data is passed in as a JSON list. Each list entry is a dictionary with these keys: text – The text of the training document. May contain HTML, which is stripped out. Either `text` or `data` must be provided. data – Base64-encoded content of a document. Text is extracted from this document if possible. Either `text` or `data` must be provided. mime – Specifies the MIME type of the `data` field. Mandatory if `data` is provided. lang (optional) – Two-letter language code specifying the language of the training data. This is auto-detected from the data if it not specified.
Headers:	See Common Headers.
Status Codes:	204 –Training document added and fingerprint updated. See also Common Status Codes.

Update Training from Content

POST https://squirro-endpoint/api/topic/v0/(string: tenant)/fingerprint/{string: type}/{string: type_id}/{string: name}/content/{string: record_id}

Edits a training document in the fingerprint.

Parameters:	tenant – User tenant. type – Type of the resource to which the fingerprint is attached. Valid values: `project`. type_id – Resource identifier to which the fingerprint is attached. Commonly the project identifier. name – Fingerprint name. record_id – Record identifier. This is the `id` field from the `content` list in the fingerprint details.
JSON Data:	Data is passed in as a JSON object. The same input is used as the individual entries of Train from Text.
Headers:	See Common Headers.
Status Codes:	204 –Training document and fingerprint updated. See also Common Status Codes.

Delete Training Content

DELETE https://squirro-endpoint/api/topic/v0/(string: tenant)/fingerprint/{string: type}/{string: type_id}/{string: name}/content/{string: record_id}

Deletes a training document from the fingerprint.

Parameters:

tenant – User tenant.
type – Type of the resource to which the fingerprint is attached. Valid values: project.
type_id – Resource identifier to which the fingerprint is attached. Commonly the project identifier.
name – Fingerprint name.
record_id – Record identifier. This is the id field from the content list in the fingerprint details.

Headers: See Common Headers.

Status Codes:

204 –Training document deleted and fingerprint updated.

Train from Item

POST https://squirro-endpoint/api/topic/v0/(string: tenant)/fingerprint/{string: type}/{string: type_id}/{string: name}/items

A Squirro item can be added directly to a fingerprint for training with this method.

Parameters:	tenant – User tenant. type – Type of the resource to which the fingerprint is attached. Valid values: `project`. type_id – Resource identifier to which the fingerprint is attached. Commonly the project identifier. name – Fingerprint name.
JSON Data:	Data is passed in as a JSON object. Valid object keys: item_ids – List of item identifiers to add to the fingerprint as training. The text from these items is used as training content. negative – Boolean, default false. If true, the item as added as a negative training document, reducing the score of the words that occur in this item.
Headers:	See Common Headers.
Status Codes:	204 – Items added and fingerprint updated. See also Common Status Codes.

Delete Training Item

DELETE https://squirro-endpoint/api/topic/v0/(string: tenant)/fingerprint/{string: type}/{string: type_id}/{string: name}/items/{string: record_id}

Deletes a training item from the fingerprint.

Parameters:

tenant – User tenant.
type – Type of the resource to which the fingerprint is attached. Valid values: project.
type_id – Resource identifier to which the fingerprint is attached. Commonly the project identifier.
name – Fingerprint name.
record_id – Record identifier. This is the id field from the content list in the fingerprint details.

Headers: See Common Headers.

Status Codes:

204 –Training item deleted and fingerprint updated.