DEPRECATED API

Note: Ingenia API version 1.0 is now superseded by version 2.0: any new user should use the newest version. If you're a user of v1, the API will still work as you would expect.

However, it is now a proxy of version 2.0: this means that the responses will include references to the concept of "bundle", which you can ignore as it is not supported in v1. We recommend to move to version 2.0 as soon as possible. To transition, you will only need to modify the endpoint to api.ingeniapi.com/v2/.

Get started with Ingenia

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 one of the libraries.

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.

API libraries

Ruby

https://github.com/ingenia-api/ingenia_ruby

Javascript

See javascript examples for document on how to use APIs from client based applications.

Rate limiting

Ingenia by default limits a user to 4 calls per second, for every type of API call. This limit can be increased or removed if needed.

Basic response format

All responses from the API gateway have the following format:

Example

{
  "status": "okay",
  "api_version": "1.0",
  "message" : "",
  "data": { }
}

Parameters

Name Description
version The API version.
data Response specific data, see below
message Message text describing nature of error
status "okay" if the call is processed correctly, otherwise will be "error"

Classifications

Post

Example

POST https://api.ingeniapi.com/classify

Parameters

Name Console Description
api_key

<API KEY>
Your API key
api_version
The version of the api to use (1.0)
min_tags 0
(Optional - defaults to 0) Return at least these many tags
max_tags 6
(Optional - defaults to 6) Return at most these many tags
CONTENT INPUT
text
The text you want Ingenia to classify
String "A comparative study of European secondary education systems illustrated issues related to their budgetary sustainability..."
url http://example.com
Source URL to read text from and classify from
String "http://example.com"
file document.pdf
Source document sent as multi-part form submission. At the moment only text based PDFs are supported, any other type will return a failure.
Binary

Notes: you need to provide either one of text, file or url for a call to be successful

Response

Example

{
  "api_version": "1.0",
  "status": "okay",

  "data": {
    "classification_status": "complete",
    "results": {

      "Software": {
        "id": 6,
        "tags": [
          {
            "id": 31,
            "name": "php",
            "score": 0.655
          },
          {
            "id": 90,
            "name": "php-session",
            "score": 0.315
          },
          {
            "id": 158,
            "name": "pass-by-reference",
            "score": 0.262
          },
          {
            "id": 160,
            "name": "debugging",
            "score": 0.24
          },
          {
            "id": 159,
            "name": "pass-by-value",
            "score": 0.198
          },
          {
            "id": 63,
            "name": "apache",
            "score": 0.132
          }
        ]
      }
    }
  }
}

Sample JSON response to tagging request

Fields

Name Description
classification_status
"complete" if the classification was completed successfully, otherwise it indicates which error occurred
results
The object containing Tag Sets that have matching tags. All Tags are returned in a sorted array, highest match first.

Recommendation engine

Similar to Text

Get

Example

POST https://api.ingeniapi.com/similar_to_text?api_key=<API KEY>

Parameters

Name Console Description
api_key

<API KEY>
Your API key
limit

10
Maximum number of items to return
full_text

1
Return full text of item on Ingenia
text  
Text to use as a starting point

Response

Example

