REST methods for IBM Concept Insights

Authenticated requests return public collections and collections with read permission.

Example Request

curl -u user:password ‘https://gateway.watsonplatform.net/concept-insights-beta/api/v1/corpus/’

[
    {
        “access”: “private”,
        “id”: “/user/test”,
        “users”: [
            {
                “permission”: “ReadWriteAdmin”,
                “uid”: “user”
            }
        ]
    }
]

Requires ‘Admin’ permission to the corpus. The operation also deletes all the documents contained in the corpus.

Example Request

curl -D - -X DELETE -u user:password 'https://gateway.watsonplatform.net/concept-insights-beta/api/v1/corpus/user/test’

HTTP/1.1 200 OK

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.

Example Request

curl -u user:password https://gateway.watsonplatform.net/concept-insights-beta/api/v1/corpus/user/test?limit=10

[“a”, “foo”, “testdoc”, “testdoc”]

Example Request

curl -D - -X PUT -u user:password -d '{"access":"private"}' 
        'https://gateway.watsonplatform.net/concept-insights-beta/api/v1/corpus/user/test'

HTTP/1.1 201 Created

Requires write access to the corpus.

Example Request

curl -D - -X DELETE -u user:password 'https://gateway.watsonplatform.net/concept-insights-beta/api/v1/corpus/user/test/mydoc’

HTTP/1.1 200 OK

Authenticated requests return documents from a corpus if it has public access and from a corpus with read permission.

Example Request

curl -D - -u user:password 'https://gateway.watsonplatform.net/concept-insights-beta/api/v1/corpus/user/test/ibmnews’

HTTP/1.1 200 OK
Content-Length: 13
Content-Type: application/json
Date: Thu, 18 Sep 2014 14:23:08 GMT

{
    “id”: “ibmnews”,
    “label”: “IBM News”,
    “parts”: [
        {
            “name”: “excerpt”,
            “uri”: “”,
            “type”: “”,
            “data”: “IBM announced today a new cognitive system…”
        }
    ]
}

Requires write access to the corpus.

Example Request

curl -D - -X POST -u user:password -d ‘{“label”:“a new label”,“parts”:[{“data”:“International Business Machines 
        announced today a new cognitive system.”,“name”:“field”}]}’ 
        ‘https://gateway.watsonplatform.net/concept-insights-beta/api/v1/user/test/mydoc’

Requires write access to the corpus.

Example Request

curl -D - -X PUT -u user:password -d ‘{“label”:“IBM News”,“parts”:[{“name”:“excerpt”,“data”:“IBM announced today 
        a new cognitive system…”}]}’ 'https://gateway.watsonplatform.net/concept-insights-beta/api/v1/corpus
        /user/test/ibmnews’

HTTP/1.1 201 Created

Similar to the GET /v1/graph/{user}/{graphid}/{conceptid} method, but for multiple concepts.

Example Request

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

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.

Example Request

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

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.

Example Request

curl --get -u username:password --data-urlencode “func=related” --data-urlencode 
        ‘concepts=["/graph/wikipedia/en-20120601/Color_blindness"]’ --data-urlencode “level=0” 
        ‘https://gateway.watsonplatform.net/concept-insights-beta/api/v1/graph/wikipedia/en-20120601/’ 
        | python -m json.tool
[
    {
        “score”: 0.9773398,
        “uri”: “/v1/graph/wikipedia/en-20120601/Retina”
    },
    {
        “score”: 0.9358882,
        “uri”: “/v1/graph/wikipedia/en-20120601/Human_eye”
    },
    {
        “score”: 0.92706054,
        “uri”: “/v1/graph/wikipedia/en-20120601/Color”
    },
    {
        “score”: 0.9090508,
        “uri”: “/v1/graph/wikipedia/en-20120601/Ophthalmology”
    },
    {
        “score”: 0.886107,
        “uri”: “/v1/graph/wikipedia/en-20120601/Zygosity”
    }
]

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:

