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.
See also Common Status Codes. |
---|
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: | 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: | 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.
See also Common Status Codes. |
---|
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.
See also Common Status Codes. |
---|