REST methods for IBM Concept Insights

NOT OFFICIAL! Demonstrates import specification in swagger format only (from http://www.ibm.com/smarterplanet/us/en/ibmwatson/developercloud/apis/)

Base URI

https://gateway.watsonplatform.net/concept-insights-beta/api/v1
API Methods
Concept-insights
DELETE /v1/corpus/{user}/{corpus}
GET /v1/corpus/{user}/{corpus}
PUT /v1/corpus/{user}/{corpus}
DELETE /v1/corpus/{user}/{corpus}/{documentid}
GET /v1/corpus/{user}/{corpus}/{documentid}
POST /v1/corpus/{user}/{corpus}/{documentid}
PUT /v1/corpus/{user}/{corpus}/{documentid}
GET /v1/graph/{user}/{graphid}
POST /v1/graph/{user}/{graphid}
GET /v1/graph/{user}/{graphid}/{conceptid}
GET /v1/searchable/{user}/{corpus}
GET /v1/searchable/{user}/{corpus}/{documentid}
GET /v1/searchable/{user}/{corpus}/{documentid}
Retrieves the available corpora
GET /v1/corpus

Authenticated requests return public collections and collections with read permission.<h4>Example Request</h4>Retrieves the available corpora:<pre>curl -u user:password 'https://gateway.watsonplatform.net/concept-insights-beta/api/v1/corpus/'<br><br>[<br> {<br> "access": "private",<br> "id": "/user/test",<br> "users": [<br> {<br> "permission": "ReadWriteAdmin",<br> "uid": "user"<br> }<br> ]<br> }<br>]</pre>

Responses

200 Success
Body
400 Bad Request
Body
500 Internal Server Error
Body
Deletes a corpus by ID
DELETE /v1/corpus/{user}/{corpus}

Requires 'Admin' permission to the corpus. The operation also deletes all the documents contained in the corpus.<h4>Example Request</h4>Deletes corpus 'test':<pre>curl -D - -X DELETE -u user:password 'https://gateway.watsonplatform.net/concept-insights-beta/api/v1/corpus/user/test'<br><br>HTTP/1.1 200 OK</pre>

Path variables

user
string required

User ID

corpus
string required

Corpus ID

Responses

200 Corpus deleted
400 Bad Request
Body
500 Internal Server Error
Body
Retrieves the content of a corpus
GET /v1/corpus/{user}/{corpus}

Returns the content of the corpus if it has public access or has read permission. The content of a corpus is the list of document IDs within a corpus.<h4>Example Request</h4>Retrieves the list of documents in '/user/test' corpus:<pre>curl -u user:password https://gateway.watsonplatform.net/concept-insights-beta/api/v1/corpus/user/test?limit=10<br><br>["a", "foo", "testdoc", "testdoc"]</pre>

Path variables

user
string required

User ID

corpus
string required

Corpus ID

Request parameters

limit
integer optional

Number of possible items to return in the range 0 – 10. Specify '0' to return the maximum value of 100,000.

cursor
integer optional

Number of items to skip

Responses

200 Corpus deleted
400 Bad Request
Body
500 Internal Server Error
Body
Creates an empty corpus
PUT /v1/corpus/{user}/{corpus}

<h4>Example Request</h4>Creates corpus '/user/test' with private access:<pre>curl -D - -X PUT -u user:password -d '{"access":"private"}' <br> 'https://gateway.watsonplatform.net/concept-insights-beta/api/v1/corpus/user/test'<br><br>HTTP/1.1 201 Created</pre>

Path variables

user
string required

User ID

corpus
string required

Corpus ID

Request body

Responses

201 Corpus created
400 Bad Request
Body
500 Internal Server Error
Body
Deletes a document by ID
DELETE /v1/corpus/{user}/{corpus}/{documentid}

Requires write access to the corpus.<h4>Example Request</h4>Deletes the '/user/test/foo.mw' document:<pre>curl -D - -X DELETE -u user:password 'https://gateway.watsonplatform.net/concept-insights-beta/api/v1/corpus/user/test/mydoc'<br><br>HTTP/1.1 200 OK</pre>

Path variables

user
string required

User ID

corpus
string required

Corpus ID

documentid
string required

Node ID

Responses

200 Node created
400 Bad Request
Body
500 Internal Server Error
Body
Retrieves a document from a corpus
GET /v1/corpus/{user}/{corpus}/{documentid}

Authenticated requests return documents from a corpus if it has public access and from a corpus with read permission.<h4>Example Request</h4>Retrieves the '/user/test/ibmnews' document:<pre>curl -D - -u user:password 'https://gateway.watsonplatform.net/concept-insights-beta/api/v1/corpus/user/test/ibmnews'<br><br>HTTP/1.1 200 OK<br>Content-Length: 13<br>Content-Type: application/json<br>Date: Thu, 18 Sep 2014 14:23:08 GMT<br><br>{<br> "id": "ibmnews",<br> "label": "IBM News",<br> "parts": [<br> {<br> "name": "excerpt",<br> "uri": "",<br> "type": "",<br> "data": "IBM announced today a new cognitive system..."<br> }<br> ]<br>}</pre>

Path variables

user
string required

User ID

corpus
string required

Corpus ID

documentid
string required

Document ID

Responses

200 OK
Body
Updates a document by ID
POST /v1/corpus/{user}/{corpus}/{documentid}

Requires write access to the corpus.<h4>Example Request</h4>Updates the '/user/test/mydoc' document:<pre>curl -D - -X POST -u user:password -d '{"label":"a new label","parts":[{"data":"International Business Machines <br> announced today a new cognitive system.","name":"field"}]}' <br> 'https://gateway.watsonplatform.net/concept-insights-beta/api/v1/user/test/mydoc'</pre>

Path variables

user
string required

User ID

corpus
string required

Corpus ID

documentid
string required

Document ID

Request body

Responses

201 Node created
400 Bad Request
Body
500 Internal Server Error
Body
Creates a document in a corpus
PUT /v1/corpus/{user}/{corpus}/{documentid}

Requires write access to the corpus.<h4>Example Request</h4>Creates the '/user/test/ibmnews' document:<pre>curl -D - -X PUT -u user:password -d '{"label":"IBM News","parts":[{"name":"excerpt","data":"IBM announced today <br> a new cognitive system..."}]}' 'https://gateway.watsonplatform.net/concept-insights-beta/api/v1/corpus<br> /user/test/ibmnews'<br><br>HTTP/1.1 201 Created</pre>

Path variables

user
string required

User ID

corpus
string required

Corpus ID

documentid
string required

Document ID

Request body

Responses

201 Document created
400 Bad Request
Body
500 Internal Server Error
Body
Retrieves the metadata for multiple concepts
GET /v1/graph

Similar to the GET /v1/graph/{user}/{graphid}/{conceptid} method, but for multiple concepts.<h4>Example Request</h4>Retrieves the metadata for two concepts: "IBM" and "Information theory":<pre>curl --get -u username:password --data-urlencode "func=minfo" --data-urlencode <br> 'ids=["/graph/wikipedia/en-20120601/Information_theory", <br> "/graph/wikipedia/en-20120601/IBM"]' 'https://gateway.watsonplatform.net/concept-insights-beta/api/v1/graph' <br> | python -mjson.tool<br>[<br> {<br> "abstract": "Information theory is a branch of applied mathematics and electrical engineering involving <br>the quantification of information. Information theory was developed by Claude E. Shannon to find fundamental <br>limits on signal processing operations such as compressing data and on reliably storing and communicating data.",<br> "id": "Information_theory",<br> "label": "Information theory",<br> "link": "http://en.wikipedia.org/wiki/Information_theory",<br> "type": "wiki_resource"<br> },<br> {<br> "abstract": "International Business Machines Corporation or IBM is an American multinational technology <br>and consulting corporation headquartered in Armonk, New York, United States. IBM manufactures and sells <br>computer hardware and software, and it offers infrastructure, hosting and consulting services in areas <br>ranging from mainframe computers to nanotechnology.",<br> "id": "IBM",<br> "label": "IBM",<br> "link": "http://en.wikipedia.org/wiki/IBM",<br> "ontology": [<br> "Company",<br> "Organisation",<br> "Agent"<br> ],<br> "thumbnail": "http://upload.wikimedia.org/wikipedia/commons/thumb/5/51/IBM_logo.svg/200px-IBM_logo.svg.png",<br> "type": "wiki_resource"<br> }<br>]</code></pre>

Request parameters

func
string required

Response requested

Enumeration:
minfo
ids
string required

Array of concept URIs

Responses

200 Success
Body
400 Bad Request
Body
500 Internal Server Error
Body
Searches for graph concepts by using partial matches
GET /v1/graph/{user}/{graphid}

Searches for partial matches on the concept label field. The comparison is not case sensitive. When the prefix parameter is set to true, the main use of this method is to build query boxes that offer auto-complete.<h4>Example Request</h4>Retrieves four concepts in which the label starts with the word 'cognitive':<pre>curl -u username:password 'https://gateway.watsonplatform.net/concept-insights-beta/api/v1/graph/wikipedia/en-20120601?<br> func=labelSearch&label=cognitive&prefix=true&limit=4' | python -m json.tool<br>[<br> {<br> "abstract": "In science, cognition: refers to mental processes. These processes include attention, <br> memory, producing and understanding language, solving problems, and making decisions. Cognition is <br> studied in various disciplines such as psychology, philosophy, linguistics, science and computer <br> science. Usage of the term varies in different disciplines; for example in psychology and cognitive <br> science, it usually refers to an information processing view of an individual's psychological functions.",<br> "id": "Cognition",<br> "label": "Cognitive",<br> "link": "http://en.wikipedia.org/wiki/Cognition",<br> "type": "wiki_resource"<br> },<br> {<br> "abstract": "Cognitive psychology is a subdiscipline of psychology exploring internal mental processes. <br> It is the study of how people perceive, remember, think, speak, and solve problems. Cognitive psychology <br> differs from previous psychological approaches in two key ways. It accepts the use of the scientific <br> method, and generally rejects introspection as a valid method of investigation - in contrast with <br> such approaches as Freudian psychology.",<br> "id": "Cognitive_psychology",<br> "label": "Cognitive approach",<br> "link": "http://en.wikipedia.org/wiki/Cognitive_psychology",<br> "type": "wiki_resource"<br> },<br> {<br> "abstract": "Cognitive behavioral therapy (CBT) is a psychotherapeutic approach that addresses dysfunctional <br> emotions, behaviors, and cognitions through a goal-oriented, systematic process. The name refers to <br> behavior therapy, cognitive therapy, and to therapy based upon a combination of basic behavioral and <br> cognitive research. CBT is effective for the treatment of a variety of conditions, including mood, <br> anxiety, personality, eating, substance abuse, tic, and psychotic disorders.",<br> "id": "Cognitive_behavioral_therapy",<br> "label": "Cognitive behavior modification",<br> "link": "http://en.wikipedia.org/wiki/Cognitive_behavioral_therapy",<br> "type": "wiki_resource"<br> },<br> {<br> "abstract": "A cognitive architecture is a blueprint for intelligent agents. It proposes (artificial) <br> computational processes that act like certain cognitive systems, most often, like a person, or acts <br> intelligent under some definition. Cognitive architectures form a subset of general agent <br> architectures. The term 'architecture' implies an approach that attempts to model not only <br> behavior, but also structural properties of the modelled system.",<br> "id": "Cognitive_architecture",<br> "label": "Cognitive architecture",<br> "link": "http://en.wikipedia.org/wiki/Cognitive_architecture",<br> "type": "wiki_resource"<br> }<br>]<br></pre>

Path variables

user
string required

User

Enumeration:
wikipedia
graphid
string required

Graph ID

Enumeration:
en-20120601

Request parameters

func
string required

Response requested

Enumeration:
labelSearch
label
string required

String to use as search

limit
integer optional

Unique ID of the knowledge base that contains the concept.

prefix
string optional

Prefix search flag. Set to true to treat the input string as a prefix to the label. Useful to restrict the results to labels that begin with the label string.

Default:
false

Responses

200 Success
Body
400 Bad Request
Body
500 Internal Server Error
Body
GET /v1/graph/{user}/{graphid}

Each entry in the response is augmented with a score field in the range 0.5 - 1.0. The higher the score, the more evidence that the query concept is related to the concept in the returned entry.<h4>Example Request</h4>Retrieves high-level concepts that are related to color blindness:<pre>curl --get -u username:password --data-urlencode "func=related" --data-urlencode <br> 'concepts=["/graph/wikipedia/en-20120601/Color_blindness"]' --data-urlencode "level=0" <br> 'https://gateway.watsonplatform.net/concept-insights-beta/api/v1/graph/wikipedia/en-20120601/' <br> | python -m json.tool<br>[<br> {<br> "score": 0.9773398,<br> "uri": "/v1/graph/wikipedia/en-20120601/Retina"<br> },<br> {<br> "score": 0.9358882,<br> "uri": "/v1/graph/wikipedia/en-20120601/Human_eye"<br> },<br> {<br> "score": 0.92706054,<br> "uri": "/v1/graph/wikipedia/en-20120601/Color"<br> },<br> {<br> "score": 0.9090508,<br> "uri": "/v1/graph/wikipedia/en-20120601/Ophthalmology"<br> },<br> {<br> "score": 0.886107,<br> "uri": "/v1/graph/wikipedia/en-20120601/Zygosity"<br> }<br>]</pre>

Path variables

user
string required

User

Enumeration:
wikipedia
graphid
string required

Graph ID

Enumeration:
en-20120601

Request parameters

func
string required

Response requested

Enumeration:
related
concepts
string required

Array of concept IDs, each identifying a concept.

level
integer optional

Number in the range 0 - 3 that represents the level of popularity of related concepts. A value of 0 indicates a very popular concept or a high-level concept (for example, countries, institutions, celebrities, and subject areas). Values ranging from 1 - 3 indicate less famous concepts that are likely to be related to fewer other concepts and are usually domain-specific.

limit
integer optional

Number in the range 1 - 10 that represents the number of possible concepts to return. Fewer concepts might be returned if the level parameter is set to "0".

Responses

200 Success
400 Bad Request
Body
500 Internal Server Error
Body
Identifies concepts in a piece of text
POST /v1/graph/{user}/{graphid}

Attempts to identify words in the text that correspond to concepts in the graph. You can use the operation to test sample content for suitability in the Concept Insights service before it is ingested in a corpus. For useful results, use content that has at least 10 Wikipedia concepts with a score of 0.7 or higher:<pre>curl -u username:password -d "My heart sank when I saw that Deep Blue won against Kasparov. Computer science <br> and humanity would never be the same after that." 'https://gateway.watsonplatform.net/concept-insights-beta<br> /api/v1/graph/wikipedia/en-20120601?func=annotateText' | python -m json.tool<br>[<br> {<br> "concept": "/graph/wikipedia/en-20120601/Computer_science",<br> "coords": [<br> [<br> 62,<br> 70<br> ],<br> [<br> 71,<br> 78<br> ]<br> ],<br> "weight": 0.8426364<br> },<br> {<br> "concept": "/graph/wikipedia/en-20120601/Deep_Blue_vs_Kasparov",<br> "coords": [<br> [<br> 30,<br> 34<br> ],<br> [<br> 35,<br> 39<br> ],<br> [<br> 52,<br> 60<br> ]<br> ],<br> "weight": 0.7565227<br> },<br> {<br> "concept": "/graph/wikipedia/en-20120601/Humanity",<br> "coords": [<br> [<br> 83,<br> 91<br> ]<br> ],<br> "weight": 0.6133502<br> }<br>]</pre></code>

Path variables

user
string required

User

Enumeration:
wikipedia
graphid
string required

Graph ID

Enumeration:
en-20120601

Request parameters

func
string required

Response requested

Enumeration:
annotateText

Request body

string

Responses

200 Success
400 Bad Request
Body
500 Internal Server Error
Body
Retrieves the metadata for a concept
GET /v1/graph/{user}/{graphid}/{conceptid}

The graph is restricted to '/wikipedia/en-20120601/.' The concept is the string that Wikipedia uses for an article's URI. For example, for 'The New York Times,' the concept is 'The_New_York_Times.'<h4>Example Request</h4>Retrieves the metadata for concept "IBM":<pre><code>curl -u username:password -s 'https://gateway.watsonplatform.net/concept-insights-beta/api/v1/graph<br> /wikipedia/en-20120601/IBM'| python -mjson.tool<br>{<br> "abstract": "International Business Machines Corporation or IBM is an American multinational technology <br>and consulting corporation headquartered in Armonk, New York, United States. IBM manufactures and sells <br>computer hardware and software, and it offers infrastructure, hosting and consulting services in areas <br>ranging from mainframe computers to nanotechnology.",<br> "id": "IBM",<br> "label": "IBM",<br> "link": "http://en.wikipedia.org/wiki/IBM",<br> "ontology": [<br> "Company",<br> "Organisation",<br> "Agent"<br> ],<br> "thumbnail": "http://upload.wikimedia.org/wikipedia/commons/thumb/5/51/IBM_logo.svg/200px-IBM_logo.svg.png",<br> "type": "wiki_resource"<br>}</code></pre>

Path variables

user
string required

User

Enumeration:
wikipedia
graphid
string required

description

Enumeration:
en-20120601
conceptid
string required

description

Responses

200 Success
Body
400 Bad Request
Body
500 Internal Server Error
Body
Performs a fuzzy search of corpus node labels and concept URIs for some text
GET /v1/searchable/{user}/{corpus}

The main use of this operation is to build auto-complete query boxes. The order of the concept URIs is influenced by the corpus contents. Concepts to the corpus are prioritized. Returns corpus listings with read permission.<h4>Example Request</h4>Finds both concepts and searchables in the 'ibmresearcher' domain with a prefix of 'mark.' Limit set to two items for each:<pre>curl -u username:password 'https://gateway.watsonplatform.net/concept-insights-beta/api/v1/searchable/public/ibmresearcher<br> ?func=labelSearch&query=mark&prefix=true&concepts=true&limit=2' | python -m json.tool<br><br>[<br> {<br> "id": "zurich-mla",<br> "label": "Lantz, Mark A.",<br> "result":{<br> "id": "zurich-mla",<br> "label": "Lantz, Mark A.",<br> "lastbuild": "0001-01-01T00:00:00Z",<br> "lastmodified": "2015-01-07T16:32:09Z",<br> "state":{<br> "stage": "compute",<br> "status": "locked",<br> "timestamp": "2015-01-31T03:55:06.216Z"<br> },<br> "type": "",<br> "user": {<br> "thumbnail": "http://researcher.watson.ibm.com/researcher/photos/942.jpg"<br> }<br> },<br> "type": "/public/ibmresearcher"<br> },<br> {<br> "id": "us-mferriss",<br> "label": "FERRISS, MARK A.",<br> "result":{<br> "id": "us-mferriss",<br> "label": "FERRISS, MARK A.",<br> "lastbuild": "0001-01-01T00:00:00Z",<br> "lastmodified": "2015-01-16T11:22:24-05:00",<br> "state":{<br> "stage": "ready",<br> "status": "done",<br> "timestamp": "2015-01-30T08:54:40.34Z"<br> },<br> "type": "",<br> "user": {<br> "thumbnail": "http://researcher.watson.ibm.com/researcher/photos/1274.jpg"<br> }<br> },<br> "type": "/public/ibmresearcher"<br> },<br> {<br> "id": "Garbagecollection(computer_science)",<br> "label": "Mark and sweep",<br> "result":{<br> "abstract": "In computer science, garbage collection (GC) is a form of automatic memory management. <br> The garbage collector, or just collector, attempts to reclaim garbage, or memory occupied by objects <br> that are no longer in use by the program. Garbage collection was invented by John McCarthy around <br> 1959 to solve problems in Lisp.",<br> "id": "Garbagecollection(computer_science)",<br> "label": "Garbage collection (computer science)",<br> "type": "wiki_resource",<br> "link": "http://en.wikipedia.org/wiki/Garbage_collection_(computer_science)"<br> },<br> "type": "concept"<br> },<br> {<br> "id": "Markov_chain",<br> "label": "Markhow chain",<br> "result":{<br> "abstract": "A Markov chain, named after Andrey Markov, is a mathematical system that undergoes transitions <br> from one state to another, between a finite or countable number of possible states. It is a random <br> process characterized as memoryless: the next state depends only on the current state and not on <br> the sequence of events that preceded it. This specific kind of \"memorylessness\" is called the <br> Markov property. Markov chains have many applications as statistical models of real-world processes.",<br> "id": "Markov_chain",<br> "label": "Markov model",<br> "type": "wiki_resource",<br> "link": "http://en.wikipedia.org/wiki/Markov_chain"<br> },<br> "type": "concept"<br> }<br>]</pre>

Path variables

user
string required

User

corpus
string required

Corpus ID

Request parameters

func
string required

Response requested

Enumeration:
labelSearch
query
string required

String to search for

prefix
string optional

Prefix search flag. Set to true to specify that the query parameter string is a prefix query.

Default:
false
concept
string optional

Concepts flag. Set to true to return concepts in addition to searchables.

Default:
false
limit
integer optional

Number in the range 1 – 10 that represents the number of possible concepts to return.

Responses

200 OK
Performs a conceptual search within a corpus
GET /v1/searchable/{user}/{corpus}

Returns documents from the specified corpus that are sorted by conceptual relevance to the query. Additionally, the operation returns an explanation of why concepts within the corpus are relevant to the query, with enough information to render the original text with concepts relevant to the query.<h4>Example Requests</h4>Finds documents in /'user/corpus' that are conceptually related to Java virtual machine:<pre>curl -u username:password 'https://gateway.watsonplatform.net/concept-insights-beta/api/v1/searchable/public/ibmresearcher<br> ?func=semanticSearch&&ids=["/graph/wikipedia/en-20120601/Java_virtual_machine"]&limit=4'</pre><p/>Finds documents in '/user/corpus' that are conceptually related to the /'user/mydocs/foo' document:<pre>curl -u username:password ''https://gateway.watsonplatform.net/concept-insights/beta/api/v1/searchable/user/corpus<br> ?func=semanticSearch&ids=["/corpus/user/mydocs/foo"]&limit=4'</pre><p/>Find IBM researchers by using Charlie Bennet (us-bennetc) as an example:<pre>curl --get -u username:password --data-urlencode "limit=4" --data-urlencode "func=semanticSearch" <br> --data-urlencode 'ids=["/corpus/public/ibmresearcher/us-bennetc"]' <br> 'https://gateway.watsonplatform.net/concept-insights-beta/api/v1/searchable/public/ibmresearcher'</pre>

Path variables

user
string required

User

corpus
string required

Corpus ID

Request parameters

func
string required

Response requested

Enumeration:
semanticSearch
ids
unknown required

Reference to a Concept URI or Searchable

cursor
integer optional

Number of items to skip

limit
integer optional

Number in the range 1 – 10 that represents the number of possible concepts to return.

Responses

200 OK
Retrieves the processing state of a document
GET /v1/searchable/{user}/{corpus}/{documentid}

The item is ready for semantic search when stage is in the 'ready' state. The intermediate stages are 'annotate and 'compute.' When you update a corpus document, the 'annotate' process restarts.<h4>Example Request</h4><pre>curl 'https://gateway.watsonplatform.net/concept-insights-beta/api/v1/searchable/user/corpus/documentid?func=getState'<br><br>{<br> "stage": "ready",<br> "status": "done",<br> "timestamp": "2014-03-31T20:04:57.74-04:00"<br>}</pre>

Path variables

user
string required

User

corpus
string required

Corpus ID

documentid
string required

Document ID

Request parameters

func
string required

Response requested

Enumeration:
getState

Responses

201 Success
Body
400 Bad Request
Body
500 Internal Server Error
Body
GET /v1/searchable/{user}/{corpus}/{documentid}

<h4>Example Request</h4>Asks how related a document is by score to the 'Hash_functions' concept:<pre>curl -u username:password 'https://gateway.watsonplatform.net/concept-insights-beta/api/v1/searchable/public/ibmresearcher<br> /us-bennetc?func=relScore&dest=["/graph/wikipedia/en-20120601/Hash_functions"]'<br><br>{<br> "score":0.9582957029342651<br>}</pre>

Path variables

user
string required

User

corpus
string required

Corpus ID

documentid
string required

Document ID

Request parameters

func
string required

Response requested

Enumeration:
relScore
dest
unknown required

Reference to a Concept URI

Responses

201 Success
Body
400 Bad Request
Body
500 Internal Server Error
Body
Ping the service to verify that that it is available
GET /v1/ping

Responses

200 OK
Uploads the seeds list
POST /v1/upload

Step 1. Upload the seed list.

Request parameters

dataset
string required

Dataset to run against.

Enumeration:
mtsamples
twitter
label
string required

A conceptual classification of the seed terms.

Request body

Responses

200 OK
Body
400 Missing label or seeds. Or error uploading seed list. Or error creating the job.
500 Job is not ready
Get the status of a job
GET /v1/status

Step 2. Query the status of the job created with the POST /upload operation.

Request parameters

jobid
string required

The jobid returned from the POST /upload operation.

Responses

200 OK
Body
400 Missing or incorrect jobid
Retrieves the seed list and deletes the results
PUT /v1/result

Step 3. Retrieve the concept-expanded seed list and delete the results.

Request body

Responses

200 OK
400 Missing jobid or seed list. Or error deleting or retrieving seed list. Or error setting state.
500 Job is not ready
Language-identification
POST /v1/txtlid/0
Sends text to the server
POST /v1/txtlid/0

You can detect the language of text that is encoded as UTF-8 by using the Watson Language Identification (LID) service.

Request parameters

sid
string required

Language identification of the text.

Default:
lid-generic
txt
string required

The text that you want to process. Must be encoded as UTF-8.

rt
string required

Return type. The content type to accept.

Enumeration:
json
text
xml
Default:
text

Responses

200 OK
Machine-translation
Sends text to the server for translation
POST /v1/smt/0

Request parameters

sid
string required

Language identifiers. Uses the ISO language and country code in the form "mt-<from-language>-<to-language>".

Enumeration:
mt-enus-eses
mt-eses-enus
mt-enus-frfr
mt-frfr-enus
mt-enus-ptbr
mt-ptbr-enus
mt-arar-enus
txt
string required

The text that you want to translate. Must be encoded as UTF-8.

rt
string optional

The format of the translated content that you want.

Enumeration:
json
text
xml
Default:
text

Responses

200 OK
Message-resonance
Retrieves the ringscore for terms within a community
GET /v1/ringscore

The ringscore has the range 0 - 99. The larger the ringscore, the more effective the term.

Request parameters

text
string required

The term to use for the ringscore

dataset
integer optional

The ID of the community to which the ringscore applies. Use GET /v1/datasets to retrieve the communities. If dataset is not included, the service returns an aggregate ring score.

Responses

200 OK
Body
400 Missing term
Retrieves the datasets
GET /v1/datasets

Responses

200 OK
Body
400 Cannot interpret the request
Natural-language-classifier
POST /v1/classifiers
POST /v1/classifiers/{classifier_id}/classify
DELETE /v1/classifiers/{classifier_id}
GET /v1/classifiers/{classifier_id}
Creates a classifier
POST /v1/classifiers

Sends data to create and train a classifier, and returns information about the new classifier. <br>The status has the value of Training when the operation is successful, and might remain at this status for a while.<h4>Example Request</h4>Creates a classifier with the information in the file train.json:<pre>curl -X POST -u user:password -H "Content-Type:application/json" -d @train.json <br> "https://gateway.watsonplatform.net/natural-language-classifier-experimental/api/v1/classifiers"</pre>

Request body

Responses

200 OK
400 Bad request. Likely caused by a missing `training_data` property or malformed JSON. Or this request

Bad request. Likely caused by a missing training_data property or malformed JSON. Or this request exceeds the maximum number of classifiers for this user or service instance.

413 Training data is too large
Retrieves the list of classifiers for the user
GET /v1/classifiers

Returns an empty array if no classifiers are available.<h4>Example Request</h4><pre>curl -u user:password "https://gateway.watsonplatform.net/natural-language-classifier-experimental/api/v1/classifiers"</pre>

Responses

Returns classification information for a classifier on a phrase
POST /v1/classifiers/{classifier_id}/classify

The status must be Available before you can use the classifier to classify calls. Use GET /classifiers/{classifier_id} to retrieve the status.<h4>Example Request</h4>Classify a phrase with the classifier 6C76AF-nlc-43:<pre>curl -X POST -u user:password -H "Content-Type:application/json" -d "{\"text\":\"what is your phone number?\"}" <br> "https://gateway.watsonplatform.net/natural-language-classifier-experimental/api/v1/classifiers/6C76AF-nlc-43/classify"</pre>

Path variables

classifier_id
string required

Classifier ID to use

Responses

400 Bad request. Likely caused by a classifier status other than `Available` or malformed JSON.
404 The classifier does not exist or is not available to the user
Deletes a classifier
DELETE /v1/classifiers/{classifier_id}

<h4>Example Request</h4>Delete the classifier 6C76AF-nlc-43:<pre>curl -X DELETE -u user:password "https://gateway.watsonplatform.net/natural-language-classifier-experimental<br> /api/v1/classifiers/6C76AF-nlc-43"</pre>

Path variables

classifier_id
string required

Classifier ID to delete

Responses

200 OK. Deleted.
404 The classifier does not exist or is not available to the user
Returns the training status of a classifier
GET /v1/classifiers/{classifier_id}

<h4>Example Request</h4>Retrieves the information for classifier with the id 6C76AF-nlc-43:<pre>curl -u user:password "https://gateway.watsonplatform.net/natural-language-classifier-experimental<br> /api/v1/classifiers/6C76AF-nlc-43"</pre>

Path variables

classifier_id
string required

Classifier ID to query

Responses

200 OK
404 The classifier does not exist or is not available to the user
Personality-insights
Sends up to 20MB of content for analysis
POST /v2/profile

Currently only English (en) is supported for both input and output. A JSON response conforms to the Profile model. When an error status code is returned, a JSON response is returned with more details about the error.

Request parameters

headers
string optional

If true, column labels are sent with a CSV response. Specify "text/csv" for the Accept header.

Default:
false

Request headers

Content-Type
string required

The content type of the request

Enumeration:
application/json
text/html
text/plain
Default:
text/plain
Accept
string required

The desired content type of the response. CSV output includes a fixed number of columns

Enumeration:
application/json
text/csv
Default:
application/json
Accept-Language
string optional

The desired language of the response. Currently only "en" is supported.

Enumeration:
en
Default:
en
Content-Language
string optional

The content language of the request. Applies when the Content-Type header is set to "text/plain" or "text/html". Currently only "en" is supported.

Enumeration:
en
Default:
en

Request body

Responses

200 OK
Body
400 The request JSON is not properly formatted, or less than 100 words are provided.
Body
500 Server error
Body
DEPRECATED: Visualize a JSON profile
POST /v2/visualize

The POST /v2/visualize operation is deprecated, it will be removed in a future release. The visualization capability now is included in the sample code to facilitate its use with caching and content distribution networks.<br><br>Accepts a User Modeling portrait that is generated from the response of the POST /profile operation. The response is a visualization of the portrait that is generated via JavaScript, HTML and SVG with the D3.js library.

Request parameters

w
integer optional

Width of the visualization, in pixels.

Default:
800
h
integer optional

Height of the visualization, in pixels.

Default:
800
id
string optional

The id of the result div element containing the visualization.

Default:
chartDiv
d3
string optional

If true, return the D3.js library inline. If false, do not. Specify "true" for the first widget you place in your page and "false" for the rest to avoid having multiple copies of D3.

Default:
true
imgurl
string optional

The url to an image to place at the center of the visualization. Typically this would be a picture of the person who created the text that was analyzed. For example, a URL to the user's portrait from Twitter.

useorignames
string optional

The visualization uses some names that are more meaningful to a lay person. Set to true to see the original names for these characteristics.

Default:
false

Request body

Responses

200 OK
Body
string
400 Bad request
Body
500 Server error
Body
Pings the service to verify that it is available
GET /v1/ping

Responses

200 Service is available
Returns the list of supported Watson domains
GET /v1/services

Responses

200 OK
Sends a question to an instance of Watson
POST /v1/question/{dataset}

Accepts a Question and Answer REST API request and routes it to the Watson instance identified by the "dataset" path parameter. The response includes answers and supporting evidence.

Path variables

dataset
string required

Identifies the data set or domain that Watson is trained for

Enumeration:
travel
healthcare

Request headers

X-SyncTimeout
integer optional

Specifies how long the Watson pipeline waits for a response

Request body

WatsonQuestion

Responses

200 Message processed successfully
400 Question validation failed. See the message text for more information.
500 Server error. See the message text for more information
Submit feedback on the Question Answer Gateway service
PUT /v1/feedback

The feedback API allows you to provide information on how well the service performed. The feedback is used to further improve the service and future results.

Request body

Responses

201 Accepted
400 Bad request. Most likely the result of a missing required parameter.
Relationship-extraction
Sends text to the server 2
POST /v1/sire/0

You can extract useful information from text by using the IBM Watson Relationship Extractor service.

Request parameters

sid
string required

Language identifier. "es" refers to Spanish, and "en" refers to English.

Enumeration:
ie-es-news
ie-en-news
txt
string required

The text that you want to process. Must be encoded as UTF-8.

rt
string optional

Return type. The content type to accept.

Enumeration:
json
xml
Default:
xml

Responses

200 OK
Retrieves the models available for the service
GET /v1/models

Responses

200 OK
Body
406 Not acceptable. Unsupported MIME type.
Body
Retrieves information about the model
GET /v1/models/{modelId}

Path variables

modelId
string required

The desired model

Responses

200 OK
Body
404 Model not found
Body
406 Not acceptable. Unsupported MIME type.
Body
Creates a session using the default model
POST /v1/sessions

The default model is WatsonModel (English). Create a session to lock an engine to the session. You can use the session for multiple recognition requests, so that each request is processed with the same speech-to-text engine. Use the cookie that is returned from this operation in the Set-Cookie header for each request that uses this session. The session expires after 15 minutes of inactivity.

Responses

201 Created
Body
406 Not acceptable. Unsupported MIME type.
Body
Deletes the specified session
DELETE /v1/sessions/{sessionId}

Path variables

sessionId
string required

Responses

204 OK, no content
400 Bad request. Cookie must be set.
Body
404 SessionId not found
Body
406 Not acceptable. Unsupported MIME type.
Body
Result observer for upcoming or ongoing recognition task within the session
GET /v1/sessions/{sessionId}/observeResult

Start the request before the POST to recognize finishes. If the POST request is finished, the response for this request waits for the next recognition. You can submit multiple requests that point to the same recognition task and specify interim results.

Path variables

sessionId
string required

Session used in the recognition

Request parameters

interim_results
string optional

If true, interim results are returned as a stream of JSON objects. Each object represents a single SpeechRecognitionEvent. If false, the response is a single SpeechRecognitionEvent with all final results.

Default:
false

Request headers

X-logging
string optional

Specify 0 to prevent the server from saving the audio and transcription. Setting applies only to this request.

Enumeration:
1
0
Default:
1

Responses

404 SessionId not found
Body
406 Not acceptable. Unsupported MIME type.
Body
500 Internal server error. The session ID is destroyed after this error. Future request using this sessi

Internal server error. The session ID is destroyed after this error. Future request using this session will return HTTP 404.

Body
Checks whether a session is ready to accept a new recognition task
GET /v1/sessions/{sessionId}/recognize

Concurrent recognition tasks during the same session are not allowed. This method offers a way to check whether the session can accept another recognition task. The returned state must be 'initialized' to send the POST recognize operation.

Path variables

sessionId
string required

Session used in the recognition

Responses

200 OK
404 SessionId not found
Body
406 Not acceptable. Unsupported MIME type.
Body
Sends audio for speech recognition within a session
POST /v1/sessions/{sessionId}/recognize

Returns only the final results. To see interim results, call GET {sessionId}/observeResult?interim_results=true before this POST finishes. Endianness of the audio is autodetected. Audio longer than 5 minutes has to be sent in streaming mode (see Transfer-encoding header)

Path variables

sessionId
string required

Session used in the recognition

Request parameters

continuous
string optional

If true, multiple final results representing multiple consecutive phrases separated by pauses can be returned. Otherwise, the recognition ends after first 'End of speech' is detected.

Default:
false

Request headers

Content-Type
string required

Media type of the audio

Enumeration:
audio/flac
audio/l16
Transfer-encoding
string optional

Set this header to chunked to send the audio in streaming mode. Streaming is required for audio longer than 5 minutes

Enumeration:
chunked
X-logging
string optional

Specify 0 to prevent the server from saving the audio and transcription. Setting applies only to this request.

Enumeration:
1
0
Default:
1

Request body

Responses

200 OK.
400 Bad request. Session is in wrong state or missing some parameters.
Body
404 SessionId not found
Body
406 Not acceptable. Unsupported MIME type.
Body
500 Internal server error. The session will be destroyed after this error and next requests on this sess

Internal server error. The session will be destroyed after this error and next requests on this session would return 404.

Body
503 Session is already processing a request. Concurrent requests are not allowed on the same session. Se

Session is already processing a request. Concurrent requests are not allowed on the same session. Session remains alive after this error.

Body
Sends audio as multipart for speech recognition within a session
POST /v1/sessions/{sessionId}/recognize

Returns only the final results. To see interim results, call GET {sessionId}/observeResult?interim_results=true before this POST finishes. Audio longer than 5 minutes has to be sent in streaming mode (see Transfer-encoding header). The first part must be a JSON, the following parts must be audio files, e.g. {"part_content_type":"audio/flac", "num_data_parts":1, "continuous":true}, where 1 flac file would follow in the second part

Path variables

sessionId
string required

Session used in the recognition

Request parameters

continuous
string optional

If true, multiple final results representing multiple consecutive phrases separated by pauses can be returned. Otherwise, the recognition ends after first 'End of speech' is detected

Default:
false

Request headers

Content-Type
string required

Content-Type of the payload

Enumeration:
multipart/form-data
Transfer-encoding
string optional

Set this header to chunked to send the audio in streaming mode. Streaming is required for audio longer than 5 minutes

Enumeration:
chunked
X-logging
string optional

Specify 0 to prevent the server from saving the audio and transcription. Setting applies only to this request.

Enumeration:
1
0
Default:
1

Request body

application/x-www-form-urlencoded
Object
multipart
unknown

Metadata and audio files

Responses

400 Bad request. Session is in wrong state or missing some parameters
Body
404 SessionId not found
Body
406 Not acceptable. Unsupported MIME type.
Body
500 Internal server error. The session will be destroyed after this error and next requests on this sess

Internal server error. The session will be destroyed after this error and next requests on this session would return 404

Body
503 Session is already processing a request. Concurrent requests are not allowed on the same session. Se

Session is already processing a request. Concurrent requests are not allowed on the same session. Session remains alive after this error

Body
Sends audio for speech recognition that uses the default model
POST /v1/recognize

The default model is WatsonModel (English). Returns only the final results. Use sessions to enable interim results. Endianness of the audio is autodetected. Audio longer than 5 minutes has to be sent in streaming mode (see Transfer-encoding header)

Request parameters

continuous
string optional

If true, multiple final results that represent multiple consecutive phrases separated by pauses can be returned. Otherwise, the recognition ends after first 'End of speech' is detected.

Default:
false

Request headers

Content-Type
string required

Media type of the audio. Both audio/flac and audio/l16 MIME types are supported. If you use the audio/l16 MIME type, specify the rate and channels. For example, "audio/l16; rate=48000; channels=2". Ensure that the rate matches the rate at which the audio is captured.

Enumeration:
audio/flac
audio/l16
Transfer-encoding
string optional

Set this header to chunked to send the audio in streaming mode. Streaming is required for audio longer than 5 minutes

Enumeration:
chunked
X-logging
string optional

Specify 0 to prevent the server from saving the audio and transcription. Setting applies only to this request.

Enumeration:
1
0
Default:
1

Request body

Responses

406 Not acceptable. Unsupported MIME type.
Body
500 Internal server error
Body
Sends audio as multipart for speech recognition that uses the default model
POST /v1/recognize

Returns only the final results. Use sessions to enable interim results. Audio longer than 5 minutes has to be sent in streaming mode (see Transfer-encoding header). The default model is WatsonModel (English). The first part must be a JSON, the following parts must be audio files, e.g. {"part_content_type":"audio/flac", "num_data_parts":1, "continuous":true}, where 1 flac file would follow in the second part

Request parameters

continuous
string optional

If true, multiple final results representing multiple consecutive phrases separated by pauses can be returned. Otherwise, the recognition ends after first 'End of speech' is detected

Default:
false

Request headers

Content-Type
string required

Content-Type of the payload

Enumeration:
multipart/form-data
Transfer-encoding
string optional

Set this header to chunked to send the audio in streaming mode. Streaming is required for audio longer than 5 minutes

Enumeration:
chunked
X-logging
string optional

Specify 0 to prevent the server from saving the audio and transcription. Setting applies only to this request.

Enumeration:
1
0
Default:
1

Request body

application/x-www-form-urlencoded
Object
multipart
unknown

Metadata and audio files

Responses

406 Not acceptable. Unsupported MIME type.
Body
500 Internal server error
Body
Streaming speech synthesis of the text in a query parameter
GET /v1/synthesize

Identical to the POST method but passes shorter text in a query parameter. The text size is limited by the maximum length of the HTTP request line and headers, or about 6KB.

Request parameters

accept
string optional

Requested MIME type. You can use this query parameter instead of a header parameter.

Enumeration:
audio/ogg; codecs=opus
audio/wav
voice
string required

Selects a voice to use for synthesis. Retrieve available voices with GET /v1/voices method.

Default:
VoiceEnUsMichael
text
string required

Text to synthesize. Text size limited to about 6KB.

Request headers

X-logging
string optional

Specify 0 to prevent the server from saving the input text. Setting applies only to this request.

Enumeration:
1
0
Default:
1

Responses

200 OK
Body
Array of string
304 Not modified
400 Bad request
Body
406 Unsupported MIME type
Body
500 Internal server error
Body
Streaming speech synthesis of the text in the body parameter
POST /v1/synthesize

Identical to the GET method but passes longer texts in the body. Text size is limited to 4MB.

Request parameters

accept
string optional

Requested MIME type. You can use this query parameter instead of a header parameter.

Enumeration:
audio/ogg; codecs=opus
audio/wav
voice
string required

Selects a voice to use for synthesis. Retrieve available voices with GET /v1/voices method.

Default:
VoiceEnUsMichael

Request headers

X-logging
string optional

Specify 0 to prevent the server from saving the input text. Setting applies only to this request.

Enumeration:
1
0
Default:
1

Request body

Responses

200 OK
Body
Array of string
304 Not modified
400 Bad request
Body
406 Unsupported MIME type
Body
500 Internal server error
Body
Retrieves the voices available for speech synthesis
GET /v1/voices

Responses

200 OK
Body
304 Not modified
406 Unsupported MIME type
Body
Retrieves a dilemma based on the submitted problem decision
POST /v1/dilemmas/

Returns a dilemma that contains the problem and a resolution. The problem contains a set of options and objectives. The resolution contains a set of optimal options, their analytical characteristics, and representation on a 2D space.

Request parameters

generate_visualization
string optional

Determines whether to calculate visualization

Default:
true

Request body

Responses

200 Dilemma created
Body
304 Same problem was received
400 Malformed problem was received
413 Problem received is too large
500 Server encountered internal error
Retrieves a list of labels and label groups
GET /v1/tag/labels

You can query a label group to return other label groups and relevant labels.

Request parameters

labels_to_check
unknown optional

Label groups and labels object. Send the JSON data as a string. Omit the parameter to return all items. Specify a label group to return a subset of label groups and corresponding labels. Existing labels that you specify are returned.

Responses

200 Success
400 Invalid JSON
500 Server error
Uploads an image to analyze against the specified labels
POST /v1/tag/recognize

Classifies the images you upload against the label groups and labels. For each image, the response includes a score for a label if the score meets the minimum threshold of 0.5. If no score meets the threshold for an image, no labels are returned.<br>The operation consumes both parameters as multipart/form-data

Request body

application/x-www-form-urlencoded
Object
labels_to_check
unknown

The labels to check. Send the JSON data as a string. Use the response from the GET /labels method to narrow the list of labels to check. Omit this parameter to use all labels.

img_File
unknown

The image file to analyze. Ensure that the image includes a file name extension (for example, .jpg or .png). You can also upload a compressed (.zip) file of images.

Responses

200 Success
Body
400 Invalid labels
500 Server error, such as a lack of storage.
Data Reference
Annotations
Object
annotations
Array of Annotation
Annotation
Object
concept
string

Link to external resource for this concept (for example, a wikipedia page)

coords
Array of integer

Coordinates of the extracted terms in the original document as specified in the 'sources' property of the Searchable object. Each pair of integers corresponds to the beginning and ending of each word in the term.

weight
number

Decimal percentage of the confidence in the annotation. Higher values represent higher confidences.

authorization
Object
uid
string

User ID

permission
string

Combination of 'Read', 'Write' and 'Admin'

Concept
Object
id
string

Unique identfier for this concept

label
string

Human-readable title of the concept

abstract
string
link
string

Link to external resource for this concept (for example, a wikipedia page)

ontology
Array of string

List of potential categories for a concept

thumbnail
string

URL of a small image of the concept

conceptsRelated
Object
concepts
Array of conceptRelated
conceptRelated
Object
score
number

The conceptual relationship score in the range 0.5 - 1.0. The higher the score, the more evidence of a relationship.

uri
string
Corpora
Object
corpus
Array of Corpus
Corpus
Object
id
string

Must match the URI corpus ID in requests

access

Visibility of the corpus

users
Array of authorization
createCorpus
Object
access
string

'public' or 'private'

users
Array of authorization
Document
Object
id
string
label
string
parts
Array of Part

List of document descriptor objects

lastmodified
string

As defined in RFC 3339. Set by server if not sent by client

annotations
Array of Annotation

Array of Annotation. Dictionary mapping of a key from 'sources' field to an array of extracted annotations.

state

The state of the searchable

documentIds
Object
docids
Array of string
documentRequest
Object
id
string
label
string
parts
Array of Part

List of document descriptor objects

lastmodified
string

As defined in RFC 3339. Set by server if not sent by client

documentUpdate
Object
id
string
label
string
lastmodified
string

As defined in RFC 3339. Set by server if not sent by client

Part
Object
name
string

Document name

uri
string

document URI. The only supported protocol is that of the doc service. Specify URIs without a protocol and with a relative path. For example, "/api//v1/doc/user/collection/document.txt"

type
string

Document MIME type

data
string

Immediate document data (takes precedence over URI)

labelResult
Object
id
string

ID of Concept or Searchable

label
string

Label of Concept or Searchable

type
string

'Concept' to identify concept. Also, domain name for Searchable of a domain

result
unknown

Concept URI or Searchable object representation

score
Object
score
number

The conceptual relationship score in the range 0.5 - 1.0. The higher the score, the more evidence of a relationship.

semanticResult
Object
concepts
Array of Corpus
results
Array of Document

Variation of the Document model. Each Node object also includes a ‘tags’ field that contains a subset of the annotations in the original annotations field. In addition, a score field is added to reflect the relevance of the tag to the query.

status
string
Enumeration:
FRONT
EXCLUDED
INCOMPLETE
ping
Object
message
string

Ping response message.

Jobid
Object
jobid
string

Unique identifier for the submitted job in the form "<id_number>#<serialnumber>"

Status
Object
state

Current status of the job: Done. Awaiting start. Going, Retrieved, and Failed

Seeds
Object
seeds
Array of string

Comma-separated list of seed terms

rtn_seeds
Object
return_seeds
rtn_seed
Object
prevalance
double

Ranked score for result

result
string

A new term

Types: rtn_seeds
ringscore
Object
overall
integer
prevalence
integer
volume
integer
duration
integer
datasets
Object
id
integer
name
text
ErrorResponsePayload
Object
error
string

Error description

code
integer

HTTP status code

TrainingData
Object
text
string

Representative phrase. For example, questions that users might ask

classes
Array of string

Identifier (or "key") of the specific action that the application takes for the representative phrase.

ListClassifiersPayload
Object
classifiers

The classifiers available to the user

StatusPayload
Object
classifier_id
string

Unique identifier for this classifier

url
string

Link to the classifer

status

The state of the classifier

status_description
string

Additional detail about the status

NLClassifierOutputPayload
Object
classifier_id
string

Unique identifier for this classifier

url
string

Link to the classifer

text
string

The submitted phrase

top_class
string

The class with the highest confidence

classes

An array of up to ten class-confidence pairs sorted in descending order of confidence

NLClassifierInputPayload
Object
text
string

The submitted phrase

NLClassifiedClass
Object
class_name
string

Class label

confidence
number

A decimal percentage that represents the confidence that Watson has in this class. Higher values represent higher confidences.

TrainingInputPayload
Object
language

IETF primary language subtag for the classifier

training_data
Array of TrainingData

The set of questions and their "keys" used to adapt a system to a domain (the ground truth)

ClassifierInfoPayload
Object
classifier_id
string

Unique identifier for this classifier

url
string

Link to the classifer

Profile
Object
id
string

The unique identifier for which these characteristics were computed, from the "userid" field of the input ContentItems.

source
string

The source for which these characteristics were computed, from the "sourceid" field of the input ContentItems.

word_count
integer

The number of words found in the input.

word_count_message
string

A message indicating the number of words found and where that value falls in the range of required/suggested number of words.

TraitTreeNode
Object
id
string

The id of the characteristic, globally unique.

name
string

The user-displayable name of the characteristic.

percentage
double

The normalized value of the characteristic, from 0-1. For example, if the percentage for Openness is 0.25, you scored in the 25th percentile. You are more open than 24% of the population and less open than 74% of the population.

children
Array of TraitTreeNode
sampling_error
double

Indicates the sampling error of the percentage, based on the number of words in the input. The number defines a 95% confidence interval around the percentage. For example, the sampling error is 4% and percentage is 61%. It is 95% likely that the actual percentage value is between 57% and 65% if more words are given.

Types: Profile
ContentListContainer
Object
contentItems
Array of ContentItem
ContentItem
Object
id
string

Unique identifier for this content item.

userid
string

Unique identifier for the author of this content.

sourceid
string

Identifier for the source of this content. For example, blog123, twitter.

created
int

Timestamp that identifies when this content was created. In milliseconds since midnight 1/1/1970 UTC.

updated
int

Timestamp that identifies when this content was last updated. In milliseconds since midnight 1/1/1970 UTC.

contenttype
string

MIME type of the content, for example, "text/plain, text/html". The tags are stripped from HTML content before it is analyzed. Other MIME types are processed as is.

charset
string

Character set of the text, for example, "UTF-8"

language
string

Language identifier (two-letter ISO 639-1 identifier). Currently only English content (en) is supported.

content
string

Content to be analyzed. Up to 20MB of content is supported.

parentid
string

Unique id of the parent content item. Used to identify hierarchical relationships between posts/replies, messages/replies, etc.

reply
string

Indicates whether this content item is a reply to another content item.

forward
string

Indicates whether this content item is a forwarded/copied version of another content item.

services
Object
services
Array of Service
service
Object
overall
integer
dataset
string

Unique identifier of the domain

name
string

Friendly name of the Watson domain

description
string

Brief description of the domain

watsonQuestion
Object

Question information

QuestionInformation
Object
questionText
string

The text of the question to be answered

items
integer

An integer in the range 1 – 10 that represents the number of possible answers to be returned. If you do not specify the number of items, the request assumes five answers.

evidenceRequest

Specifies that you want Watson to return supporting evidence for each answer in the answers/answer/evidence section of the answer response.

answerAssertion
string

Specify an answer to receive the supporting evidence passages for that answer. Without this element, Watson searches for answers from the questionText. When you assert an answer, Watson uses that answer instead to search for supporting evidence passages.

category
string

The category of the question in terms of a constraint on the possible answers.

context
string

A natural language string that is composed of words that provide extra information for Watson to consider when it determines answers.

formattedAnswer
string

Requests Watson to return the formatted answer.

passthru
string

Specifies a string that you include with the question. The passthru data is not submitted with the pipeline but does pass through to the answer.

synonyms
string

The container for the set of synonyms. You can provide feedback to Watson by resubmitting a question and including an updated list of synonyms.

lat
string

The lexical answer type (LAT) of the question. The LAT is a word or noun phrase that appears in the question, or is implied by it.

filters

Supports the use of metadata to restrict answers to specific documents

EvidenceRequest
Object
items
integer

An integer in the range 1 – 10 that defines the number of supporting passages to return for each answer. Fewer passages might be returned for answers that do not have good passage support. The default value is 3 passages.

profile

Whether to return evidence profiles for each possible answer.

Filters
Object
filters
Array of Filter
Filter
Object
filterType

The type of the filter

filterName
string

The name of the indexed metadata field. Use "indexedKey." for dateRangeFilter use "indexed" for other filterTypes.

values
string

The metadata value of the indexed field name.

Types: Filters
WatsonAnswer
Object
id
integer

An integer that is assigned by the service to identify this question and its answers.

answers
category
string

The category of the question that was submitted with the question. When no category was submitted with the question, an empty category element is returned in the response.

errorNotifications
evidenceList
Array of Evidence
focusList
string

The container for a list of focus elements that are determined by the pipeline for the final answer.

latList
string

The container for lexical answer types (LATs) that the pipeline determined for the final answer. The /question/lat is submitted in the POST when the question what submitted. The/question/latlist contains the LATs that were determined by the pipeline when it processed the answer.

pipelineid
string

The internal ID that is assigned for the final answer CAS. This element contains the internal CAS ID that is assigned after the question is answered. You can use this ID to identify the question with the internal data structures that Watson uses.

qclasslist
string

The container for a list of question classes that are determined by the pipeline for the final answer.

status

The response status of the request.

supplemental
string

Contains more information about the answers for a customization of the IBM Watson processing pipeline. In a Watson system that is not customized, this element is not returned.

synonymList
Array of SynonymList
Answers
Object
answers
Array of Answer
Types: WatsonAnswer
Answer
Object
id
integer

An integer that uniquely identifies an answer in the context of the question.

text
string

A string that contains an answer to the question in the form of text.

confidence
string

A decimal percentage that represents the confidence that Watson has in this answer. Higher values represent higher confidences.

evidence
Array of Passage
evidenceProfile
Array of EvidenceProfile
formattedText
string

The HTML-formatted version of the answer text that is returned when you set formattedAnswer to true when you submit a question. The formatted answer includes content from the <body> tag of the answer.

Types: Answers
Passage
Object
copyright
string

The copyright holder for the document that contains the evidence passage. If there is no copyright information, the element is empty.

document
string

The URL to a document passage for an answer.

termsOfUse
string

A URL that points to the license that describes the terms of use of the document.

text
string

The passage text, essentially one or more sentences.

title
string

The passage title, a string of text.

Types: Answer
EvidenceProfile
Object
featureGroup
Array of FeatureGroup
Types: Answer
FeatureGroup
Object
name
string
value
string
ErrorNotification
Object
error
string

The container for message information about a recoverable error.

text
string

A string that describes the error.

Types: WatsonAnswer
SynonymList
Object
term
string

The original term value with its part of speech, such as noun, adj, adv, and verb.

synSet
string

The set that represents the source (such as wordnet or wikiredirect) of the synonyms.

synonym
string

A synonym that belongs to a synSet. The synonym is represented by its value and whether it is used. All synonyms are returned in lowercase text.

Types: WatsonAnswer
Evidence
Object
copyright
string

The copyright holder for the document that contains the evidence passage. If there is no copyright information, the element is empty.

metadataMap
string

The container for the metadata from the document that contains the evidence passage. This element is returned only when the IBM Watson processing pipeline is configured to support metadata.

termsOfUse
string

A URL that points to the license that describes the terms of use of the document that contains the evidence passage. If there is no information about terms of use, the element is empty.

text
string

The evidence passage text.

title
string

The title of the document for the evidence passage.

document
string

The URL to a document passage for an answer.

value
string

A decimal percentage that represents the confidence that Watson has in this evidence. Higher values represent higher confidences.

Types: WatsonAnswer
FeedbackInput
Object
questionId
string

The question ID, obtained from the QA API result.

questionText
string

The question text obtained from the QA API result.

answerId
string

The answer ID to provide feedback on. The Answer ID is obtained from the QA API result.

answerText
string

The answer text to provide feedback on. The answer text is obtained from the QA API result.

userName
string

The name of the user submitting the feedback.

mode

The Watson mode used to obtain the QA API result.

confidence
string

The confidence of the answer obtained from the QA API result.

shown
string

If the answer was shown to the user.

evidenceViewed
string

If the evidence was viewed by the user.

feedback

String representation of the feedback [-1 = answers was irrelevant, 0=neutral feedback, 1=answer was relevant, 9=answer was partially relevant]

comment
string

User comment.

SpeechRecognitionEvent
Object
result_index
integer

Index of the first updated result in the array of all results. The returned array contains only the items from this index.

results

Updated results. Each item corresponds to a single utterance ended by 'end of speech' detected by the service.

SpeechRecognitionResult
Object
final
string

If true, result for this utterance will not be updated further

alternatives

List of alternative transcripts received from the service

SpeechRecognitionAlternative
Object
transcript
string

Transcript of the utterance

ModelSet
Object
models
Array of Model
Model
Object
name
string

Name of the model to use as identifier in all requests

rate
integer

Sampling rate used by model (minimal rate to use)

sessions
string

URI for sessions on this model

url
string

URI of the model.

Session
Object
session_id
string

ID of the session created

new_session_uri
string

URI for the session created

recognize
string

URI for recognize

observe_result
string

URI for results observers

Multipart
Object
metadata

This must be the first part and contain JSON-formatted text, with the metadata describing the following parts, which contain the data. The Content-Type of the parts will be ignored

files
Array of unknown

Audio parts as described by metadata. Endianness of the audio is autodetected.

Metadata
Object
part_content_type
string

The MIME type of the data in the following parts. All data parts must have the same MIME type

data_parts_count
integer

The number of the data parts (should be one less than total number of parts in the request). When specified, server-side end-of-stream detection can be applied to the last (and possibly the only) data part. If omitted, the number of parts is determined from the request itself.

continuous
string

If true, multiple final results that represent multiple consecutive phrases separated by pauses can be returned. If set to false (default), the recognition ends after first 'End of speech' is detected.

Types: Multipart
RecognizeStatus
Object
session

Description of state and possible actions on the current session

SessionStatus
Object
state
string

State of the session. It must be 'initialized' to perform new recognition tasks on the session

model
string

URI where information about the model that is used in the session can be found

recognize
string

URI for recognize

observe_result
string

URI for results observers

VoiceSet
Object
voices
Array of Voice
Voice
Object
name
string

The name of the voice. Use this as voice identifier in all requests.

language
string

The language and region of the voice (for example, 'en-US').

gender
string

The gender of the voice: 'male' or 'female'.

url
string

URI of the voice.

Types: VoiceSet
Text
Object
text
string

Text to synthesize

Resolution
Object
solutions

Analytical data per option

map

2D position of option on map polygon

Types: Dilemma
MetaMap
Object
config

Configuration of algorithm parameters used for this map output

Metrics associated with map quality

anchors
Array of Anchor

Anchor point on map

nodes
java.util.Collection<com.ibm.modmt.impl.model.sommos.SommosNode>

Cell on map. Structure is {"coordinates": {"x": 0, "y": 0}, "solution_refs": ["key1", "key3"]}. Coordinates describe the position on the map of options identified by keys in solution_refs.

comments
string

Comments related to map, currently not in use

Types: Resolution
ObjectiveDefinition
Object
goal

Direction of the objective. The direction can be minimized (price of a car) or maximized (safety of a car)

is_objective
string

Specifies whether this column is acting as objective in the given problem

insignificant_loss
number

A value that is considered an insignificant loss for this objective

significant_gain
number

A value that is considered a significant gain for this objective

significant_loss
number

A value that is considered a significant loss for this objective

key
string

Unique ID

type

Currently only numeric types are supported. Might extend with additional types, such as categorial and date

full_name
string

Descriptive name

range

Range of valid values

enum_vals
Array of string

Reserved

format
string

A regex used to apply formatting on the measure values

description
string

Long description

Types: Problem
SolutionPerspective
Object
status

Option status

shadows
Array of string

list of references to solutions which are shadowed by this solution

solution_ref
string

Option key as reference

shadow_me
Array of string

list of references to solutions which shadow this solution

status_cause

detailed description for status value

Types: Resolution
ValueRange
Object
low
number

Low end

high
number

High end

Anchor
Object
name
string

Anchor point name

Anchor point position

Types: MetaMap
StatusCause
Object
message
string

Text description for status value

tokens
Array of string

Problematic fields in the option that cause this error

error_code

Error code

MapQualityMeasurements
Object
kappa
number

Kappa error

final_kappa
number

Kappa error for final map

Types: MetaMap
MapDrivers
Object
r_fin
number

Radius finish

r_init
number

Radius initialization

r_anchor_init
number

Radius anchor

training_length
integer

Number of iterations

max_map_size
integer

Maximum size of map

alpha_init
number

Alpha initatlization value

training_anchors
number

Anchor training ratio

data_multiplier
integer
Types: MapConfig
Problem
Object
columns

List of possible objectives. Typically, the columns in a table representation of your data

subject
string

Name of the decision problem. Typically, the name of the column representing the options names in a table representation of your data

options
Array of Option

A list of options. Typically, the rows in a table representation of your data

Dilemma
Object
problem

The decision problem

resolution

The decision problem resolution

MapNodeCoordinates
Object
x
number

X coordinate

y
number

Y coordinate

Types: Anchor
Option
Object
key
string

Unique ID

name
string

Name

values
Map[string,double]

Map of objective key to objective value with the structure, "values": { "key1": value1, "key2": value2 }

description_html
string

Description in HTML format

app_data
Map[string,string]

Reserved

Types: Problem
MapParameters
Object
rInit
number

Radius initialization

rFinish
number

Radius finish

rAnchor
number

Radius anchor

seed
integer

Random seed used in the algorithm

map_size
integer

Estimated number of neurons in map

training_period
integer

Algorithm training iterations

anchor_epoch
integer

Rate of anchor training

alpha_init
number

Alpha initialization value

Types: MapConfig
MapConfig
Object

Raw algorithm parameters used for map generation

drivers

Derived algorithm parameters used for map generation

Types: MetaMap
images
Object
images
Array of image
image
Object
image_id
integer

Integer assigned to each uploaded image

image_name
string

File name of the image

labels
Array of labels
Types: images
labels
Object
label_name
string

Name of the label

label_score
number

Number that represents how strongly the label is recognized in the image

Types: image
labels_payload
Object
label_groups
Array of string
labels
Array of string
access
string
Enumeration:
public
private
Types: Corpus
stage
string
Enumeration:
annotate
compute
ready
statusEnum
string
Enumeration:
done
state
string
Enumeration:
D
A
G
R
F
Types: Status
language
string
Enumeration:
en
profile
string
Enumeration:
yes
no
filterType
string
Enumeration:
dataRangeFilter
metadataFilter
prefixFilter
queryFilter
Types: Filter
mode
string
Enumeration:
prod
m_prod
test
m_test
feedback
string
Enumeration:
-1
0
1
9
goal
string
Enumeration:
MIN
MAX
type
string
Enumeration:
NUMERIC
TEXT
error_code
string
Enumeration:
MISSING_OBJECTIVE_VALUE
MISSING_DESIGN_VALUE
RANGE_MISMATCH
Types: StatusCause