curl  -u username:password -d “My heart sank when I saw that Deep Blue won against Kasparov. Computer science 
        and humanity would never be the same after that.” ‘https://gateway.watsonplatform.net/concept-insights-beta
        /api/v1/graph/wikipedia/en-20120601?func=annotateText’ | python -m json.tool
[
    {
        “concept”: “/graph/wikipedia/en-20120601/Computer_science”,
        “coords”: [
            [
                62,
                70
            ],
            [
                71,
                78
            ]
        ],
        “weight”: 0.8426364
    },
    {
        “concept”: “/graph/wikipedia/en-20120601/Deep_Blue_vs_Kasparov”,
        “coords”: [
            [
                30,
                34
            ],
            [
                35,
                39
            ],
            [
                52,
                60
            ]
        ],
        “weight”: 0.7565227
    },
    {
        “concept”: “/graph/wikipedia/en-20120601/Humanity”,
        “coords”: [
            [
                83,
                91
            ]
        ],
        “weight”: 0.6133502
    }
]

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

Example Request

curl -u username:password -s ‘https://gateway.watsonplatform.net/concept-insights-beta/api/v1/graph
        /wikipedia/en-20120601/IBM’| python -mjson.tool
{
   “abstract”: “International Business Machines Corporation or IBM is an American multinational technology 
and consulting corporation headquartered in Armonk, New York, United States. IBM manufactures and sells 
computer hardware and software, and it offers infrastructure, hosting and consulting services in areas 
ranging from mainframe computers to nanotechnology.”,
   “id”: “IBM”,
   “label”: “IBM”,
   “link”: “http://en.wikipedia.org/wiki/IBM”,
   “ontology”: [
      “Company”,
      “Organisation”,
      “Agent”
   ],
   “thumbnail”: “http://upload.wikimedia.org/wikipedia/commons/thumb/5/51/IBM_logo.svg/200px-IBM_logo.svg.png”,
   “type”: “wiki_resource”
}

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.

Example Request

curl -u username:password ‘https://gateway.watsonplatform.net/concept-insights-beta/api/v1/searchable/public/ibmresearcher
        ?func=labelSearch&query=mark&prefix=true&concepts=true&limit=2’ | python -m json.tool

[
    {
        “id”: “zurich-mla”,
        “label”: “Lantz, Mark A.”,
        “result”:{
            “id”: “zurich-mla”,
            “label”: “Lantz, Mark A.”,
            “lastbuild”: “0001-01-01T00:00:00Z”,
            “lastmodified”: “2015-01-07T16:32:09Z”,
            “state”:{
                “stage”: “compute”,
                “status”: “locked”,
                “timestamp”: “2015-01-31T03:55:06.216Z”
            },
            “type”: “”,
            “user”: {
                “thumbnail”: “http://researcher.watson.ibm.com/researcher/photos/942.jpg”
            }
        },
        “type”: “/public/ibmresearcher”
    },
    {
        “id”: “us-mferriss”,
        “label”: “FERRISS, MARK A.”,
        “result”:{
            “id”: “us-mferriss”,
            “label”: “FERRISS, MARK A.”,
            “lastbuild”: “0001-01-01T00:00:00Z”,
            “lastmodified”: “2015-01-16T11:22:24-05:00”,
            “state”:{
                “stage”: “ready”,
                “status”: “done”,
                “timestamp”: “2015-01-30T08:54:40.34Z”
            },
            “type”: “”,
            “user”: {
                “thumbnail”: “http://researcher.watson.ibm.com/researcher/photos/1274.jpg”
            }
        },
        “type”: “/public/ibmresearcher”
    },
    {
        “id”: “Garbage_collection_(computer_science)”,
        “label”: “Mark and sweep”,
        “result”:{
            “abstract”: “In computer science, garbage collection (GC) is a form of automatic memory management. 
                The garbage collector, or just collector, attempts to reclaim garbage, or memory occupied by objects 
                that are no longer in use by the program. Garbage collection was invented by John McCarthy around 
                1959 to solve problems in Lisp.”,
            “id”: “Garbage_collection_(computer_science)”,
            “label”: “Garbage collection (computer science)”,
            “type”: “wiki_resource”,
            “link”: “http://en.wikipedia.org/wiki/Garbage_collection_(computer_science)”
        },
        “type”: “concept”
    },
    {
    “id”: “Markov_chain”,
    “label”: “Markhow chain”,
    “result”:{
        “abstract”: “A Markov chain, named after Andrey Markov, is a mathematical system that undergoes transitions 
                from one state to another, between a finite or countable number of possible states. It is a random 
                process characterized as memoryless: the next state depends only on the current state and not on 
                the sequence of events that preceded it. This specific kind of “memorylessness” is called the 
                Markov property. Markov chains have many applications as statistical models of real-world processes.”,
        “id”: “Markov_chain”,
        “label”: “Markov model”,
        “type”: “wiki_resource”,
        “link”: “http://en.wikipedia.org/wiki/Markov_chain”
        },
        “type”: “concept”
    }
]

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.

