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_ruby

Rate 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.
Example

785uU423aC

text string Your item's content. [1]
url string Source URL to get text from. Ingenia will extract the most relevant text [1]
Example

https://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
Example

785uU423aC

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
Example

2013-12-16T11:24:52+00:00

updated_at date_time When this item was last updated
Example

2013-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
Example

2013-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
Example

6bbd66632349f38b87af3cb8b370a481_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
Example

2013-12-16T11:24:52+00:00

updated_at date_time When this bundle was last updated
Example

2013-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
Example

2013-12-16T11:24:52+00:00

updated_at date_time When this tag was last updated
Example

2013-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
Example

2013-12-16T11:24:52+00:00

updated_at date_time When this tag rule was last updated
Example

2013-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
Example

2013-12-16T11:24:52+00:00

updated_at date_time When this tag rule was last updated
Example

2013-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
Example

2013-12-16T11:24:52+00:00

updated_at date_time When this tag set was last updated
Example

2013-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/classify
Parameters
Name Type Description
text string The text you want Ingenia to classify [1]
Example

A 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]
Example

https://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]
Example

document.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.
Default

0

max_tags integer Return at most these many tags, up to a maximum of 1000.
Default

6

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.

Example request
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_to
Parameters
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
Example

77

bundle_ids array Restrict your search to one or more bundles. If this parameter is omitted, all bundles will be scanned
Example

1,4,77

limit integer The number of items to return, the maximum is 100.
Example

15

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)
Default

auto

Example

mode=tag

metadata_filters string Instruct ingenia to only consider knowledge items which match these criteria
Example

metadata_filters[author]=Joe%20Bloggs

item_filters string Instruct ingenia to only consider knowledge items which were created within specific dates. Dates are inclusive.
Example

item_filters[from]=2014-12-25&item_filters[to]=2014-12-30

Example request
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

See Similarity response

Similar to text
Path
POST api.ingeniapi.com/v2/similar_to_text
Parameters
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.
Example

77

bundle_ids array Find similar items in one or more bundles. If this parameter is omitted, ingenia find items from any of your bundles.
Example

1,4,77

limit integer The number of items to return, the maximum is 100.
Example

15

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)
Default

auto

Example

mode=tag

metadata_filters string Instruct ingenia to only consider knowledge items which match these criteria
Example

metadata_filters[author]=Joe%20Bloggs

item_filters string Instruct ingenia to only consider knowledge items which were created within specific dates. Dates are inclusive.
Example

item_filters[from]=2014-12-25&item_filters[to]=2014-12-30

Example request
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

See Similarity response

Similar to tags
Path
GET api.ingeniapi.com/v2/similar_to_tags
Parameters
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
Example

1,4,77

limit integer The number of items to return, the maximum is 100.
Example

15

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
Example

metadata_filters[author]=Joe%20Bloggs

item_filters string Instruct ingenia to only consider knowledge items which were created within specific dates. Dates are inclusive.
Example

item_filters[from]=2014-12-25&item_filters[to]=2014-12-30

Example request
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

See Similarity response

Summarisation

Summarise
Path
POST api.ingeniapi.com/v2/summarise
Description
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
Default

true

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
Default

false

max_sentences integer Maximum number of sentences to return
Default

2

Notes

[1] You must input content as either text or a URL.

Example request
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_id
Description
Returns a list of keywords for a given item
Parameters
Name Type Description
item_id required integer ID of the item to show keyfords for.
Example request
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/clusters
Description
Returns a list of clusters for a given bundle
Parameters
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.
Default

20

word_limit integer Limit on the number of words per cluster to return.
Default

20

Example request
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/:id
Description
Returns a specific cluster of words
Parameters
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.
Default

20

Example request
      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/:id
Description
Creates a tag using the given cluster
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 "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.
Example request
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/:id
Description
Merges a given cluster into an existing tag
Parameters
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.
Example request
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/:id
Description
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".
Example request
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

Blocks of textual content, typically self-contained and homogeneous
Index
Path
GET api.ingeniapi.com/v2/items
Description
Returns a list of all your items
Parameters
Name Type Description
limit integer Return up to this many results, up to a maximum of 1000.
Default

