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://topic-api.squirro.com/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://topic-api.squirro.com/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://topic-api.squirro.com/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://topic-api.squirro.com/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://topic-api.squirro.com/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://topic-api.squirro.com/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.
See also Common Status Codes.
|
Copy Fingerprint
POST https://topic-api.squirro.com/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://topic-api.squirro.com/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: |
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://topic-api.squirro.com/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: |
See also Common Status Codes.
|
Validate Fingerprint
POST https://topic-api.squirro.com/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://topic-api.squirro.com/v0/(string: tenant)/fingerprint/{string: type}/{string: type_id}/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://topic-api.squirro.com/v0/(string: tenant)/fingerprint/{string: type}/{string: type_id}/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://topic-api.squirro.com/v0/(string: tenant)/fingerprint/{string: type}/{string: type_id}/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.
See also Common Status Codes.
|
Train from Item
POST https://topic-api.squirro.com/v0/(string: tenant)/fingerprint/{string: type}/{string: type_id}/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://topic-api.squirro.com/v0/(string: tenant)/fingerprint/{string: type}/{string: type_id}/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.
See also Common Status Codes.
|