Getting started
Check out the demo to see Ingenia in action.
Look at the FAQ for any questions.
Go through the documentation and choose if you want to use Ingenia by the API or with the Ruby gem.
Contact us to get your API key or if you have any questions.
If you would like to verify your API key or code data path then use the status call.
Ruby API library
https://github.com/ingenia-api/ingenia_rubyRate limiting
Ingenia by default limits a user to 4 calls per second, for every type of API call. Contact us to have this limit increased or removed if needed.
Endpoint
All calls are made with the following end point
api.ingeniapi.com/v2/
Both HTTP and HTTPS are supported as protocols. JSON is the data encapsulation format
Basic response format
All responses from the API gateway have the following format
Fields
Name | Type | Description |
---|---|---|
version |
string
|
The version of the API that is responding
Example"2.0" |
data |
object
|
The data payload response from the call |
status |
string
|
"okay" if the call is processed correctly, otherwise it will be "error" |
message |
string
|
A message describing the nature of the error, returned if an error occurred |
Data structures
Item: create / update input
An item is a block of text to which you can associate tags, that belongs to a bundle
Fields
Name | Type | Description |
---|---|---|
id |
string
|
An alphanumeric id unique to each item within a bundle. You can use your own, or have Ingenia generate one for you. Note: Can NOT contain commas.
Example785uU423aC |
text |
string
|
Your item's content. [1] |
url |
string
|
Source URL to get text from. Ingenia will extract the most relevant text [1]
Examplehttps://www.example.com |
bundle_id |
integer
|
ID of the bundle in which to put the item |
tag_sets |
hash
|
A hash of tag sets, each of which is an array of tags that you consider of the same type [2]
Example{ "topics": [ "startups", "saas", "marketing" ], "geography": [ "United Kingdom", "Italy" ] } |
tags |
array
|
An array with the name of the tags you wish to assign to this item. If the tag doesn't exist, it will be created [2].
Example[ "startups", "saas", "marketing" ]' |
tags |
hash
|
As above, but with a user-assigned score. The score should be a number between 0 and 1 that quantifies the strength of the association between the item and the tag (1: highest) [2].
Example{ "startups" : 0.2 , "sass" : 0.7, "marketing" : 1 } |
tag_ids |
array
|
The Ingenia IDs of the tags you wish to assign to this item [2]
Example[ 45, 787, 23 ] |
language |
string
|
The ISO639-2 code for language (see the full list at http://www.loc.gov/standards/iso639-2/php/English_list.php), in lower case.
This enables you to ensure Ingenia processes this content in that language.
If not passed, Ingenia assumes the language is the same as the bundle to which the item belongs.
If 'auto', Ingenia will automatically detect the language: especially useful for multi-language bundles.
Example'en' |
metadata |
array
|
A list of attributes you can associate to the knowledge item.
Valid types of metadata are date, string, collection and number.
'date': which includes a time for when an event occurred
'string': General purpose content
'collection': One item from defined collection
'number': A numerical value
Example[{ name: 'published_date', type: 'date', content: '2012-01-20 00:00:00' }, { name: 'title', type: 'string', content: 'A day to remember', { name: 'author', type: 'collection', content: 'Joe Bloggs' }, { name: 'author', type: 'collection', content: 'John Smith' }] |
delimiters |
array
|
A list of characters or words that Ingenia will use to split the text you send into smaller blocks. This is useful if you want to identify and analyse tags at a per-sentence level. For instance, you may break down the text: 'The staff were friendly, but the food was disappointing' into two by splitting on the word ' but ': i.e. The first part of the text could be categorised as 'staff' and 'positive' and the second part as 'room' and 'negative', thus enabling you to identify granularly which specific features are or are not appreciated. You can send an empty array in order to use the default set of delimiters to split the text: ['. ', '? ', '! ', ' ']. Please note, you will need to specify for each delimiters whether to require a subsequent space. i.e. [':'] is not the same as [': ']. This also applies to using words. i.e. splitting on ['but'] is not the same as [' but ']. Example['. ', ' but ']
This would split the following text: "I liked it overall. The food was good but the service could be improved."
into three separate chunks:
"I liked it overall"
"The food was good"
"the service could be improved." |
Notes
[1] You can input content as one of these fields: text, a URL, a file. Formats supported for files include txt, html, pdf and all MS Office formats. If you send a file, it will extract the text from it.
The text and the URL are input as part of the JSON component. The file is sent as a multipart encoded https field.
[2] Only specify one of the following: tag_sets, tags or tag_ids
Example
{ text: "High tech startups and their positive power to change for good", tag_sets: { "Topics": [ "startups", "technology" ], "Mood": [ "positive" ] } }
Item: show output
Fields
Name | Type | Description |
---|---|---|
bundle_id |
numeric
|
The id of the bundle that this item belongs to |
bundle_name |
string
|
The name of the bundle that this item belongs to |
concordance |
float
|
The extent to which the user and Ingenia agree on the categorisation of the item. 0 if the tags are different, 1 if they are identical. Use this to identify content that may need to be reviewed |
id |
string
|
A unique alphanumeric id
Example785uU423aC |
item_state |
string
|
The current state of the item |
language |
string
|
The language of the content in this item |
text |
string
|
Your item's content |
created_at |
date_time
|
When this item was created
Example2013-12-16T11:24:52+00:00 |
updated_at |
date_time
|
When this item was last updated
Example2013-12-16T11:25:52+00:00 |
last_classified_at |
date_time
|
When this item was last classified by the system; null if it hasn't been classified yet
Example2013-12-16T11:25:52+00:00 |
tag_sets |
array
|
An array of tag sets associated to the item |
tag_set |
hash
|
A hash containing the tag set id and the array of tags associated to the item |
tag |
hash
|
A hash with the details of a tag associated to the item, including its id, name, user assigned score and user_selected |
score |
numeric
|
An aggregation of the machine and rule scores, between 0 (lowest) and 1 (highest). |
user_selected |
string
|
Deprecated: please use user_assigned value, this will be removed in the next release |
user_assigned |
boolean
|
true if the tag was assigned to the item by the user, false if it was assigned by Ingenia |
user_assigned_score |
float
|
score assigned by the user when tag was created |
machine_score |
numeric
|
A number which quantifies the strength of the association between an item and a tag, between 0 (lowest) and 1 (highest) |
rule_score |
numeric
|
A number which quantifies the strength of the association between an item and a tag score, between -1 (lowest) and 1 (highest) |
membership_degree |
float
|
the degree to which this item is a member of its bundle |
metadata |
array
|
any additional data you associated to this content; it may include dates, values, urls, additional text, etc. |
aggregated_items |
array
|
This only appears for items that have been split using delimiters defined during item creation. It is a list of the component items that make up the overall text. |
partial_id |
string
|
If there are aggregated_items present, each will have a partial_id to uniquely identify it. This will be an alphanumeric string containing the overall item id, a number representing its position in the original text, and a unique identifier
Example6bbd66632349f38b87af3cb8b370a481_00001_e64305ac4dfe6168e52f1afb32e713d5 ------> overallitemid_positionintext_uniqueidentifier |
Example
{ "id":"e19e134d0e79153349ff78a674283e0b", "last_classified_at":2013-12-16T11:25:07+00:00, "text":"How to get to scale with a saas startup in the UK? ...", "tag_sets": [ { "topics": { "id":156, "tags": [ { "id":4352, "name":"startups", "user_selected": "f", "user_assigned": false, "score":"0.8", "machine_score":"0.45", "rule_score": "0.35", "user_assigned_score": null }, { "id": 7811, "name": "saas", "user_selected": "t", "user_assigned": true, "score": "0.45", "machine_score":"0.45", "rule_score": null, "user_assigned_score": 0.7 }, { "id":1327, "name":"marketing", "user_selected": "t", "user_assigned": true, "score": "0.50", "machine_score":"0.45", "rule_score": "0.05", "user_assigned_score": 0.7 } ] } }, { "geography": { "id":622, "tags": [ { "id":3321, "name":"united kingdom", "score":"0.37", "user_selected": "t", "user_assigned": true } ] } } ] "created_at":"2013-12-16T11:24:52+00:00", "updated_at":"2013-12-16T11:24:56+00:00" }
Bundle: create / update input
A collection of items related to each other
Fields
Name | Type | Description |
---|---|---|
name |
string
|
The name of your bundle |
tag_set_ids |
array
|
An array of tag set IDs to be applied to this bundle. The tags in these tag sets will be available to the items in the bundle. If an existing bundle already has tag sets, then these can be removed by omitting the ID in the call. |
Example
{ "name":"Tech Startups", "tag_sets": [ { "id" : 2820, "name" : "Tag Set One" }, { "id" : 2819, "name" : "Tag Set Two" } ] }
Bundle: show output
A collection of items related to each other
Fields
Name | Type | Description |
---|---|---|
id |
numeric
|
A unique numeric id generated by Ingenia |
name |
string
|
The name of your bundle |
tag_sets |
array
|
The tag sets that are currently attached to this bundle. Items within the bundle can use all the tags in these tag sets. |
created_at |
date_time
|
When this bundle was created
Example2013-12-16T11:24:52+00:00 |
updated_at |
date_time
|
When this bundle was last updated
Example2013-12-16T11:25:52+00:00 |
Example
{ "id":47858, "name":"Tech Startups", "tag_sets": [ { "name": "technology", "id": 14562 }, { "name": "business", "id": 666 } ], "created_at":"2014-03-13T15:36:51Z", "updated_at":"2014-03-13T15:36:51Z", }
Tag: create / update input
Something you want to associate to an item, e.g., a concept, topic, tone, sentiment, keyword, person, company, product, etc.
Fields
Name | Type | Description |
---|---|---|
name |
string
|
The name of your tag; we advise to make it short but meaningful; unique to each tag set |
tag_set_id |
integer
|
The ID of the tag_set to which this tag belongs. REQUIRED. |
description |
string
|
A description of this tag: this is helpful to define in a focused way how the tag should be used |
disposition |
float
|
The disposition of the tag. Float value between 0 and 1, defaults to 0.5. Lower values will tend to privilege precision (we suggest 0.25); higher values will tend to privilege recall (we suggest 0.75). For most uses, the default value will work well. You will want to privilege precision (with a disposition < 0.5) if you want each tag assignment to be accurate, and are less worried about some items being missed, i.e., you prefer to have false negatives than false positives. If the disposition is 0, no item will be tagged with this tag. You will want to privilege recall (with a disposition > 0.5) if you want each tag assignment to occur, and are less worried about some items being tagged incorrectly, i.e., you prefer to have false positives than false negatives. If the disposition is 1, all items will be tagged with this tag. |
Example
{ "name":"Text Analytics", "tag_set_id":37874, "description":"A set of techniques designed to extract valuable information from textual content", "disposition": 0.5 }
Tag: show output
Something you want to associate to an item, e.g., a concept, topic, tone, sentiment, keyword, person, company, product, etc.
Fields
Name | Type | Description |
---|---|---|
id |
numeric
|
A unique numeric id, generated by Ingenia |
name |
string
|
The name of your tag |
tag_set_id |
integer
|
The ID of the tag_set to which this tag belongs |
confidence |
float
|
From 0 to 1; confidence gets closer to 1 the more Ingenia considers the training for this tag sufficient; if this value is low, we advise to increase your training set for this tag |
description |
string
|
A description of this tag |
created_at |
date_time
|
When this tag was created
Example2013-12-16T11:24:52+00:00 |
updated_at |
date_time
|
When this tag was last updated
Example2013-12-16T11:25:52+00:00 |
significant_words |
array
|
Up to 5 words or phrases closely associated with this tag. Useful to understand the 'meaning' of the tag. |
tag_relationships |
array
|
The other tags to which the current one is similar, either because of its name (relationship_type: by_name), or because of how it has been assigned to the content (relationship_type: by_assignment); each presented with related tag_id and its name, the relationship type, and a value between 0 and 1 that quantifies the closeness of the relationship, where 1 is highest. Most used to deduplicate your tags, or to identify interesting relationships. |
Example
{ "id": 192745, "name": "Finance", "created_at": "2017-09-18T13:15:16.407Z", "updated_at": "2017-09-18T14:49:40.259Z", "tag_set_id": 4564, "confidence": 0.85, "current_state": "processed", "description": "", "significant_words": [ { "text": "finance" }, { "text": "bank" }, { "text": "accounts" }, { "text": "capital markets" }, { "text": "fintech" } ], "tag_relationships": [ { "related_tag_id": 191711, "related_tag_name": "Economics", "relationship_type": "by_assignment", "value": 0.74 }, { "related_tag_id": 194712, "related_tag_name": "Fintech", "relationship_type": "by_name", "value": 0.66 } ] }
Tag rules: index output
A list of rules applied to a tag to influence whether or not to apply the tag to an item.
Fields
Name | Type | Description |
---|---|---|
tag_id |
integer
|
The ID of the tag to which this tag rule belongs |
text |
string
|
the word or phrase that influences the "target tag" |
language |
string
|
the language for "text" (optional, required if you pass the "text" parameter |
rule_tag_id |
integer
|
the id of the "rule tag", or the tag that influences the "target tag" |
influence |
float
|
the extent to which the "target tag" is influenced by either "text" or "rule tag", a number between -1 (greatest effect to prevent "target tag" from being applied) to 1 (greatest effect to ensure "target tag" is applied). |
tag_rule_mode |
string
|
A the way in which the rule is being applied. These modes are supported: 'word_present': apply "influence" to the "target tag" if the "text" is present 'word_absent': apply "influence" to the "target tag" if the "text" is absent 'word_skip': ignore this "text", if it is present ("influence" is not used in this mode) 'word_cap': cap the role of "text" for the "target tag" to at most the value of "influence" 'tag_present': apply "influence" to the "target tag" if the "rule_tag" is present (Note: this is useful to create hierarchies: "target_tag" is a parent, "rule_tag" is a child, "influence" is 1) |
created_at |
date_time
|
When this tag rule was created
Example2013-12-16T11:24:52+00:00 |
updated_at |
date_time
|
When this tag rule was last updated
Example2013-12-16T11:25:52+00:00 |
Example
{ "tag": { "id":554273, "name":"Text Analytics", }, "tag_rule": [{ "text": "data", "influence": 0.4, "language": "en", "tag_rule_mode":"word_present", "created_at":"2014-03-13T12:59:32Z", "updated_at":"2014-03-13T12:59:32Z" }, ... ] }
Tag Rule: show output
A rule applied to a tag to influence whether or not to apply the tag to an item.
Fields
Name | Type | Description |
---|---|---|
tag_id |
integer
|
The ID of the tag to which this tag rule belongs |
text |
string
|
the word or phrase that influences the "target tag" |
language |
string
|
the language for "text" (optional, required if you pass the "text" parameter |
rule_tag_id |
integer
|
the id of the "rule tag", or the tag that influences the "target tag" |
influence |
float
|
the extent to which the "target tag" is influenced by either "text" or "rule tag", a number between -1 (greatest effect to prevent "target tag" from being applied) to 1 (greatest effect to ensure "target tag" is applied). |
tag_rule_mode |
string
|
A the way in which the rule is being applied. These modes are supported: 'word_present': apply "influence" to the "target tag" if the "text" is present 'word_absent': apply "influence" to the "target tag" if the "text" is absent 'word_skip': ignore this "text", if it is present ("influence" is not used in this mode) 'word_cap': cap the role of "text" for the "target tag" to at most the value of "influence" 'tag_present': apply "influence" to the "target tag" if the "rule_tag" is present (Note: this is useful to create hierarchies: "target_tag" is a parent, "rule_tag" is a child, "influence" is 1) |
created_at |
date_time
|
When this tag rule was created
Example2013-12-16T11:24:52+00:00 |
updated_at |
date_time
|
When this tag rule was last updated
Example2013-12-16T11:25:52+00:00 |
Example
{ "tag": { "id":554273, "name":"Text Analytics", }, "tag_rule": { "text": "data", "influence": 0.4, "language": "en", "tag_rule_mode":"word_present", "created_at":"2014-03-13T12:59:32Z", "updated_at":"2014-03-13T12:59:32Z" } }
Tag rule: create input
A rule to apply to a tag to influence use of that tag.
Fields
Name | Type | Description |
---|---|---|
tag_id |
integer
|
The ID of the tag to which this tag rule belongs |
text |
string
|
the word or phrase that influences the "target tag" |
language |
string
|
the language for "text" (optional, required if you pass the "text" parameter |
rule_tag_id |
integer
|
the id of the "rule tag", or the tag that influences the "target tag" |
influence |
float
|
the extent to which the "target tag" is influenced by either "text" or "rule tag", a number between -1 (greatest effect to prevent "target tag" from being applied) to 1 (greatest effect to ensure "target tag" is applied). |
tag_rule_mode |
string
|
A the way in which the rule is being applied. These modes are supported: 'word_present': apply "influence" to the "target tag" if the "text" is present 'word_absent': apply "influence" to the "target tag" if the "text" is absent 'word_skip': ignore this "text", if it is present ("influence" is not used in this mode) 'word_cap': cap the role of "text" for the "target tag" to at most the value of "influence" 'tag_present': apply "influence" to the "target tag" if the "rule_tag" is present (Note: this is useful to create hierarchies: "target_tag" is a parent, "rule_tag" is a child, "influence" is 1) |
Notes
[1] A tag rule must include either an entry for the tuple "text" and "language", or for "rule tag", but NOT both.
[2] You can associate as many rules as you like to a tag. Do so cautiously, and make sure they work well together, or you risk to apply the target tag all the time, or never.
Example
{ "text":"ruby", "influence":0.5, "language":"en", "tag_rule_mode":"word_present" } OR { "influence":0.5, "rule_tag_id":12, "tag_rule_mode":"tag_present" }
Tag set: create / update input
A collection of thematically consistent tags
Fields
Name | Type | Description |
---|---|---|
name |
string
|
The name of your tag set; we advise to make it short but meaningful; must be unique |
bundle_ids |
array
|
A list of the ids of bundles to which the tag set should be associated. Can be left blank if tag set should not be associated to any just yet. |
Example
{ "name" : "Big Data" "bundle_ids" : "[42, 56]" }
Tag set: show output
A collection of thematically consistent tags
Fields
Name | Type | Description |
---|---|---|
id |
numeric
|
A unique numeric id, generated by Ingenia |
name |
string
|
The name of your tag set |
created_at |
date_time
|
When this tag set was created
Example2013-12-16T11:24:52+00:00 |
updated_at |
date_time
|
When this tag set was last updated
Example2013-12-16T11:25:52+00:00 |
bundles |
array
|
A list of bundles associated to this tag set |
Example
{ "id":178751, "name":"Big Data", "created_at":"2014-03-12T12:17:33Z", "updated_at":"2014-03-12T12:17:33Z", "bundles": [ { "id": 778, "name": "A Bundle Name" } ] }
Similarity response
An array of items that are related to an origin item sent via a similarity API call
Fields
Name | Type | Description |
---|---|---|
id |
string
|
The ID of the origin item |
text |
string
|
First 50 characters of the text of each related item |
mode |
string
|
If 'tag', it will determine related items on the basis of their tags; if 'word', it will do so on the basis of the words contained in the item |
similarity |
float
|
From 0 to 1, it measures how similar each related item is to the origin item; the response will sort items on descending similarity |
Example
{ [ { "item": { "id":12182, "text": "The fall in the rand has given wealthy Russians a new location to search for luxury..." }, "mode": "tag", "similarity": 0.62 }, { "item": { "id":9293, "text": "Robots tend to do jobs that no one wants to do. I am old enough to remember..." }, "mode": "tag", "similarity": 0.55 }, { "item": { "id":25333, "text": "The market for RMB credit raised outside China has gone four weeks without a..." }, "mode": "word", "similariy": 0.22 } ] }
API calls
Classifications
Classify
Path
POST
api.ingeniapi.com/v2/classifyParameters
Name | Type | Description |
---|---|---|
text |
string
|
The text you want Ingenia to classify [1]
ExampleA comparative study of European secondary education systems illustrated issues related to their budgetary sustainability... |
url |
string
|
The source URL from which to extract the text to be classified; Ingenia will extract the most relevant text [1]
Examplehttps://www.example.com |
file |
multipart
|
File to be used as text source. Sent as multipart upload. Accepted file extensions are: Text (txt), Postscript Document Format (pdf) and Microsoft Office Documents (doc, docx, xlsx, ppt, pptx). [1]
Exampledocument.pdf |
bundle_id |
integer
|
ID of the bundle to which the item belongs
Default[user's first bundle] |
min_tags |
integer
|
Return at least these many tags, up to a maximum of 1000.
Default0 |
max_tags |
integer
|
Return at most these many tags, up to a maximum of 1000.
Default6 |
Notes
[1] You can input content as one of these fields: text, a URL, a file. Formats supported for files include txt, html, pdf and all MS Office formats. If you send a file, it will extract the text from it.
The text and the URL are input as part of the JSON component. The file is sent as a multipart encoded https field.
curl -X POST 'https://api.ingeniapi.com/v2/classify?text=A%20comparative%20study%20of%20European%20secondary%20education%20systems%20illustrated%20issues%20related%20to%20their%20budgetary%20sustainability&api_key=$api_key' Response: { "classification_status": "complete", "text": "A comparative study of European secondary education systems illustrated issues related to their budgetary sustainability", "results": { "Themes": { "tags": [ { "machine_score": -0.15, "name": "Ed-tech", "id": 174857, "rule_score": 0.21, "score": 0.06 } ], "id": "1627" } } }
Personalisation
Similar to
Path
GET
api.ingeniapi.com/v2/items/:id/similar_toParameters
Name | Type | Description |
---|---|---|
id required |
string
|
ID of item to get similar items to |
bundle_id |
integer
|
Tell ingenia which bundle this item is in. If this parameter is omitted, ingenia will only look for the item in the default bundle
Example77 |
bundle_ids |
array
|
Restrict your search to one or more bundles. If this parameter is omitted, all bundles will be scanned
Example1,4,77 |
limit |
integer
|
The number of items to return, the maximum is 100.
Example15 |
full_text |
boolean
|
Show the results with all their text, however long |
mode |
string
|
Constrain matches to base similarity on just "tag", just "word", or "auto" (first tags, then words)
Defaultauto Examplemode=tag |
metadata_filters |
string
|
Instruct ingenia to only consider knowledge items which match these criteria
Examplemetadata_filters[author]=Joe%20Bloggs |
item_filters |
string
|
Instruct ingenia to only consider knowledge items which were created within specific dates. Dates are inclusive.
Exampleitem_filters[from]=2014-12-25&item_filters[to]=2014-12-30 |
curl -X GET 'https://api.ingeniapi.com/v2/items/ID423455-12-1432321250/similar_to?limit=3&api_key=$api_key' Response: [ { "item": { "id": "ID1959443-12-1458267383", "text": " So it’s been a little over a year since GitHub fired me. I initially made a vague tweet about leaving the company, and then a few weeks later I wrot..." }, "mode": "word", "similarity": 0.194 }, { "item": { "id": "ID1834322-12-1455638255", "text": " I worked there. It was literally the worst experience of my career - and I have worked at all of the hardest charging blue chips and two successfu..." }, "mode": "word", "similarity": 0.193 }, { "item": { "id": "ID1847748-12-1455841393", "text": "Table of Contents (Show)Table of Contents (Hide) In This Issue of Venture Weekly: Top Story Why Category Leaders Win, By Ablorde Ashigbi Per..." }, "mode": "word", "similarity": 0.19 } ]
Response
Similar to text
Path
POST
api.ingeniapi.com/v2/similar_to_textParameters
Name | Type | Description |
---|---|---|
text required |
string
|
Text of item for which we want other similar items |
bundle_id |
integer
|
The bundle this item would most likely be found in. If this parameter is omitted, ingenia assumes the first bundle you created.
Example77 |
bundle_ids |
array
|
Find similar items in one or more bundles. If this parameter is omitted, ingenia find items from any of your bundles.
Example1,4,77 |
limit |
integer
|
The number of items to return, the maximum is 100.
Example15 |
full_text |
boolean
|
Show the results with all their text, however long |
mode |
string
|
Constrain matches to base similarity on just "tag", just "word", or "auto" (first tags, then words)
Defaultauto Examplemode=tag |
metadata_filters |
string
|
Instruct ingenia to only consider knowledge items which match these criteria
Examplemetadata_filters[author]=Joe%20Bloggs |
item_filters |
string
|
Instruct ingenia to only consider knowledge items which were created within specific dates. Dates are inclusive.
Exampleitem_filters[from]=2014-12-25&item_filters[to]=2014-12-30 |
curl -X POST 'https://api.ingeniapi.com/v2/similar_to_text?text=technology%latest&limit=3&api_key=$api_key' Response: [ { "item": { "id": "ID218266-10-1425298759", "text": "Clarus Financial Technology | Esma +447771824036" }, "mode": "word", "similarity": 0.966 }, { "item": { "id": "CyberVally", "text": "Technology blog group. blogging about latest technology related news." }, "mode": "word", "similarity": 0.87 }, { "item": { "id": "TechoTrack", "text": "This is a technology blog. We provide latest updates on gadgets and technology." }, "mode": "word", "similarity": 0.869 } ]
Response
Similar to tags
Path
GET
api.ingeniapi.com/v2/similar_to_tagsParameters
Name | Type | Description |
---|---|---|
tag_ids required |
array
|
JSON encoded array of tag IDs for which we want relevant items
Example[ 45, 787, 23 ] |
bundle_ids |
array
|
Find similar items in one or more bundles. If this parameter is omitted, ingenia will attempt to infer the bundles from the tags
Example1,4,77 |
limit |
integer
|
The number of items to return, the maximum is 100.
Example15 |
full_text |
boolean
|
Show the results with all their text, however long |
metadata_filters |
string
|
Instruct ingenia to only consider knowledge items which match these criteria
Examplemetadata_filters[author]=Joe%20Bloggs |
item_filters |
string
|
Instruct ingenia to only consider knowledge items which were created within specific dates. Dates are inclusive.
Exampleitem_filters[from]=2014-12-25&item_filters[to]=2014-12-30 |
curl -X GET 'http://api.ingeniapi.com/v2/similar_to_tags?tag_ids=%5B189454%2C189475%5D&limit=3&api_key=$api_key' Response: [ { "item": { "id": "ID1959443-12-1458267383", "text": " So it’s been a little over a year since GitHub fired me. I initially made a vague tweet about leaving the company, and then a few weeks later I wrot..." }, "mode": "word", "similarity": 0.194 }, { "item": { "id": "ID1834322-12-1455638255", "text": " I worked there. It was literally the worst experience of my career - and I have worked at all of the hardest charging blue chips and two successfu..." }, "mode": "word", "similarity": 0.193 }, { "item": { "id": "ID1847748-12-1455841393", "text": "Table of Contents (Show)Table of Contents (Hide) In This Issue of Venture Weekly: Top Story Why Category Leaders Win, By Ablorde Ashigbi Per..." }, "mode": "word", "similarity": 0.19 } ]
Response
Summarisation
Summarise
Path
POST
api.ingeniapi.com/v2/summariseDescription
GET
is also supported
Parameters
Name | Type | Description |
---|---|---|
text |
string
|
Text to summarise: the key sentences will be extracted [1] |
url |
string
|
URL of article to summarise: the key sentences will be extracted [1] |
id |
string
|
ID of the item to be summarised. |
include_tags |
boolean
|
If true the resulting sentences will be organised by each tag associated to the text, if false they are returned as a list
Defaulttrue |
order_by_position |
boolean
|
If true, the results will be ordered as they appear in the text, if false, they will be ordered by the score of the sentence
Defaultfalse |
max_sentences |
integer
|
Maximum number of sentences to return
Default2 |
Notes
[1] You must input content as either text or a URL.
curl -X POST 'https://api.ingeniapi.com/v2/summarise?url=http://techcrunch.com/2016/05/11/charged/&api_key=$api_key' Response: { "results": { "Relevance": { "tags": [ { "machine_score": 0.11, "name": "Relevance", "id": 174842, "rule_score": 0.31, "score": 0.42, "sentences": [ { "text": "Venture capitalists in some sectors are increasingly eager to fund serious scientific innovations, they can be much tougher to do due diligence on than simple software that can be assessed based on immediate market traction.", "score": 0.055, "position": 4812 }, { "text": " Otherwise, it could find it difficult to raise additional funding, hire or retain talent, and avoid a negative press spiral.", "score": 0.043, "position": 4686 } ] } ], "id": "1625" } } }
Keywords
Show
Path
GET
api.ingeniapi.com/v2/keywords/:item_idDescription
Returns a list of keywords for a given itemParameters
Name | Type | Description |
---|---|---|
item_id required |
integer
|
ID of the item to show keyfords for. |
curl -X POST 'https://api.ingeniapi.com/v2/keywords/457?api_key=$api_key' Response: [ { "text": "chronograph", "occurrences": 1, "score": 254 }, { "text": "measure", "occurrences": 3, "score": 122 }, { "text": "time", "occurrences": 8, "score": 12 } ]
Clusters
Index
Path
GET
api.ingeniapi.com/v2/clustersDescription
Returns a list of clusters for a given bundleParameters
Name | Type | Description |
---|---|---|
bundle_id |
integer
|
ID of the bundle to show clusters for. If one is not provided, all of your bundles and their respective clusters will be returned. |
cluster_limit |
integer
|
Limit on the number of clusters per bundle to return.
Default20 |
word_limit |
integer
|
Limit on the number of words per cluster to return.
Default20 |
curl 'https://api.ingeniapi.com/v2/clusters?word_limit=4&api_key=$api_key' Response: [ { "bundle_id": 851, "date": "2016-09-23T13:00:16Z", "clusters": [ { "cluster": { "id": 149061, "score": 0.0118, "words": [ { "text": "tax", "score": 8.5 }, { "text": "cash", "score": 2.57 }, { "text": "payable", "score": 2.5 }, { "text": "financial", "score": 2.2 } ], "knowledge_items": [ 4379077, 4379091, 4379092, ], "related_tags": [ 191845 ], "related previous clusters": [ ... ] } }, {...} } {...} ]
Show
Path
GET
api.ingeniapi.com/v2/clusters/:idDescription
Returns a specific cluster of wordsParameters
Name | Type | Description |
---|---|---|
id required |
integer
|
ID of the cluster you want to show. |
word_limit |
integer
|
Limit on the number of words in the cluster to return.
Default20 |
curl 'https://api.ingeniapi.com/v2/clusters/149061?word_limit=4&api_key=$api_key' Response: { "id": 149061, "score": 0.0118, "words": [ { "text": "tax", "score": 8.5 }, { "text": "cash", "score": 2.57 }, { "text": "payable", "score": 2.5 }, { "text": "financial", "score": 2.2 } ], "knowledge_items": [ 4379077, 4379091, 4379092 ], "related_tags": [ 191845 ], "related previous clusters": [] }
Transform cluster into tag
Path
PUT
api.ingeniapi.com/v2/clusters/:idDescription
Creates a tag using the given clusterParameters
Name | Type | Description |
---|---|---|
id required |
integer
|
ID of the cluster you want to update. |
cluster_action required |
string
|
Action for cluster. In this case, it should be "transform_to_tag". |
tag_set_id required |
integer
|
The ID of the Tag Set that you want the new Tag to be saved in. |
name required |
string
|
The name for this new tag. |
curl -X PUT -F'json={ "name" : "Cluster Tag", "tag_set_id" : 2860 }' 'https://api.ingeniapi.com/v2/clusters/102165?cluster_action=transform_to_tag&api_key=$api_key' Response: { "cluster_actions": { "action": "transform_to_tag", "action_payload": "{"tag_set_id"=>"2860", "name"=>"Cluster Tag"}", "cluster_id": 102165, "created_at": "2016-11-02T12:15:49Z", "id": 49, "updated_at": "2016-11-02T12:33:52Z" }, "tags": { "confidence": 0, "created_at": "2016-11-02T12:33:52Z", "current_state": "unprocessed", "description": "", "id": 192038, "name": "Cluster Tag", "tag_set_id": 2860, "updated_at": "2016-11-02T12:33:52Z" } }
Merge cluster into tag
Path
PUT
api.ingeniapi.com/v2/clusters/:idDescription
Merges a given cluster into an existing tagParameters
Name | Type | Description |
---|---|---|
id required |
integer
|
ID of the Cluster you want to merge. |
cluster_action required |
string
|
Action for cluster. In this case, it should be "merge_into_tag". |
tag_id required |
integer
|
The ID of the Tag you want to merge the Cluster into. |
curl -X PUT -F'json={ "tag_id" : 192038 }' 'https://api.ingeniapi.com/v2/clusters/102165?cluster_action=merge_into_tag&api_key=$api_key' Response: { "cluster_actions": { "action": "merge_into_tag", "action_payload": "{"tag_id"=>"192038"}", "cluster_id": 102165, "created_at": "2016-11-02T15:17:49Z", "id": 50, "updated_at": "2016-11-02T15:35:52Z" } }
Ignore Cluster
Path
PUT
api.ingeniapi.com/v2/clusters/:idDescription
Marks the given cluster to be ignored in future. Use this if it is clearly irrelevant or incorrect.Parameters
Name | Type | Description |
---|---|---|
id required |
integer
|
ID of the cluster you want to update. |
cluster_action required |
string
|
Action for cluster. In this case, it should be "ignore". |
curl -X PUT -F 'https://api.ingeniapi.com/v2/clusters/102165?cluster_action=ignore&api_key=$api_key' Response: { "cluster_actions": { "action": "ignore", "action_payload": "", "cluster_id": 102165, "created_at": "2016-11-17T12:14:16Z", "id": 52, "updated_at": "2016-11-17T12:14:16Z" } }
Items
Index
Path
GET
api.ingeniapi.com/v2/itemsDescription
Returns a list of all your itemsParameters
Name | Type | Description |
---|---|---|
limit |
integer
|
Return up to this many results, up to a maximum of 1000.
Default10 |
full_text |
boolean
|
Show the results with all their text, however long |
offset |
integer
|
Offset the results I receive by this amount
Default0 |
ids |
array
|
Show only items with these ids.
Example[1a, 2b, 4a, 6c] |
bundle_id |
integer
|
Show only items from this bundle.
Example34 |
tag_set_id |
integer
|
Show only items associated to this tag_set.
Example27 |
curl 'https://api.ingeniapi.com/v2/items?api_key=$api_key' Response: [ { "bundle_id": 778, "bundle_name": "Here we go again", "concordance": null, "created_at": "2016-05-10T15:35:59Z", "id": "61265a8b2e56ff9693753fd044630ed5", "item_state": "processed", "language": "en", "last_classified_at": "2016-05-10T15:38:47Z", "membership_degree": null, "updated_at": "2016-05-10T15:38:47Z", "tag_sets": [ { "Cooking": { "id": 42, "tags": [ { "id": 81656, "name": "french-cuisine", "user_selected": "t", "user_assigned": true, "score": "0.06", "machine_score": "0.06", "rule_score": "0", "user_assigned_score": "0" } ] } } ], "text": "Some inline text", "metadata": [ null ] }, { "bundle_id": 778, "bundle_name": "Here we go again", "concordance": null, "created_at": "2016-05-10T16:03:59Z", "id": "3fdb62127e7a839e3f4e0ab6de7cd869", "item_state": "processed", "language": "en", "last_classified_at": "2016-05-10T16:04:00Z", "membership_degree": null, "updated_at": "2016-05-10T16:04:01Z", "tag_sets": [ { "Tech": { "id": 57, "tags": [ { "id": 91567, "name": "wearables", "user_selected": "t", "user_assigned": true, "score": "0.06", "machine_score": "0.06", "rule_score": "0", "user_assigned_score": "0" } ] } } ], "text": "Smartwatch cheats force Thai students back to exam halls - BBC News\nSome 3,000 students in Thailand must retake university entrance exams after a cheating scam involving cameras and smartwatches was uncovered.The sophisticated scam happened at Rangsit University in Bangkok.The ...", "metadata": [ null, { "name": "url-fetched", "type": "date", "content": "2016-05-10 16:03:59" }, { "name": "url", "type": "url", "content": "http://www.bbc.co.uk/news/world-asia-36253769" } ] } ]
Response
Show
Path
GET
api.ingeniapi.com/v2/items/:idDescription
Returns a single itemParameters
Name | Type | Description |
---|---|---|
id required |
string
|
The ID of the item you want to show |
bundle_id |
integer
|
The ID of the bundle containing the item you want to show. Items in different bundles could have the same ID, so this ensures the item returned is the correct one. |
full_text |
boolean
|
Show the results with all their text, however long |
curl 'https://api.ingeniapi.com/v2/items/61265a8b2e56ff9693753fd044630ed5?api_key=$api_key' Response: { "bundle_id": 778, "bundle_name": "Tech Startups", "concordance": null, "created_at": "2016-05-10T15:35:59Z", "id": "61265a8b2e56ff9693753fd044630ed5", "item_state": "processed", "language": "en", "last_classified_at": "2016-05-10T15:38:47Z", "membership_degree": null, "updated_at": "2016-05-10T15:38:47Z", "tag_sets": [ { "Tech": { "id": 57, "tags": [ { "id": 91567, "name": "wearables", "user_selected": "t", "user_assigned": true, "score": "0.06", "machine_score": "0.06", "rule_score": "0", "user_assigned_score": "0" } ] } } ], "text": "Some inline text", "metadata": [ null ] }
Response
Create
Path
POST
api.ingeniapi.com/v2/itemsDescription
Creates a new itemParameters
Name | Type | Description |
---|---|---|
json required |
json
|
An item is a block of text to which you can associate tags, that belongs to a bundle |
file |
multipart
|
File to be used as text source. Sent as multipart upload. Accepted file extensions are: Text (txt), Postscript Document Format (pdf) and Microsoft Office Documents (doc, docx, xlsx, ppt, pptx). [1] |
update_existing |
boolean
|
Choice of what to do if the item sent via a create call already exists on Ingenia, as determined by its item ID. If this field is true, the tags supplied will overwrite those on the existing item. If false, no data is modified and a response is returned with a 409 code (Conflict) together with the existing item as JSON.
Defaulttrue |
classify |
boolean
|
If true, the response will also include a classification |
Notes
[1] You can input content as one of these fields: text, a URL, a file. Formats supported for files include txt, html, pdf and all MS Office formats. If you send a file, it will extract the text from it.
The text and the URL are input as part of the JSON component. The file is sent as a multipart encoded https field.
# Simply post item's text curl -X POST \ -F'json={ "text" : "Some inline text" }' \ 'https://api.ingeniapi.com/v2/items?api_key=$api_key&classify=true' # Create an item with some text and assign a tag ('foo') to it with a score of 0.2. curl -X POST \ -F'json={ "text" : "Some inline text" , "tags" : { "foo" : 0.2 } }' \ 'https://api.ingeniapi.com/v2/items?api_key=$api_key&classify=true' # Create an item with some text, create a new tag set ('my tag set') and add # a tag ('foo') with a score of 0.2 to that tag set.. curl -X POST \ -F'json={ "text" : "Some inline text" , "tag_sets" : { "my tag set" : { "foo" : 0.2 } } }' \ 'https://api.ingeniapi.com/v2/items?api_key=$api_key&classify=true' # Create an item with the tag ('foo') curl -X POST \ -F'json={ "text" : "Some inline text" , "tags" : [ "foo"] }' \ 'https://api.ingeniapi.com/v2/items=$api_key&classify=true' # Post url to retrieve content from and create an item with that content curl -X POST \ -F'json={ "url" : "https://www.zdziarski.com/blog/?p=3875" }' \ 'https://api.ingeniapi.com/v2/items?api_key=$api_key' # Post a file using multipart/form-data upload and create an item with that content curl -X POST \ -F'json={}' \ -F'file=@article.txt' \ 'https://api.ingeniapi.com/v2/items?api_key=$api_key&classify=true&update_existing=true'
Response
Update
Path
PUT
api.ingeniapi.com/v2/items/:idDescription
Update an existing itemParameters
Name | Type | Description |
---|---|---|
id required |
string
|
The ID of the item you want to update |
json required |
json
|
An item is a block of text to which you can associate tags, that belongs to a bundle |
file |
multipart
|
File to be used as text source. Sent as multipart upload. Accepted file types are: Text (txt), Postscript Document Format (pdf), Microsoft Office Documents (doc, docx, xls, xlsx, ppt, pptx). [1] |
Notes
[1] You can input content as ONE of: text, a URL, a file (formats supported include txt, html, pdf, all the MS Office formats). If you send a URL, Ingenia will extract the most meaningful text from it, e.g., ignoring links. If you send a file, it will extract the text from it.
The text and the URL are input as part of the JSON component. The file is sent as a multipart encoded https field.
curl -X PUT \ -F'json={ "text" : "Some updated text" , "tags" : [ "foo"] }' \ 'https://api.ingeniapi.com/v2/items/61265a8b2e56ff9693753fd044630ed5?api_key=$api_key Response: { "bundle_id": 778, "created_at": "2016-05-10T15:35:59Z", "id": "61265a8b2e56ff9693753fd044630ed5", "last_classified_at": "2016-05-10T16:54:56Z", "updated_at": "2016-05-10T16:54:57Z", "text": "Some updated text", "tag_sets": [ { "Technologia": { "id": 2860, "tags": [ { "id": 189475, "name": "foo", "user_selected": "t", "user_assigned": true, "score": "0.0", "machine_score": "0", "rule_score": null, "user_assigned_score": "0" } ] } } ] }
Response
Delete
Path
DELETE
api.ingeniapi.com/v2/items/:idDescription
Delete an existing itemParameters
Name | Type | Description |
---|---|---|
id required |
string
|
The ID of the item you want to delete |
curl -X DELETE 'https://api.ingeniapi.com/v2/items/61265a8b2e56ff9693753fd044630ed5?api_key=$api_key' Response: { "61265a8b2e56ff9693753fd044630ed5": "destroyed", "bundle_id": 778 }
Bundles
Index
Path
GET
api.ingeniapi.com/v2/bundlesDescription
Returns a list of all your bundlesParameters
Name | Type | Description |
---|---|---|
limit |
integer
|
Return up to this many results, up to a maximum of 1000.
Default10 |
offset |
integer
|
Offset the results I receive by this amount
Default0 |
curl 'https://api.ingeniapi.com/v2/bundles?api_key=$api_key' Response: '{ [ { "id":755, "name":"New Bundle", "tag_sets" : [ { "name" : "technology", "id": 14562 }, { "name" : "business", "id": 666 } ], "created_at" : "2016-04-06T09:00:44Z", "updated_at":"2016-04-06T09:00:44Z" }, { "id" : 756, "name" : "Another Bundle", "tag_sets" : [ { "name" : "technology", "id": 14562 } ], "created_at" : "2016-04-07T11:44:26Z", "updated_at":"2016-04-07T11:44:26Z" } ] }'
Response
Show
Path
GET
api.ingeniapi.com/v2/bundles/:idDescription
Returns a single bundleParameters
Name | Type | Description |
---|---|---|
id required |
integer
|
The ID of the bundle you want to show |
curl 'https://api.ingeniapi.com/v2/bundles/47858?api_key=$api_key' Response: '{ "id" : 47858, "name" : "Tech Startups", "tag_sets" : [ { "name" : "technology", "id": 14562 }, { "name" : "business", "id": 666 } ], "created_at" :"2014-03-13T15:36:51Z", "updated_at" :"2014-03-13T15:36:51Z", }'
Response
Find_by_name
Path
GET
api.ingeniapi.com/v2/bundles/find_by_nameDescription
Looks for a bundle that matches exactly text inputParameters
Name | Type | Description |
---|---|---|
name required |
string
|
Name of the bundle to look for |
curl 'https://api.ingeniapi.com/v2/bundles/find_by_name?name=Tech%20Startups&api_key=$api_key' Response: '{ "id" : 47858, "name" : "Tech Startups", "tag_sets" : [ { "name" : "technology", "id": 14562 }, { "name" : "business", "id": 666 } ], "created_at" :"2014-03-13T15:36:51Z", "updated_at" :"2014-03-13T15:36:51Z", }'
Response
Create
Path
POST
api.ingeniapi.com/v2/bundlesDescription
Creates a new bundleParameters
Name | Type | Description |
---|---|---|
json required |
json
|
A collection of items related to each other |
curl -X POST \ -F'json={ "name" : "New Bundle", "tag_set_ids" : [2820, 2819] }' \ 'https://api.ingeniapi.com/v2/bundles?api_key=$api_key' Response: '{ "id" : 47858, "name" : "New Bundle", "tag_sets" : [ { "id" : 2820, "name" : "Tag Set One" }, { "id : 2819, "name : "Tag Set Two" } ], "created_at" :"2014-03-13T15:36:51Z", "updated_at" :"2014-03-13T15:36:51Z" }'
Response
Update
Path
PUT
api.ingeniapi.com/v2/bundles/:idDescription
Update an existing bundleParameters
Name | Type | Description |
---|---|---|
id required |
integer
|
The ID of the bundle you want to update |
json required |
json
|
A collection of items related to each other |
curl -X PUT \ -F'json={ "name" : "New Bundle Updated" }' \ 'https://api.ingeniapi.com/v2/bundles/47858?api_key=$api_key' Response: '{ "id" : 47858, "name" : "New Bundle Updated", "tag_sets" : [ { "id" : 2820, "name" : "Tag Set One" }, { "id : 2819, "name : "Tag Set Two" } ], "created_at" :"2016-04-06T09:00:44Z", "updated_at" :"2016-04-06T09:00:44Z", }'
Response
Delete
Path
DELETE
api.ingeniapi.com/v2/bundles/:idDescription
Delete an existing bundleParameters
Name | Type | Description |
---|---|---|
id required |
integer
|
The ID of the bundle you want to delete |
curl -X DELETE \ 'https://api.ingeniapi.com/v2/bundles/47858?api_key=$api_key' Response: '{ "47858" : "destroyed" }'
Tags
Index
Path
GET
api.ingeniapi.com/v2/tagsDescription
List all your tagsParameters
Name | Type | Description |
---|---|---|
limit |
integer
|
Return up to this many results, up to a maximum of 500.
Default10 |
offset |
integer
|
Offset the results I receive by this amount
Default0 |
curl 'https://api.ingeniapi.com/v2/tags?api_key=$api_key' Response: [ { "id": 192745, "name": "Finance", "created_at": "2017-09-18T13:15:16.407Z", "updated_at": "2017-09-18T14:49:40.259Z", "tag_set_id": 4564, "confidence": 0.85, "current_state": "processed", "description": "", "significant_words": [ { "text": "finance" }, { "text": "bank" }, { "text": "accounts" }, { "text": "capital markets" }, { "text": "fintech" } ], "tag_relationships": [ { "related_tag_id": 191711, "related_tag_name": "Economics", "relationship_type": "by_assignment", "value": 0.74 }, { "related_tag_id": 194712, "related_tag_name": "Fintech", "relationship_type": "by_name", "value": 0.66 } ] }, { "id": 198745, "name": "Technology", "created_at": "2017-09-18T17:15:16.407Z", "updated_at": "2017-09-18T17:49:40.259Z", "tag_set_id": 4564, "confidence": 1, "current_state": "processed", "description": "", "significant_words": [ { "text": "technology" }, { "text": "software" }, { "text": "company" }, { "text": "clean" }, { "text": "create" } ], "tag_relationships": [ { "related_tag_id": 198711, "related_tag_name": "Innovation", "relationship_type": "by_assignment", "value": 0.88 }, { "related_tag_id": 198742, "related_tag_name": "Tech startup", "relationship_type": "by_name", "value": 0.68 } ] } ]
Response
See Tag: show output
Show
Path
GET
api.ingeniapi.com/v2/tags/:idDescription
View a single tagParameters
Name | Type | Description |
---|---|---|
id required |
integer
|
The ID of the tag you want to show |
curl 'https://api.ingeniapi.com/v2/tags/189453?api_key=$api_key' Response: { "id": 198745, "name": "Technology", "created_at": "2017-09-18T17:15:16.407Z", "updated_at": "2017-09-18T17:49:40.259Z", "tag_set_id": 4564, "confidence": 1, "current_state": "processed", "description": "", "significant_words": [ { "text": "technology" }, { "text": "software" }, { "text": "company" }, { "text": "clean" }, { "text": "create" } ], "tag_relationships": [ { "related_tag_id": 198711, "related_tag_name": "Innovation", "relationship_type": "by_assignment", "value": 0.88 }, { "related_tag_id": 198742, "related_tag_name": "Tech startup", "relationship_type": "by_name", "value": 0.68 } ] }
Response
See Tag: show output
Find_by_name
Path
GET
api.ingeniapi.com/v2/tags/find_by_nameDescription
Looks for a tag that matches exactly text inputParameters
Name | Type | Description |
---|---|---|
name required |
string
|
Name of the tag to look for |
curl 'https://api.ingeniapi.com/v2/tags/find_by_name?name=New%20Tag&api_key=$api_key' Response: { "confidence": 0.0, "created_at": "2016-05-04T16:12:43Z", "current_state": "not_enough_items_to_learn", "description": "", "id": 189453, "name": "New Tag", "tag_set_id": 2858, "updated_at": "2016-05-04T16:12:43Z" }
Response
See Tag: show output
Create
Path
POST
api.ingeniapi.com/v2/tagsDescription
Create a new tagParameters
Name | Type | Description |
---|---|---|
json required |
json
|
Something you want to associate to an item, e.g., a concept, topic, tone, sentiment, keyword, person, company, product, etc. |
curl -X POST \ -F'json={ "tag_set_id" : 2858, "name" : "New Tag" }' \ 'https://api.ingeniapi.com/v2/tags?api_key=$api_key' Response: { "confidence": 0.0, "created_at": "2016-05-04T17:05:18Z", "current_state": "unprocessed", "description": "", "id": 189455, "name": "New Tag", "tag_set_id": 2858, "updated_at": "2016-05-04T17:05:18Z" }
Response
Update
Path
PUT
api.ingeniapi.com/v2/tags/:idDescription
Update an existing tagParameters
Name | Type | Description |
---|---|---|
id required |
integer
|
The ID of the tag you want to update |
json required |
json
|
Something you want to associate to an item, e.g., a concept, topic, tone, sentiment, keyword, person, company, product, etc. |
curl -X PUT \ -F'json={ "name" : "New Tag Updated" }' \ 'https://api.ingeniapi.com/v2/tags/189453?api_key=$api_key' Response: { "confidence": 0.0, "created_at": "2016-05-04T16:12:43Z", "current_state": "unprocessed", "description": "", "id": 189453, "name": "New Tag Updated", "tag_set_id": 2858 }
Response
Merge
Path
POST
api.ingeniapi.com/v2/tags/:id/mergeDescription
Merge two or more existing tagsParameters
Name | Type | Description |
---|---|---|
id required |
integer
|
The ID of the tag into which you want to merge other tags; the resulting tag will have this name |
tag_ids required |
array
|
A JSON encoded array of tag IDs that will be merged into the main tag
Example[ 23, 43, 2113 ] |
curl -X POST 'https://api.ingeniapi.com/v2/tags/189454/merge?tag_ids=%5B189452%2C189453%5D&api_key=$api_key' /*(Where: '%5B' = '[' '%2C' = ',' '%5D' = ']' for constructing array of IDs in url params)*/ Response: { "189454":"merged" }
Delete
Path
DELETE
api.ingeniapi.com/v2/tags/:idDescription
Delete an existing tagParameters
Name | Type | Description |
---|---|---|
id required |
integer
|
The ID of the tag you want to delete |
curl -X DELETE 'https://api.ingeniapi.com/v2/tags/189454?api_key=$api_key' Response: { "189455" : "destroyed" }
Tag rules
Index For User
Path
GET
api.ingeniapi.com/v2/tag_rulesDescription
List all of the current user's tag rules, organised by tag.Parameters
Name | Type | Description |
---|
curl https://api.ingeniapi.com/v2/tag_rules?api_key=$api_key Response: [ { "id": 189879, "name": "Questions", "rules": [ { "id": 10963, "tag_rule_mode": "word_absent", "rule_tag_id": null, "word": "help", "language": "en", "influence": -0.1, "created_at": "2016-06-02T18:10:24Z", "updated_at": "2016-06-02T18:10:24Z" }, { "id": 10964, "tag_rule_mode": "word_present", "rule_tag_id": null, "word": "question", "language": "en", "influence": 0.1, "created_at": "2016-06-02T18:10:24Z", "updated_at": "2016-06-02T18:10:24Z" } ] }, { "id": 189840, "name": "service improvements", "rules": [ { "id": 10783, "tag_rule_mode": "word_present", "rule_tag_id": null, "word": "better", "language": "en", "influence": 0.1, "created_at": "2016-06-02T18:10:24Z", "updated_at": "2016-06-02T18:10:24Z" }, {...} ] }, {...} ]
Response
Index
Path
GET
api.ingeniapi.com/v2/tags/:tag_id/tag_rulesDescription
List all of your tag rules for a specific tag.Parameters
Name | Type | Description |
---|---|---|
tag_id required |
integer
|
The ID of the tag to find its associated tag rules |
curl https://api.ingeniapi.com/v2/tags/5/tag_rules?api_key=$api_key Response: { "tag": { "id": 189879, "name": "Questions" }, "tag_rules": [ { "id": 10963, "tag_rule_mode": "word_absent", "rule_tag_id": null, "word": "help", "language": "en", "influence": -0.1, "created_at": "2016-06-02T18:10:24Z", "updated_at": "2016-06-02T18:10:24Z" }, { "id": 10964, "tag_rule_mode": "word_present", "rule_tag_id": null, "word": "question", "language": "en", "influence": 0.1, "created_at": "2016-06-02T18:10:24Z", "updated_at": "2016-06-02T18:10:24Z" } ] }
Response
Show
Path
GET
api.ingeniapi.com/v2/tags/:tag_id/tag_rules/:idDescription
View a single tag ruleParameters
Name | Type | Description |
---|---|---|
id required |
integer
|
The ID of the tag rule |
tag_id required |
integer
|
The ID of the tag |
curl https://api.ingeniapi.com/v2/tags/5/tag_rules/6?api_key=$api_key Response: { "tag": { "id": 189879, "name": "Questions" }, "tag_rule": { "id": 10963, "tag_rule_mode": "word_absent", "rule_tag_id": null, "word": "help", "language": "en", "influence": -0.1, "created_at": "2016-06-02T18:10:24Z", "updated_at": "2016-06-02T18:10:24Z" } }
Response
Create
Path
POST
api.ingeniapi.com/v2/tags/:tag_id/tag_rulesDescription
Create a new tag ruleParameters
Name | Type | Description |
---|---|---|
tag_id required |
integer
|
The ID of the tag |
json required |
json
|
A rule to apply to a tag to influence use of that tag. |
curl -X POST \ -F'json={ "text": "tag_text", "influence" : 0.3, "language": "en", "tag_rule_mode": "word_present" }' \ https://api.ingeniapi.com/v2/tags/5/tag_rules?api_key=$api_key
Response
Delete
Path
DELETE
api.ingeniapi.com/v2/tags/:tag_id/tag_rules/:idDescription
Delete an existing tag ruleParameters
Name | Type | Description |
---|---|---|
id required |
integer
|
The ID of the tag rule you want to delete |
tag_id required |
integer
|
The ID of the tag |
curl -X DELETE \ https://api.ingeniapi.com/v2/tags/5/tag_rules/6?api_key=$api_key
Tag sets
Index
Path
GET
api.ingeniapi.com/v2/tag_setsDescription
List all your tag setsParameters
Name | Type | Description |
---|---|---|
limit |
integer
|
Return up to this many results, up to a maximum of 1000.
Default10 |
offset |
integer
|
Offset the results I receive by this amount
Default0 |
# Simple request to fetch all tag sets curl -s -q 'https://api.ingeniapi.com/v2/tag_sets?api_key=$api_key' # ...and a bit more advanced example curl -s -q 'https://api.ingeniapi.com/v2/tag_sets?limit=100&offset=100&bundle_id=42&api_key=$api_key' Response: '[ { "created_at" : "2016-04-06T11:01:18Z", "id" : 2820, "name" : "Tag Set One", "updated_at" : "2016-04-06T11:04:00Z" "bundles": [ { "id": 773, "name": "Some Bundle" }, { "id": 774, "name": "Some Other Bundle" } ] }, { "created_at" : "2016-04-06T09:00:44Z", "id" : 2819, "name" : "Tag Set Two", "updated_at":"2016-04-06T09:00:44Z", "bundles": [ { "id": 773, "name": "A Different Bundle" } ] } ]'
Response
Show
Path
GET
api.ingeniapi.com/v2/tag_sets/:idDescription
View a single tag setParameters
Name | Type | Description |
---|---|---|
id required |
integer
|
The ID of the tag set you want to show |
curl 'https://api.ingeniapi.com/v2/tag_sets/2820?api_key=haDJdWeW41iwzEup7n8x' Response: { "created_at": "2016-05-04T11:30:43Z", "id": 2857, "name": "New Tag Set", "updated_at": "2016-05-04T12:52:56Z", "bundles": [ { "id": 773, "name": "Prodotti" }, { "id": 774, "name": "Articoli" } ] }
Response
Find_by_name
Path
GET
api.ingeniapi.com/v2/tag_sets/find_by_nameDescription
Looks for a tag set that matches exactly text inputParameters
Name | Type | Description |
---|---|---|
text required |
string
|
Text of tag set to look for |
curl 'https://api.ingeniapi.com/v2/tag_sets/find_by_name?name=Big%20Data&api_key=$api_key' Response: '{ "created_at" : "2016-04-07T16:13:52Z", "id" : 2822, "name" : "Big Data", "updated_at" : "2016-04-07T16:13:52Z" "bundles": [ { "id": 773, "name": "A Bundle Name" } ] }'
Response
Create
Path
POST
api.ingeniapi.com/v2/tag_setsDescription
Create a new tag setParameters
Name | Type | Description |
---|---|---|
json required |
json
|
A collection of thematically consistent tags |
curl -s -X POST \ -F'json={ "name" : "new tag s" }' \ 'https://api.ingeniapi.com/v2/tag_sets?api_key=$api_key' Response: '{ "created_at" : "2016-04-07T16:49:24Z", "id" : 2823, "name" : "new tag s", "updated_at" : "2016-04-07T16:49:24Z" }'
Response
Update
Path
PUT
api.ingeniapi.com/v2/tag_sets/:idDescription
Update an existing tag setParameters
Name | Type | Description |
---|---|---|
id required |
integer
|
The ID of the tag set you want to update |
json required |
json
|
A collection of thematically consistent tags |
curl -s -X PUT \ -F'json={ "name" : "Updated Tag Set Name" }' \ 'https://api.ingeniapi.com/v2/tag_sets/2823?api_key=$api_key' Response: '{ "created_at" : "2016-04-07T16:49:24Z", "id" : 2823, "name" : "Updated Tag Set Name", "updated_at" : "2016-04-07T16:58:11Z" }'
Response
Merge
Path
POST
api.ingeniapi.com/v2/tag_sets/:id/mergeDescription
Merge two or more existing tag setsParameters
Name | Type | Description |
---|---|---|
id required |
integer
|
The ID of the tag set into which you want to merge the other tag sets; the resulting tag set will have this name |
tag_set_ids required |
array
|
JSON encoded array of tag set IDs to merge into main tag set
Example[ 12, 34, 56 ] |
curl -X POST 'https://api.ingeniapi.com/v2/tag_sets/2824/merge?tag_set_ids=%5B2833%2C2832%5D&api_key=$api_key' /*(Where: '%5B' = '[' '%2C' = ',' '%5D' = ']' for constructing array of IDs in url params)*/ Response: '{ {"tag_set_id" : 2824} }'
Delete
Path
DELETE
api.ingeniapi.com/v2/tag_sets/:idDescription
Delete an existing tag setParameters
Name | Type | Description |
---|---|---|
id required |
integer
|
The ID of the tag set you want to delete. |
curl -X DELETE 'https://api.ingeniapi.com/v2/tag_sets/2824?api_key=$api_key' Response: '{ "2824" : "destroyed" }'
Text extraction
Get stripped text
Description
Returns stripped text for a given urlParameters
Name | Type | Description |
---|---|---|
uri |
string
|
The url of the article you want to extract |
# Request to get stripped content for url curl -X POST -H 'Content-Type: application/json' -d '{"url":{"uri":"https://techcrunch.com/2016/08/02/instagram-stories/"}}' http://content-service.ingeniapi.com/urls Response: '{ "url": { "uri": "https://techcrunch.com/2016/08/02/instagram-stories/" }, "title": "Instagram launches “Stories,” a Snapchatty feature for imperfect sharing", "content": "People only post the highlights of their life on Instagram, so today the app adds its own version of “Stories” ...'
Get full html
Description
Returns full html for a urlParameters
Name | Type | Description |
---|---|---|
url |
string
|
The url of the html you want to return |
# Request to get stripped content for url curl 'https://techcrunch.com/2016/08/02/instagram-stories/' Response:' Instagram launches “Stories,” a Snapchatty feature for imperfect sharing | TechCrunch ...'
Administrative calls
Status
Path
GET
api.ingeniapi.com/v2/statusDescription
The status of your Ingenia account, indicating whether Ingenia has processed all your content; use this to test your API key, see [status call] for detailsParameters
Name | Type | Description |
---|---|---|
total_bundles |
integer
|
Number of bundles you have own |
processed_bundles |
integer
|
Number of bundles where all items have been processed |
total_items |
integer
|
Number of items you have created |
pending_items |
integer
|
Number of items Ingenia has not yet processed |
processed_items |
integer
|
Number of items Ingenia has processed |
total_tag_sets |
integer
|
Number of tag sets you own |
processed_tag_sets |
integer
|
Number of tag sets Ingenia has processed |
pending_tag_sets |
integer
|
Number of tag sets ready to process, but which Ingenia has not yet processed |
untrained_tag_sets |
integer
|
Number of tag sets which do not have enough items to process |
idle_tag_sets |
integer
|
Number of tag sets that the user prefers to not be processed by Ingenia |
total_tags |
integer
|
Number of tags you have own |
processed_tags |
integer
|
Number of tags Ingenia has processed |
pending_tags |
integer
|
Number of tags Ingenia has not yet processed |
untrained_tags |
integer
|
Number of tags which are not assigned to items |
idle_tags |
integer
|
Number of tags that the user prefers to not be processed by Ingenia |
ready_to_classify |
boolean
|
True if all tags assigned to items have been processed |
curl -X GET 'https://api.ingeniapi.com/v2/status?api_key=$api_key' Response: { "total_bundles": 17, "processed_bundles": 1, "total_items": 2, "pending_items": 0, "processed_items": 2, "total_tag_sets": 2, "pending_tag_sets": 0, "processed_tag_sets": 0, "untrained_tag_sets": 2, "idle_tag_sets": 0, "total_tags": 3, "pending_tags": 0, "processed_tags": 0, "untrained_tags": 3, "idle_tags": 0, "ready_to_classify": true }
Clear_data
Path
POST
api.ingeniapi.com/v2/clear_dataDescription
Delete all the data in your account; useful to restart from zero if the data was pollutedParameters
Name | Type | Description |
---|
curl -X POST 'https://api.ingeniapi.com/v2/clear_data?api_key=$api_key' Response: {}
- Getting started
- Data structures
- Classifications
- Personalisation
- Summarisation
- Keywords
- Clusters
- Items
- Bundles
- Tags
- Tag rules
- Tag sets
- Text extraction
- Administrative calls