Example Requests

curl -u username:password  'https://gateway.watsonplatform.net/concept-insights-beta/api/v1/searchable/public/ibmresearcher
        ?func=semanticSearch&&ids=["/graph/wikipedia/en-20120601/Java_virtual_machine"]&limit=4’

curl -u username:password ''https://gateway.watsonplatform.net/concept-insights/beta/api/v1/searchable/user/corpus
        ?func=semanticSearch&ids=["/corpus/user/mydocs/foo"]&limit=4’

curl --get -u username:password --data-urlencode “limit=4” --data-urlencode “func=semanticSearch” 
        --data-urlencode ‘ids=["/corpus/public/ibmresearcher/us-bennetc"]’ 
        ‘https://gateway.watsonplatform.net/concept-insights-beta/api/v1/searchable/public/ibmresearcher’

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.

Example Request

curl ‘https://gateway.watsonplatform.net/concept-insights-beta/api/v1/searchable/user/corpus/documentid?func=getState’

{
    “stage”: “ready”,
    “status”: “done”,
    “timestamp”: “2014-03-31T20:04:57.74-04:00”
}

Example Request

curl -u username:password 'https://gateway.watsonplatform.net/concept-insights-beta/api/v1/searchable/public/ibmresearcher
        /us-bennetc?func=relScore&dest=\["/graph/wikipedia/en-20120601/Hash_functions"\]'

{
    "score":0.9582957029342651
}

Step 1. Upload the seed list.

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

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

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

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

Sends data to create and train a classifier, and returns information about the new classifier.
The status has the value of Training when the operation is successful, and might remain at this status for a while.

Example Request

curl -X POST -u user:password -H “Content-Type:application/json”  -d @train.json 
    “https://gateway.watsonplatform.net/natural-language-classifier-experimental/api/v1/classifiers”

Returns an empty array if no classifiers are available.

Example Request

curl -u user:password “https://gateway.watsonplatform.net/natural-language-classifier-experimental/api/v1/classifiers”

The status must be Available before you can use the classifier to classify calls. Use GET /classifiers/{classifier_id} to retrieve the status.

Example Request

curl -X POST -u user:password -H “Content-Type:application/json” -d “{“text”:“what is your phone number?”}” 
    “https://gateway.watsonplatform.net/natural-language-classifier-experimental/api/v1/classifiers/6C76AF-nlc-43/classify”

Example Request

curl -X DELETE -u user:password "https://gateway.watsonplatform.net/natural-language-classifier-experimental
    /api/v1/classifiers/6C76AF-nlc-43"

Example Request

curl -u user:password "https://gateway.watsonplatform.net/natural-language-classifier-experimental
    /api/v1/classifiers/6C76AF-nlc-43"

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.

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.

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.

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.

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.

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

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.

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.

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.

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)

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

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)

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

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.

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

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.

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

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.
The operation consumes both parameters as multipart/form-data