10

full_text boolean Show the results with all their text, however long
offset integer Offset the results I receive by this amount
Default

0

ids array Show only items with these ids.
Example

[1a, 2b, 4a, 6c]

bundle_id integer Show only items from this bundle.
Example

34

tag_set_id integer Show only items associated to this tag_set.
Example

27

Example request
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

See Item: show output

Show
Path
GET api.ingeniapi.com/v2/items/:id
Description
Returns a single item
Parameters
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
Example request
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

See Item: show output

Create
Path
POST api.ingeniapi.com/v2/items
Description
Creates a new item
Parameters
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.
Default

true

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.

Example request
# 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'
Update
Path
PUT api.ingeniapi.com/v2/items/:id
Description
Update an existing item
Parameters
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.

Example request
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"
          }
        ]
      }
    }
  ]
}
Delete
Path
DELETE api.ingeniapi.com/v2/items/:id
Description
Delete an existing item
Parameters
Name Type Description
id required string The ID of the item you want to delete
Example request
curl -X DELETE 'https://api.ingeniapi.com/v2/items/61265a8b2e56ff9693753fd044630ed5?api_key=$api_key'

Response:

{
  "61265a8b2e56ff9693753fd044630ed5": "destroyed",
  "bundle_id": 778
}

Bundles

Groups of thematically consistent items
Index
Path
GET api.ingeniapi.com/v2/bundles
Description
Returns a list of all your bundles
Parameters
Name Type Description
limit integer Return up to this many results, up to a maximum of 1000.
Default

10

offset integer Offset the results I receive by this amount
Default

0

Example request
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

See Bundle: show output

Show
Path
GET api.ingeniapi.com/v2/bundles/:id
Description
Returns a single bundle
Parameters
Name Type Description
id required integer The ID of the bundle you want to show
Example request
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

See Bundle: show output

Find_by_name
Path
GET api.ingeniapi.com/v2/bundles/find_by_name
Description
Looks for a bundle that matches exactly text input
Parameters
Name Type Description
name required string Name of the bundle to look for
Example request
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

See Bundle: show output

Create
Path
POST api.ingeniapi.com/v2/bundles
Description
Creates a new bundle
Parameters
Name Type Description
json required json A collection of items related to each other
Example request
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"
  }'
Update
Path
PUT api.ingeniapi.com/v2/bundles/:id
Description
Update an existing bundle
Parameters
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
Example request
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",
  }'
Delete
Path
DELETE api.ingeniapi.com/v2/bundles/:id
Description
Delete an existing bundle
Parameters
Name Type Description
id required integer The ID of the bundle you want to delete
Example request
curl -X DELETE \
  'https://api.ingeniapi.com/v2/bundles/47858?api_key=$api_key'

Response:

'{
    "47858" : "destroyed"
  }'

Tags

Tags are meaningful words or expressions that you want to associate to some of your items
Index
Path
GET api.ingeniapi.com/v2/tags
Description
List all your tags
Parameters
Name Type Description
limit integer Return up to this many results, up to a maximum of 500.
Default

10

offset integer Offset the results I receive by this amount
Default

0

Example request
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/:id
Description
View a single tag
Parameters
Name Type Description
id required integer The ID of the tag you want to show
Example request
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_name
Description
Looks for a tag that matches exactly text input
Parameters
Name Type Description
name required string Name of the tag to look for
Example request
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/tags
Description
Create a new tag
Parameters
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.
Example request
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"
  }
Update
Path
PUT api.ingeniapi.com/v2/tags/:id
Description
Update an existing tag
Parameters
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.
Example request
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
  }
Merge
Path
POST api.ingeniapi.com/v2/tags/:id/merge
Description
Merge two or more existing tags
Parameters
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 ]

Example request
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/:id
Description
Delete an existing tag
Parameters
Name Type Description
id required integer The ID of the tag you want to delete
Example request
curl -X DELETE 'https://api.ingeniapi.com/v2/tags/189454?api_key=$api_key'

