Ingenia API

Description

Ingenia analyses your textual content and automatically categorises it using your tags.

Endpoint

api.ingeniapi.com/v2/

Objects

item

Parameters

Name Type Default Description Example
text string Your item's content
id string Custom text/numeric id. This can be used for mapping items back to your own dataset without needing to store the item's generated id from ingenia. 785uU423aC
tag_ids array The tags you want to have associated with this text item. [ "politics", "education", "r&d" ]
tag_sets hash Groups of tags that you consider of the same type; tags will come as belonging of a tag set { "category": [ "politics", "education", "r&d" ], "geography": [ "united kingdom" ] }

Example

{"created_at":"2013-12-16T11:24:52+00:00","id":"e19e134d0e79153349ff78a674283e0b","last_classified_at":null,"text":"What type of cheese is the best cheese?","updated_at":"2013-12-16T11:24:56+00:00","tag_sets":[{"Cookery":{"id":107,"tags":["cheese"]}}}]}

tag

Parameters

Name Type Default Description Example
name string The name of your tag
tag_set_id integer required The ID of the tag_set that this tag belongs to. 3
description string Textual description of this tag.
disposition float 0.5 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. 0.7

tag_set

Parameters

Name Type Default Description Example
name string The name of your tag set

Resources

items

Nuggets of textual content: somewhat self-contained and homogeneous.

Requests

index

Path

/items

Description

An index of all your items

Parameters

Name Type Default Description Example
api_key string required Your API key hg7JHG6daSgf56FjhgsSa
limit integer 50 How many results to return
full_text boolean Should the results be shown with all their text
offset integer 0 Offset returned results by this amount
show

Path

/items/:id

Description

View a single item

Parameters

Name Type Default Description Example
api_key string required Your API key hg7JHG6daSgf56FjhgsSa
full_text boolean Should the results be shown with all their text
id string required The ID of the item you want to show. 3casjghd67
create

Path

/items

Description

Create a new item

Parameters

Name Type Default Description Example
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).
update_existing 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 Should the response also include a classification.
api_key string required Your API key hg7JHG6daSgf56FjhgsSa
item A text item
update

Path

/items/:id

Description

Update an existing item

Parameters

Name Type Default Description Example
id string required The ID of the item you want to update. 3casjghd67
api_key string required Your API key hg7JHG6daSgf56FjhgsSa
item A text item
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).
delete

Path

/items/:id

Description

Delete an existing item

Parameters

Name Type Default Description Example
id string required The ID of the item you want to delete. 3casjghd67
api_key string required Your API key hg7JHG6daSgf56FjhgsSa

tags

Tags are meaningful words or expressions that you want to associate to some or all your content items.

Requests

index

Path

/tags

Description

An index of all your tags

Parameters

Name Type Default Description Example
api_key string required Your API key hg7JHG6daSgf56FjhgsSa
limit integer 50 How many results to return
offset integer 0 Offset returned results by this amount
show

Path

/tags/:id

Description

View a single tag

Parameters

Name Type Default Description Example
id integer required The ID of the tag you want to show. 42
api_key string required Your API key hg7JHG6daSgf56FjhgsSa
create

Path

/tags

Description

Create a new tag

Parameters

Name Type Default Description Example
api_key string required Your API key hg7JHG6daSgf56FjhgsSa
tag A JSON tag
update

Path

/tags/:id

Description

Update an existing tag

Parameters

Name Type Default Description Example
id integer required The ID of the tag you want to update. 42
api_key string required Your API key hg7JHG6daSgf56FjhgsSa
delete

Path

/tags/:id

Description

Delete an existing tag

Parameters

Name Type Default Description Example
id integer required The ID of the tag you want to delete. 42
api_key string required Your API key hg7JHG6daSgf56FjhgsSa

tag_sets

Tag sets are thematically consistent groups of tags, such as, say, world countries, business sectors, product types, companies, concepts, topics, etc.

Requests

index

Path

/tag_sets

Description

An index of all your Tag Sets

Parameters

Name Type Default Description Example
api_key string required Your API key hg7JHG6daSgf56FjhgsSa
limit integer 50 How many results to return
offset integer 0 Offset returned results by this amount
show

Path

/tag_sets/:id

Description

View a single Tag Set

Parameters

Name Type Default Description Example
id integer required The ID of the Tag Set you want to show. 412
api_key string required Your API key hg7JHG6daSgf56FjhgsSa
create

Path

/tag_sets

Description

Create a new Tag Set

Parameters

Name Type Default Description Example
api_key string required Your API key hg7JHG6daSgf56FjhgsSa
tag_set A tag set
update

Path

/tag_sets/:id

Description

Update an existing Tag Set

Parameters

Name Type Default Description Example
id integer required The ID of the Tag Set you want to update. 412
api_key string required Your API key hg7JHG6daSgf56FjhgsSa
tag_set A tag set
delete

Path

/tag_sets/:id

Description

Delete an existing Tag Set

Parameters

Name Type Default Description Example
id integer required The ID of the Tag Set you want to delete. 412
api_key string required Your API key hg7JHG6daSgf56FjhgsSa