{
  "status": "okay",
  "api_version": "1.0",
  "data": [
    { "item": { "id":12182, "text": "The fall in the rand has given wealthy Russians a new location to search for luxury..." }, "mode": "tag", "similarity": 0.62144 },
    { "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.62174 },
    { "item": { "id":25333, "text": "The market for RMB credit raised outside China has gone four weeks without a..." }, "mode": "word", "similariy": 0.62174 }
  ]

}

Sample JSON response

Fields

Name Description
data An array of item matches. KI ID is the item ID, mode is whether this is a 'tag' match based on the taggings of the item or a 'word' match based on the word content (text) of the item. Similarity is how close the matches are to the source in terms of tags and words

Similar to Tags

Get

Example

GET https://api.ingeniapi.com/similar_to_tags?api_key=<API KEY>

Parameters

Name Console Description
api_key

<API KEY>
Your API key
limit

10
Maximum number of items to return
full_text

1
Return full text of item on Ingenia
tag_ids  
JSON encoded array of tag IDs to use as starting point

Response

Example

{
  "status": "okay",
  "api_version": "1.0",
  "data": [
    { "item": { "id":12182, "text": "The fall in the rand has given wealthy Russians a new location to search for luxury..." }, "mode": "tag", "similarity": 0.62144 },
    { "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.62174 },
    { "item": { "id":25333, "text": "The market for RMB credit raised outside China has gone four weeks without a..." }, "mode": "word", "similariy": 0.62174 }
  ]

}

Sample JSON response

Fields

Name Description
data An array of item matches. KI ID is the item ID, mode is whether this is a 'tag' match based on the taggings of the item or a 'word' match based on the word content (text) of the item. Similarity is how close the matches are to the source in terms of tags and words

Summarization

Summarise

Post

Example

POST https://api.ingeniapi.com/summarise?api_key=<API KEY>

Parameters

Name Console Description
api_key

<API KEY>
Your API key
text  
text to summarise
include_tags

true
(Optional - defaults to true) If true the results be organised by tag, if false they are returned as a list
max_sentences

10
(Optional - defaults to 10) Maximum number of sentences to return
order_by_position

false
(Optional - defaults to false) If true, the results will be ordered as they appear in the text, if false, they will be ordered by score.

Response

Example

{
 "api_version":"1.0",
 "status":"okay",
 "data":{
    "results":{
       "newspaper-book":{
          "tags":[
             {
                "id":124889,
                "name":"improvement",
                "score":0.045,
                "sentences":[
                   {
                      "text":" Five others were given a requires improvement rating.",
                      "score":0.11,
                      "position":337
                   }
                ]
             }
          ],
          "id":294
       },
       "series":{
          "tags":[
             {
                "id":125312,
                "name":"schools",
                "score":0.045,
                "sentences":[
                   {
                      "text":" While four of the new schools earned Ofsteds highest rating of outstanding, only one was given an inadequate rating: the Discovery New School in Crawley, Sussex.",
                      "score":0.03,
                      "position":175
                   }
                ]
             }
          ],
          "id":297
       }
    }
 }
}

Sample JSON response

Fields

Name Description
text The extracted text of the sentence
score Ingenia's calculation of the importance of this part of the text.
position The character position within the original text this sentence starts at

Items

Items - Index

Get

Example

GET https://api.ingeniapi.com/items?api_key=<API KEY>

Parameters

Name Console Description
api_key

<API KEY>
Your API key
limit

10
(Optional - defaults to 10) How many results to return - max 500
offset

0
(Optional - defaults to 0) Return results offset by this amount (for pagination)
full_text

true
(Optional - defaults to false) If set to true then the full text of each item will be returned, otherwise only an excerpt will.

Response

Example

{

  "status": "okay",
  "api_version": "1.0",
  "data": [
      {
          "id": 4037,
          "text": "How do I save a datagrid to excel in vb.net? I know that this should be easy but how do I export/save a DataGridView to excel?...",
          "created_at": "2013-02-19T15:41:41+00:00",
          "updated_at": "2013-02-19T15:47:28+00:00",
          "tag_sets": [
              {
                  "Default": {
                      "id": 165,
                      "tags": [
                          {
                              "id": 2968,
                              "name": "vb.net",
                              "score": "0.9",
                              "user_selected": "f"
                          },
                          {
                              "id": 3015,
                              "name": "excel",
                              "score": "0",
                              "user_selected": "t"
                          }
                      ]
                  }
              }
          ]
      },
      {
          "id": 7243,
          "text": "What are the options for delivering Flash video? I'd like a concise introduction to the different options....",
          "created_at": "2013-02-20T11:21:04+00:00",
          "updated_at": "2013-02-20T11:21:04+00:00",
          "tag_sets": [
              {
                  "Default": {
                      "id": 165,
                      "tags": [
                          {
                              "id": 2869,
                              "name": "flash",
                              "score": "0",
                              "user_selected": "t"
                          },
                          {
                              "id": 3122,
                              "name": "video",
                              "score": "0",
                              "user_selected": "t"
                          }
                      ]
                  }
              }
          ]
      }
  ]
}

Sample JSON response

Fields

Name Description
data An array of items. See below for description of fields
tag_sets The tags, organised by tag_set, associated with this item via either training or by automatic classification
tags The tags associated with this item for a tag set
tag:score How certain the classifier is that this tag should be associated with this item.
tag:user_selected Shows if this association been set by a user ('t'), or created by the classifier automatically ('f').

Items - show

Get

Example

GET https://api.ingeniapi.com/items/<ITEM_ID>?api_key=<API KEY>

Parameters

Name Console Description
api_key

<API KEY>
Your API key
ITEM_ID

123
(required) ID of item you want details of

Response

Example

{

  "status": "okay",
  "api_version": "1.0",
  "data": 
      {
          "id": 4037,
          "text": "How do I save a datagrid to excel in vb.net? I know that this should be easy but how do I export/save a DataGridView to excel?...",
          "created_at": "2013-02-19T15:41:41+00:00",
          "updated_at": "2013-02-19T15:47:28+00:00",
          "tag_sets": [
              {
                  "Default": {
                      "id": 165,
                      "tags": [
                          {
                              "id": 2968,
                              "name": "vb.net",
                              "score": "0.9",
                              "user_selected": "f"
                          },
                          {
                              "id": 3015,
                              "name": "excel",
                              "score": "0",
                              "user_selected": "t"
                          }
                      ]
                  }
              }
          ]
      }
  }

Fields

Name Description
data An array of all your items, or just one item you wished to show.
tag_sets The tags, organised by tag_set, associated with this item via either training or by automatic classification
tags The tags associated with this item for a tag set
tag:score How certain the classifier is that this tag should be associated with this item.
tag:user_selected Shows if this association been set by a user ('t'), or created by the classifier automatically ('f').

Items - create

Post

Example

POST https://api.ingeniapi.com/items/

Parameters

Name Description
api_key
Your API key
json
JSON encoded string containing a hash of fields for the object. See below
file
INPUT: 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).
update_existing
(Optional - defaults to true) If the same text is sent, should the existing item be updated on Ingenia? If true then any tags supplied will overwrite those set on the existing item (default). If false, no data is changed and a response is returned with a 409 code (Conflict) together with the existing item as JSON.
classify
(Optional - defaults to false) If set to true, the response will also include a classification.

JSON Parameters

Name Description
text
INPUT: Text of item
url
INPUT: Source URL to pull text from
id
(Optional) If you wish to set the id of this new item you can supply a text/numeric id here. This can be used for mapping items back to your own dataset without needing to store the generated item id from ingenia.
tags
(Optional) The tags you want to have associated with this text item. JSON encoded.
Object [ "politics", "education", "r&d" ]
tag_sets
(Optional) Groups of tags (JSON encoded) that you consider of the same type; tags will come as belonging of a tag set, as below:
Object { "category": [ "politics", "education", "r&d" ], "geography": [ "united kingdom" ] }
tag_ids
(Optional) An array of IDs identifying the tags you wish to apply

Notes: at least one INPUT field is required. If more inputs are sent, fields are selected in the following order: text, url, file.

Notes: if the input already exists in your Ingenia account, this call will act like an 'update'. Warning: it will delete the previous tags, and apply the new ones you've sent.

Response

Example

{
  "status":"okay",
  "api_version":"1.0",
  "data":
  {
    "id":396025,
    "last_classified_at":null,
    "created_at":"2013-07-24T11:20:56+01:00",
    "updated_at":"2013-07-24T11:20:56+01:00",
    "text":"which is the best dvd for multiple lookupfields?",
    "tag_sets":[
      {
        "subject":
        {
          "id":217,
          "tags":[
            { "id":3875, "name":"multiplelookupfield" },
            { "id":3464, "name":"dvd" }
          ]
        }
      }
    ]
  }
}

Sample JSON response

Fields

Name Description
item:id ID of item just created
item:last_classified_at When this item was last automatically classified by the system
item:created_at Creation time stamp
item:tags Array of tags associated with item (with tag ID and name)

Items - update

Put

Example

PUT https://api.ingeniapi.com/items/<ITEM_ID>

Parameters

Name Description
api_key
Your API key
json
JSON encoded string containing a hash of fields for the object. See below
file
INPUT: 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).