Response:

  {
    "189455" : "destroyed"
  }

Tag rules

Tag rules are rules that you want to associate with a tag to influence the tag choice
Index For User
Path
GET api.ingeniapi.com/v2/tag_rules
Description
List all of the current user's tag rules, organised by tag.
Parameters
Name Type Description
Example request
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"
      },
      {...}
    ]
  },
  {...}
]
Index
Path
GET api.ingeniapi.com/v2/tags/:tag_id/tag_rules
Description
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
Example request
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"
    }
  ]
}
Show
Path
GET api.ingeniapi.com/v2/tags/:tag_id/tag_rules/:id
Description
View a single tag rule
Parameters
Name Type Description
id required integer The ID of the tag rule
tag_id required integer The ID of the tag
Example request
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

See Tag Rule: show output

Create
Path
POST api.ingeniapi.com/v2/tags/:tag_id/tag_rules
Description
Create a new tag rule
Parameters
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.
Example request
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

See Tag rule: create input

Delete
Path
DELETE api.ingeniapi.com/v2/tags/:tag_id/tag_rules/:id
Description
Delete an existing tag rule
Parameters
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
Example request
curl -X DELETE \
  https://api.ingeniapi.com/v2/tags/5/tag_rules/6?api_key=$api_key

Tag sets

Tag sets are thematically consistent groups of tags defined by you, such as, say, world countries, business sectors, product types, companies, concepts, topics, etc
Index
Path
GET api.ingeniapi.com/v2/tag_sets
Description
List all your tag sets
Parameters
Name Type Description
limit integer Return up to this many results, up to a maximum of 1000.
Default

10

offset integer Offset the results I receive by this amount
Default

0

Example request
# 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

See Tag set: show output

Show
Path
GET api.ingeniapi.com/v2/tag_sets/:id
Description
View a single tag set
Parameters
Name Type Description
id required integer The ID of the tag set you want to show
Example request
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

See Tag set: show output

Find_by_name
Path
GET api.ingeniapi.com/v2/tag_sets/find_by_name
Description
Looks for a tag set that matches exactly text input
Parameters
Name Type Description
text required string Text of tag set to look for
Example request
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

See Tag set: show output

Create
Path
POST api.ingeniapi.com/v2/tag_sets
Description
Create a new tag set
Parameters
Name Type Description
json required json A collection of thematically consistent tags
Example request
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"
}'
Update
Path
PUT api.ingeniapi.com/v2/tag_sets/:id
Description
Update an existing tag set
Parameters
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
Example request
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"
}'
Merge
Path
POST api.ingeniapi.com/v2/tag_sets/:id/merge
Description
Merge two or more existing tag sets
Parameters
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 ]

Example request
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/:id
Description
Delete an existing tag set
Parameters
Name Type Description
id required integer The ID of the tag set you want to delete.
Example request
curl -X DELETE 'https://api.ingeniapi.com/v2/tag_sets/2824?api_key=$api_key'

Response:

'{
  "2824" : "destroyed"
}'

Text extraction

Returns stripped text for a given url
Get stripped text
Description
Returns stripped text for a given url
Parameters
Name Type Description
uri string The url of the article you want to extract
Example request
# 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 url
Parameters
Name Type Description
url string The url of the html you want to return
Example request
# Request to get stripped content for url
curl 'https://techcrunch.com/2016/08/02/instagram-stories/'

Response:
'<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml" xmlns:og="http://opengraphprotocol.org/schema/" xmlns:fb="http://www.facebook.com/2008/fbml" lang="en">
<head>
  <title>Instagram launches &#8220;Stories,&#8221; a Snapchatty feature for imperfect sharing  |  TechCrunch</title>
  ...'

Administrative calls

Status
Path
GET api.ingeniapi.com/v2/status
Description
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 details
Parameters
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
Example request
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_data
Description
Delete all the data in your account; useful to restart from zero if the data was polluted
Parameters
Name Type Description
Example request
curl -X POST 'https://api.ingeniapi.com/v2/clear_data?api_key=$api_key'

Response:

{}