Getting started. Version 2.0

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 bundle. You can use your own, or have Ingenia generate one for you
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

http://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 ]

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' }]

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 http 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
id string A unique alphanumeric id
Example

785uU423aC

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

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_set_ids": [ 232, 332, 6582 ]
  }

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.
language string The language of your bundle
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 }
    ],
    "language": "en",
    "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
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
consistency float From 0 to 1; consistency gets closer to 1 the more Ingenia considers the items associated to this tag as similar to one another; if this value is low, we advise to re-assess the items associated to 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

Example

  {
    "id":554273,
    "name":"Text Analytics",
    "tag_set_id":8547,
    "confidence":0.95,
    "consistency":0.92,
    "description":"",
    "created_at":"2014-03-13T12:59:32Z",
    "updated_at":"2014-03-13T12:59:32Z"
  }

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

Example

  {
    "name":"Big Data"
  }

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

Example

  {
    "id":178751,
    "name":"Big Data",
    "created_at":"2014-03-12T12:17:33Z",
    "updated_at":"2014-03-12T12:17:33Z"
  }

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

http://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
Default

0

max_tags integer Return at most these many tags
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 http field.

Recommendation engine

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

Response

See Similarity response

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

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

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 these many results
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

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
full_text boolean Show the results with all their text, however long

Response

See Item: show output

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

Example request
# Simply post item's text
curl -X POST \
  -F'json={ "text" : "Some inline text" }' \
  'http://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 } }' \
  'http://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 } } }' \
  'http://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"]  }' \
  'http://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" : "http://www.zdziarski.com/blog/?p=3875" }' \
  'http://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' \
  'http://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 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 http field.

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

Response

See Similarity response

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 these many results
Default

10

offset integer Offset the results I receive by this amount
Default

0

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

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
text string Text of the bundle to look for
Create
Path
POST api.ingeniapi.com/v2/bundles
Description
Creates a new bundle
Parameters
Name Type Description
json json A collection of items related to each other
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 json A collection of items related to each other
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

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 these many results
Default

10

offset integer Offset the results I receive by this amount
Default

0

Example request
curl http://api.ingeniapi.com/v2/tags?api_key=$api_key
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

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
text string Text of the tag to look for
Create
Path
POST api.ingeniapi.com/v2/tags
Description
Create a new tag
Parameters
Name Type Description
json 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" : 52, "name" : "wine" }' \
  http://api.ingeniapi.com/v2/tags?api_key=$api_key
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 json Something you want to associate to an item, e.g., a concept, topic, tone, sentiment, keyword, person, company, product, etc.
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 \
  http://api.ingeniapi.com/v2/tags/8/merge?tag_ids='[7,8]'&api_key=$api_key
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

Tag Rules

Tag Rules are rules that you want to associate with a tag to influence the tag choice
Index
Path
GET api.ingeniapi.com/v2/tag/:tag_id/tag_rules
Description
List all your tag rules for a tag
Parameters
Name Type Description
tag_id required integer The ID of the tag to find its associated tag rules
Example request
curl http://api.ingeniapi.com/v2/tag/5/tag_rules?api_key=$api_key
Show
Path
GET api.ingeniapi.com/v2/tag/: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 http://api.ingeniapi.com/v2/tag/5/tag_rules/6?api_key=$api_key

Response

See Tag Rule: show output

Create
Path
POST api.ingeniapi.com/v2/tag/:tag_id/tag_rules
Description
Create a new tag rule
Parameters
Name Type Description
json json A rule to apply to a tag to influence use of that tag.
tag_id required integer The ID of the tag
Example request
curl -X POST \
  -F'json={ "text": "tag_text", "influence" : 0.3, "language": "en", "tag_rule_mode": "word_present" }' \
  http://api.ingeniapi.com/v2/tag/5/tag_rules?api_key=$api_key
Delete
Path
DELETE api.ingeniapi.com/v2/tag/: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 \
  http://api.ingeniapi.com/v2/tag/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 these many results
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 http://api.ingeniapi.com/v2/tag_sets?api_key=$api_key

# ...and a bit more advanced example
curl -s -q http://api.ingeniapi.com/v2/tag_sets?limit=100&offset=100&bundle_id=42&api_key=$api_key
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

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 string Text of tag set to look for
Create
Path
POST api.ingeniapi.com/v2/tag_sets
Description
Create a new tag set
Parameters
Name Type Description
json json A collection of thematically consistent tags
Example request
curl -s -X POST \
  -F'json={ "name" : "new tag s" }' \
  http://api.ingeniapi.com/v2/tag_sets?api_key=$api_key
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 json A collection of thematically consistent tags
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 ]

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.

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
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
ready_to_classify boolean True if all tags assigned to items have been processed
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
item_count integer Number of items you have that are about to be deleted
tag_set_count integer Number of tag sets you have that are about to be deleted
tag_count integer Number of tags you have that are about to be deleted