JSON Parameters

Name Description
text
INPUT: Text of item
url
INPUT: Source URL to pull text from
id
(Optional) If you wish to set the id of this new item you can supply a text/numeric id here. This can be used for mapping items back to your own dataset without needing to store the generated item id form ingenia.
tags
(Optional) The tags you want to have associated with this text item. JSON encoded.
Object [ "politics", "education", "r&d" ]
tag_sets
(Optional) Groups of tags (JSON encoded) that you consider of the same type; tags will come as belonging of a tag set, as below:
Object { "category": [ "politics", "education", "r&d" ], "geography": [ "united kingdom" ] }
tag_ids
(Optional) An array of IDs identifying tags you wish to apply

Notes: INPUT fields optional and are selected in order of text, url then file.

Notes: if the 'tags' or 'tag sets' field is present then existing tags and tag sets will be removed from that item and replaced with those sent

Response

Example

{
  "status":"okay",
  "api_version":"1.0",
  "data":
  {
    "id":396025,
    "last_classified_at":null,
    "created_at":"2013-07-24T11:20:56+01:00",
    "updated_at":"2013-07-24T11:20:56+01:00",
    "text":"which is the best dvd for multiple lookupfields?",
    "tag_sets":[
      {
        "subject":
        {
          "id":217,
          "tags":[
            { "id":3875, "name":"multiplelookupfield" },
            { "id":3464, "name":"dvd" }
          ]
        }
      }
    ]
  }
}

Sample JSON response

Fields

Name Description
item:id ID of item just created
item:created_at Creation time stamp
item:tags Array of tags associated with item (with tag ID and name)

Items - delete

Delete

Example

DELETE https://api.ingeniapi.com/items/<ITEM_ID>

Parameters

Name Description
api_key
Your API key
ITEM_ID
ID of item to delete

Response

Example

{
  "status":"okay",
  "api_version":"1.0",
  "data": {
    "id":"destroyed",
  }
}

Sample JSON response

Fields

Name Description
data Returns "id" as "destroyed" if successful

Items - similar_to

similar_to

Example

GET https://api.ingeniapi.com/items/<ITEM_ID>/similar_to;

Parameters

Name Description
api_key
Your API key
ITEM_ID
ID of item to get similar items to

Response

Example

{
  "status": "okay",
  "api_version": "1.0",
  "data": [
    {
    "item": 
      {
      "id": 396000,
      "text": "Is there a good ruby gem for a WYSIWYG editor that will easily work with a rails app?..."
      },
    "mode": "word",
    "similarity": 0.7972
    }
  ]
}

Sample JSON response

Fields

Name Description
item One of the similar items
similarity How similar this item is, with a maximum of 1.0
mode Either 'tag' or 'word' - shows in which way this similarity was calculated.

Tags

Tags - index

Get

Example

GET https://api.ingeniapi.com/tags/?api_key=<API KEY>

Parameters

Name Console Description
api_key

<API KEY>
Your API key
limit

10
(Optional - defaults to 10) How many results to return - max 500
offset

0
(Optional - defaults to 0) Return results offset by this amount (for pagination)

Response

Example

{

  "status": "okay",
  "api_version": "1.0",
  "data": [
      {
          "id": 3464,
          "name": "dvd",
          "tag_set_id": 165
          "confidence": 0,
          "consistency": 0,
          "created_at": "2013-02-19T14:59:32+00:00".
          "description": "A tag about DVDs",
          "disposition": 0.5
          
      },
      {
          "id": 4801,
          "name": "delicious-api",
          "tag_set_id": 165
          "confidence": 0,
          "consistency": 0,
          "created_at": "2013-02-20T11:19:38+00:00",
          "description": "A tag about an API"
          "disposition": 0.4
      }
  ]

}

Sample JSON response

Fields

Name Description
data An array of your tags, or just the tag you wished to show. See 'show' for description of fields.

Tag - show

Get

Example

GET api.ingeniapi.com/tags/<TAG_ID>?api_key=<API KEY>

Parameters

Name Console Description
api_key

<API KEY>
Your API key
TAG_ID

123
(required) ID of tag that is sought after

Response

Example

{

  "status": "okay",
  "api_version": "1.0",
  "data": {
          "id": 3464,
          "name": "dvd",
          "tag_set_id": 165
          "confidence": 0,
          "consistency": 0,
          "created_at": "2013-02-19T14:59:32+00:00",
          "description": "A Tag about DVDs",
          "disposition": 0.5
      }

Fields

Name Description
data tag data fields
name The text given to the tag
created_at Date/time of tag creation
confidence Higher if Ingenia understands this tag; from 0 to 1
tag_set_id tag set to which the tag belongs
consistency Higher if the tag has been applied to items that are very similar to one another; from 0 to 1
description The description of the tag assigned either by the web UI or API.
disposition

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.

Tag - create

Post

Example

POST https://api.ingeniapi.com/tags/

Parameters

Name Description
api_key
Your API key
json
JSON encoded string containing a hash of fields for the object. See below

JSON Parameters

Name Description
name
The name of this tag
tag_set_id
The ID of the tag_set that this tag belongs to. (required)
description
Textual description of tag.
disposition

Response

Example

{
  "status":"okay",
  "api_version":"1.0",
  "data": {
      "id": 3464,
      "name": "dvd",
      "tag_set_id": 165
      "confidence": 0,
      "consistency": 0,
      "created_at": "2013-02-19T14:59:32+00:00",
      "description": "A tag about DVDs",
      "disposition": 0.5
  }
}

Sample JSON response

Fields

Name Description
data The tag you just created. See 'show' for explanation of fields.

Tag - update

Put

Example

PUT https://api.ingeniapi.com/tags/<TAG_ID>

Parameters

Name Description
api_key
Your API key
TAG_ID
The ID of the tag to modify
json
JSON encoded string containing a hash of fields for the object. See below

JSON Parameters

Name Description
name
The name of this tag
tag_set_id
The ID of the tag_set that this tag belongs to. (required)
description
Textual description of tag.
disposition

Response

Example

{
  "status":"okay",
  "api_version":"1.0",
  "data": {
      "id": 3464,
      "name": "dvd",
      "tag_set_id": 165
      "confidence": 0,
      "consistency": 0,
      "created_at": "2013-02-19T14:59:32+00:00",
      "description": "A tag about DVDs",
      "disposition": 0.5
  }
}

Sample JSON response

Fields

Name Description
data The tag you just created. See show tag for explanation of fields.

Tags - delete

Delete

Example

DELETE https://api.ingeniapi.com/tags/<TAG_ID>

Parameters

Name Description
api_key
Your API key
TAG_ID
ID of tag to delete

Response

Example

{
  "status":"okay",
  "api_version":"1.0",
  "data": {
    "id":"destroyed",
  }
}

Sample JSON response

Fields

Name Description
data Returns "id" as "destroyed" if successful

Tags - merge

Merge

Example

POST https://api.ingeniapi.com/tags/<TAG_ID>/merge

Parameters

Name Description
api_key
Your API key
TAG_ID
ID of tag to merge into
json
JSON encoded string containing a hash of fields for the object. See below

JSON Parameters

Name Description
tag_ids
An array of tag IDs that will be merged into this tag.

Response

Example

{
  "status":"okay",
  "api_version":"1.0",
  "data": {
    "tag_id": TAG_ID
  }
}

Sample JSON response

Fields

Name Description
data Returns the ID of the tag into which the other tags where merged if successful

Tag sets

Tag sets - index

Get

Example

GET https://api.ingeniapi.com/tag_sets/?api_key=<API KEY>

Parameters

Name Console Description
api_key

<API KEY>
Your API key
limit

10
(Optional - defaults to 10) How many results to return - max 500
offset

0
(Optional - defaults to 0) Return results offset by this amount (for pagination)

Response

Example

{

  "status": "okay",
  "api_version": "1.0",
  "data": [
    {
      "id":165,
      "name":"Document Subject",
      "sampling_type":0,
      "public_flag":false,
      "created_at":"2013-02-19T14:58:09+00:00",
      "updated_at":"2013-03-04T16:45:48+00:00"
    },
    {
      "id":175,
      "name":"Client Name",
      "sampling_type":0,
      "public_flag":false,
      "created_at":"2013-03-04T14:47:35+00:00",
      "updated_at":"2013-03-04T14:47:35+00:00"}
  ]

}

Sample JSON response

Fields

Name Description
data An array of tag_sets. See 'show' for explanation of fields

Tag sets - show

Get

Example

GET https://api.ingeniapi.com/tag_sets/<TAG_SET_ID>?api_key=<API KEY>

Parameters

Name Console Description
api_key

<API KEY>
Your API key
TAG_SET_ID

123
(required) ID of tag set sought after

Response

Example

{

  "status": "okay",
  "api_version": "1.0",
  "data": 
    {
      "id":165,
      "name":"Document Subject",
      "sampling_type":0,
      "public_flag":false,
      "created_at":"2013-02-19T14:58:09+00:00",
    }

Fields

Name Description
data:id The ID of the tag set just created for use in other API calls
data:public_flag Flag determining if other users can see or use this tag set (and tags)
tag_set:sampling_type Items trained only against tags in other tag sets: Could have been associated with these tags (0), Are not related to these tags (1)
tag_set:created_at The date/time this tag set was created

Tag sets - create

Post

Example

POST https://api.ingeniapi.com/tag_sets/

Parameters

Name Description
api_key
Your API key
json
JSON encoded string containing a hash of fields for the object. See below

JSON Parameters

Name Description
name
The name of this tag_set
sampling_type
Items trained only against tags in other tag sets: Could have been associated with these tags (0 Default), Are not related to these tags (1)

Response

Example

{
  "status":"okay",
  "api_version":"1.0",
  "data": {
    "id":8583,
    "name":"test-new-tag",
    "tag_set_id":165,
    "created_at":"2013-03-05T15:36:31+00:00",
    "updated_at":"2013-03-05T15:36:31+00:00"
  }
}

Sample JSON response

Fields

Name Description
data The tag you just created. See 'show' for explanation of fields

Tag sets - update

Put

Example

PUT https://api.ingeniapi.com/tag_sets/<TAG_SET_ID>

Parameters

Name Description
api_key
Your API key
TAG_SET_ID
The ID of the tag set to modify
json
JSON encoded string containing a hash of fields for the object. See below

JSON Parameters

Name Description
name
The name of this tag_set
sampling_type
Items trained only against tags in other tag sets: Could have been associated with these tags (0 Default), Are not related to these tags (1)

Response

Example

{
  "status":"okay",
  "api_version":"1.0",
  "data": {
    "id":8583,
    "name":"test-new-tag",
    "tag_set_id":165,
    "created_at":"2013-03-05T15:36:31+00:00",
    "updated_at":"2013-03-05T15:36:31+00:00"
  }
}

Sample JSON response

Fields

Name Description
data The tag you just created. See 'show' for explanation of fields

Tag sets - delete

Delete

Example

DELETE https://api.ingeniapi.com/tag_sets/<TAG_SET_ID>

Parameters

Name Description
api_key
Your API key
TAG_SET_ID
ID of the tag set to be deleted

Response

Example

{
  "status":"okay",
  "api_version":"1.0",
  "data": {
    "id":"destroyed",
  }
}

Sample JSON response

Fields

Name Description
data Returns "id" as "destroyed" if successful

Tag sets - merge

Post

Example

POST https://api.ingeniapi.com/tag_sets/<TAG_SET_ID>/merge

Parameters

Name Description
api_key
Your API key
TAG_SET_ID
ID of the tag set to merge into
json JSON encoded tag set IDs to merge into request tag set. Formatted as so "json": { "tag_ids": [ 12, 34, 56 ] }

Response

Example

{
  "status":"okay",
  "api_version":"1.0",
  "data": {
    "tag_set_id": 1234,
  }
}

Sample JSON response

Fields

Name Description
data tag set ID is the tag set ID sent in request

Administration

Status

Get

Use this to test your API key, see [status call] for details

Example

GET https://api.ingeniapi.com/status?api_key=<API KEY>

Response

Example

{
  "api_version": "1.0", 
  "status": "okay", 

  "data": {
    "total_items"        : 1554, 
    "processed_items"    : 1554, 
    "total_tag_sets"     : 2, 
    "processed_tag_sets" : 2, 
    "total_tags"         : 167,
    "processed_tags"     : 167,
    "ready_to_classify"  : "yes"
    "tag_ready_percent"  : "40.2"
  }
}

Sample JSON status response

Fields

Name Description
total_items Number of items you have created
processed_items Number of items Ingenia has processed
total_tag_sets Number of tag sets you have created
processed_tag_sets Number of tag sets Ingenia has processed
total_tags Number of tags you have created
processed_tags Number of tags Ingenia has processed
ready_to_classify Boolean (true/false): it will be true if all your data has been processed
tag_ready_percent Number of your tags that have been learnt and can be classified with

Clear data

Post

Delete items, tags and tag sets from Ingenia

Example

POST https://api.ingeniapi.com/clear_data?api_key=<API KEY>

Response

Example

{
  "api_version": "1.0", 
  "status": "okay", 

  "data": {
    "item_count": 123,
    "tag_set_count": 4,
    "tag_count": 6502
  }
}

Sample JSON status response

Fields

Name Description
item_count Number of items you have that are about to be deleted
tag_set_count Number of tag sets you have that are about to be deleted
tag_count Number of tags you have that are about to be deleted

Deprecated Calls

These calls have been deprecated and may not be supported in future versions of the API. New code should not use these calls

Training

This call has been superseded by POST /items and will be removed in the future

Post

Example

POST https://api.ingeniapi.com/train

Parameters

Name Console Description
api_key

<API KEY>
Your API key
api_version
The version of the api to use (1.0)
CONTENT INPUT
text
The original chunk of text, or "text item", against which you want Ingenia to learn; this includes all the text that relates to it (e.g., title, abstract, etc), for instance:
String "The government is launching a comprehensive audit of their university policies and how they affect applied research in the country..."
url http://example.com
Source URL to read text from and train with
String "http://example.com"
file document.pdf
Source document sent as multi-part form submission. At the moment only text based PDFs are supported, any other type will return a failure.
Binary
TAG INPUT
tags
The tags you want to have associated with this text item. JSON encoded
Object [ "politics", "education", "r&d" ]
tag_sets
Groups of tags (JSON encoded) that you consider of the same type; tags will come as belonging of a tag set, as below:
Object { "category": [ "politics", "education", "r&d" ], "geography": [ "united kingdom" ] }

Notes: you need to provide either one of text, file or url for a call to be successful

Response

Example

{
  "status": "okay",
  "api_version": "1.0",

  "data": {
    "training_id": 104,

    "tag_sets": {
      "Default": {
        "id": 1,
        "tags": {
          "some": 172,
          "tags": 173,
          "here": 174
        }
      }
    }
  }
}

Sample JSON learning response

Fields

Name Description
training_id
An integer, acting as the unique ID for that block of text.
api_version The version of the API.
training_id The ID of the item in the Ingenia database that can be used in other API item calls.
tag_sets Nested hash of tag sets that where used / created during this call.
tags Hash of tag names to tag IDs that where used / created during this call.
status
"okay" if the text item is received and processed correctly, otherwise we'll specify the problem, e.g., bad syntax, empty request, etc.