Annotator for Clinical Data (ACD) v1.0.0
Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.
Natural Language Processing (NLP) service featuring a set of medical domain annotators for use in detecting entities and medical concepts from unstructured data. Multiple annotators may be invoked from a single request.
The Annotator for Clinical Data service is a medical domain NLP service featuring a variety of annotators for detecting meta-data such as entities, concepts, concept values, negated spans, hypothetical spans, and a collection of annotators that detect, normalize, and code medical and social findings from unstructured clinical data. Multiple annotators can be employed to analyze unstructured data from a single request.
The APIs may be called directly via cURL, Postman or your favorite HTTP REST client, or through the ACD SDKs which are provided for Java and Python. See these docs for information on installing and using the SDKs.
Announcement: ACD SDK Version 2
In April 2023, version 2 of the ACD Java SDK and ACD Python SDK was released. Version 2 of the SDKs is a breaking change. Updates were made to the SDK package naming. Details about the new release (including steps for migrating from version 1) are available at the SDK GitHub repository:
It is recommended to use version 2 of the SDKs. Version 1 will be deprecated at a future date.
The code samples in this document describe version 2 of the SDK.
Versioning
Annotator for Clinical Data API requests require a version parameter that takes a date in the format version=YYYY-MM-DD. When we change the API in a backwards-incompatible way, we release a new version date.
The version is a required parameter with every API request. The ACD service uses the API version for the date you specify, or the most recent version before that date. Don't default to the current date. Instead, specify a date that matches a version that is compatible with your app, and don't change it until your app is ready for a later version.
When using cURL to invoke API requests to the ACD service, the version parameter will need to be explicitly included with every API request.
When using the ACD Java or Python SDK, the version parameter gets configured when you create your ACD client to communicate with the ACD service. This version parameter will then be implicitly included when invoking ACD API requests using your ACD client.
Refer to the code examples in this document for more details. In your application, replace {version} with your version parameter.
Authentication
Annotator for Clinical Data authentication scheme will be dependant on the deployment being utilized.
The API code examples in this document use Bearer Token Authentication.
Refer to the code examples in this document for more details. In your application, replace {token} with your ACD authentication token, and replace {url} with your.acd.url/services/clinical_data_annotator/api, where your.acd.url is the URL to access the ACD service.
Container Edition
Container Edition instances can be configured to utilize an OAuth proxy for secure external access. The OAuth proxy uses bearer tokens for authentication.
See the ACD Container Edition documentation for additional details:
Code samples
curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/v1/status/health_check?version={version}"
import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import com.merative.acd.v1.AnnotatorForClinicalData;
BearerTokenAuthenticator authenticator = new BearerTokenAuthenticator({token});
AnnotatorForClinicalData acd = new AnnotatorForClinicalData(
{version},
AnnotatorForClinicalData.DEFAULT_SERVICE_NAME,
authenticator);
acd.setServiceUrl({url});
from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator
import acd_sdk.annotator_for_clinical_data as acd
acd_service = acd.AnnotatorForClinicalDataV1(
authenticator=BearerTokenAuthenticator(bearer_token={token}),
version={version}
)
acd_service.set_service_url({url})
Profiles
Managing persisted profiles
List profiles
Code samples
curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/v1/profiles?version={version}"
/*
* Get list of available profiles example.
*/
import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import com.merative.acd.v1.AnnotatorForClinicalData;
import com.ibm.cloud.sdk.core.http.Response;
import com.merative.acd.v1.model.GetProfilesOptions;
import com.merative.acd.v1.model.AcdProfile;
BearerTokenAuthenticator authenticator = new BearerTokenAuthenticator({token});
AnnotatorForClinicalData acd = new AnnotatorForClinicalData(
{version},
AnnotatorForClinicalData.DEFAULT_SERVICE_NAME,
authenticator);
acd.setServiceUrl({url});
GetProfilesOptions options = new GetProfilesOptions.Builder().build();
Response<Map<String, AcdProfile>> resp = acd.getProfiles(options).execute();
Map<String, AcdProfile> profileMap = resp.getResult();
for (String id:profileMap.keySet())
System.out.println("Profile Id: " + id);
# Get list of available profiles example.
from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator
import acd_sdk.annotator_for_clinical_data as acd
acd_service = acd.AnnotatorForClinicalDataV1(
authenticator=BearerTokenAuthenticator(bearer_token={token}),
version={version}
)
acd_service.set_service_url({url})
try:
resp = acd_service.get_profiles()
rslt = resp.result
for id, profile in rslt.items():
print("Profile:", id)
except acd.ACDException as ex:
print ("Error Code:", ex.code, " Message:", ex.message, " Correlation Id:", ex.correlation_id, "Error Description ", ex.err_description)
GET /v1/profiles
List the available profiles
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| version | query | string | true | The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. |
Example responses
List profiles results
{
"acd.acd_clinical_insights_v1.0_profile": {
"publishedDate": "2020-03-04T13:30:15.318Z"
}
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | List profiles results | ListProfilesResults |
Create profile
Code samples
curl -X POST \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Authorization: Bearer {token}" \
-d @parameters.json \
"{url}/v1/profiles?version={version}"
/*
* Create a new profile example.
*/
import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import com.merative.acd.v1.AnnotatorForClinicalData;
import com.ibm.cloud.sdk.core.http.Response;
import com.merative.acd.v1.model.Annotator;
import com.merative.acd.v1.model.CreateProfileOptions;
import com.merative.acd.v1.model.CreateProfileOptions.Builder;
BearerTokenAuthenticator authenticator = new BearerTokenAuthenticator({token});
AnnotatorForClinicalData acd = new AnnotatorForClinicalData(
{version},
AnnotatorForClinicalData.DEFAULT_SERVICE_NAME,
authenticator);
acd.setServiceUrl({url});
Map<String, Set<String>> conceptDetectionParams
= new HashMap<String,Set<String>>(){{put("libraries",
new HashSet<String>() {{ add("umls.latest"); }} ); }};
Annotator conceptDetection = new Annotator.Builder()
.name(Annotator.Name.CONCEPT_DETECTION)
.parameters(conceptDetectionParams)
.build();
Builder bldr = new CreateProfileOptions.Builder()
bldr.id("my_profile");
bldr.name("My profile");
bldr.description("My profile desc");
bldr.addAnnotators(conceptDetection);
Response<Void> resp = acd.createProfile(bldr.build()).execute();
System.out.println("Response code: " + resp.getStatusCode());
# Create a new profile example.
from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator
import acd_sdk.annotator_for_clinical_data as acd
acd_service = acd.AnnotatorForClinicalDataV1(
authenticator=BearerTokenAuthenticator(bearer_token={token}),
version={version}
)
acd_service.set_service_url({url})
try:
prof_anno = acd.Annotator(
name="concept_detection",
parameters = {"libraries": ["umls.latest"]})
prof_anno_arr = [ prof_anno ]
resp = acd_service.create_profile (
new_id="my_profile",
new_name="my profile",
new_description="my profile description",
new_annotators=prof_anno_arr)
print("Response Code:",resp.status_code)
except acd.ACDException as ex:
print ("Error Code:", ex.code, " Message:", ex.message, " Correlation Id:", ex.correlation_id, "Error Description ", ex.err_description)
POST /v1/profiles
Create a new profile
Body parameter
{
"id": "acd_profile_cd_umls_latest",
"name": "Profile for the latest Concept Detection UMLS Library",
"description": "Provides configurations for running Concept Detection with the latest UMLS library",
"annotators": [
{
"name": "concept_detection",
"parameters": {
"libraries": [
"umls.latest"
]
}
}
]
}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| version | query | string | true | The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. |
| body | body | AcdProfile | true | Input request data in JSON format containing a profile definition. |
Example responses
Profile result
{
"id": "acd_profile_cd_umls_latest",
"name": "Profile for the latest Concept Detection UMLS Library",
"description": "Provides configurations for running Concept Detection with the latest UMLS library",
"annotators": [
{
"name": "concept_detection",
"parameters": {
"libraries": [
"umls.latest"
]
}
}
]
}
400 Response
{
"code": 0,
"message": "string",
"level": "string",
"description": "string",
"moreInfo": "string",
"correlationId": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created | Profile result | ProfileResult |
| 400 | Bad Request | Invalid annotator ID, invalid (missing) annotatorFlow object, or invalid request for the annotator. | serviceError |
| 403 | Forbidden | Cannot persist artifact with a reserved prefix. | serviceError |
| 409 | Conflict | Profile ID conflict. | serviceError |
Get profile
Code samples
curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/v1/profiles/{id}?version={version}"
/*
* Get profile by id example.
*/
import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import com.merative.acd.v1.AnnotatorForClinicalData;
import com.ibm.cloud.sdk.core.http.Response;
import com.merative.acd.v1.model.GetProfilesOptions;
import com.merative.acd.v1.model.AcdProfile;
import com.merative.acd.v1.model.Annotator;
BearerTokenAuthenticator authenticator = new BearerTokenAuthenticator({token});
AnnotatorForClinicalData acd = new AnnotatorForClinicalData(
{version},
AnnotatorForClinicalData.DEFAULT_SERVICE_NAME,
authenticator);
acd.setServiceUrl({url});
GetProfileOptions options = new GetProfileOptions.Builder()
.id("my_profile").build();
Response<AcdProfile> resp = acd.getProfile(options).execute();
AcdProfile profile = resp.getResult();
System.out.println("Id: " + profile.id());
System.out.println("Name: " + profile.name());
System.out.println("Annotators: ");
List<Annotator> annos = profile.annotators();
for (Annotator anno:annos)
System.out.println(' ' + anno.name());
# Get profile by id example.
from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator
import acd_sdk.annotator_for_clinical_data as acd
acd_service = acd.AnnotatorForClinicalDataV1(
authenticator=BearerTokenAuthenticator(bearer_token={token}),
version={version}
)
acd_service.set_service_url({url})
try:
resp = acd_service.get_profile("acd.acd_clinical_insights_v1.0_profile")
rslt = resp.result
print("Id:", rslt['id'])
print("Name:", rslt['name'])
print("Description:", rslt['description'])
except acd.ACDException as ex:
print ("Error Code:", ex.code, " Message:", ex.message, " Correlation Id:", ex.correlation_id, "Error Description ", ex.err_description)
GET /v1/profiles/{id}
Get a profile by ID.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| version | query | string | true | The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. |
| id | path | string | true | Profile ID |
Example responses
Profile result
{
"id": "acd_profile_cd_umls_latest",
"name": "Profile for the latest Concept Detection UMLS Library",
"description": "Provides configurations for running Concept Detection with the latest UMLS library",
"annotators": [
{
"name": "concept_detection",
"parameters": {
"libraries": [
"umls.latest"
]
}
}
]
}
404 Response
{
"code": 0,
"message": "string",
"level": "string",
"description": "string",
"moreInfo": "string",
"correlationId": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Profile result | ProfileResult |
| 404 | Not Found | Profile ID not found | serviceError |
Update profile
Code samples
curl -X PUT \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Authorization: Bearer {token}" \
-d @parameters.json \
"{url}/v1/profiles/{profile_id}?version={version}"
/*
* Update an existing profile example.
*/
import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import com.merative.acd.v1.AnnotatorForClinicalData;
import com.ibm.cloud.sdk.core.http.Response;
import com.merative.acd.v1.model.Annotator;
import com.merative.acd.v1.model.UpdateProfileOptions;
import com.merative.acd.v1.model.UpdateProfileOptions.Builder;
BearerTokenAuthenticator authenticator = new BearerTokenAuthenticator({token});
AnnotatorForClinicalData acd = new AnnotatorForClinicalData(
{version},
AnnotatorForClinicalData.DEFAULT_SERVICE_NAME,
authenticator);
acd.setServiceUrl({url});
Map<String, Set<String>> conceptDetectionParams
= new HashMap<String,Set<String>>(){{put("libraries",
new HashSet<String>() {{ add("umls.2021AA"); }} ); }};
Annotator conceptDetection = new Annotator.Builder()
.name(Annotator.Name.CONCEPT_DETECTION)
.parameters(conceptDetectionParams)
.build();
UpdateProfileOptions.Builder bldr
= new UpdateProfileOptions.Builder();
bldr.id("my_profile");
bldr.newId("my_profile");
bldr.newName("My profile - updated");
bldr.newDescription("My profile desc - updated");
bldr.newAnnotators(Arrays.asList(new Annotator[] {conceptDetection}));
Response<Void> resp = acd.updateProfile(bldr.build().execute();
System.out.println("Response code: " + resp.getStatusCode());
# Update existing profile example.
from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator
import acd_sdk.annotator_for_clinical_data as acd
acd_service = acd.AnnotatorForClinicalDataV1(
authenticator=BearerTokenAuthenticator(bearer_token={token}),
version={version}
)
acd_service.set_service_url({url})
try:
anno_cd = acd.Annotator("concept_detection", parameters = {"libraries": ["umls.latest"]})
anno_attr = acd.Annotator("attribute_detection")
prof_annos = [ anno_cd, anno_attr ]
resp = acd_service.update_profile(
"my_profile",
new_id="my_profile",
new_name="my profile",
new_description="my profile description - UPDATE",
new_annotators=prof_annos)
print("Response Code:",resp.status_code)
except acd.ACDException as ex:
print ("Error Code:", ex.code, " Message:", ex.message, " Correlation Id:", ex.correlation_id, "Error Description ", ex.err_description)
PUT /v1/profiles/{id}
Using the specified Profile ID, updates the profile definition. This is a complete replacement of the existing profile definition using the JSON object provided in the request body.
Body parameter
{
"id": "acd_profile_cd_umls_latest",
"name": "Profile for the latest Concept Detection UMLS Library",
"description": "Provides configurations for running Concept Detection with the latest UMLS library",
"annotators": [
{
"name": "concept_detection",
"parameters": {
"libraries": [
"umls.latest"
]
}
}
]
}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| version | query | string | true | The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. |
| id | path | string | true | Profile ID |
| body | body | AcdProfile | true | The new profile definition |
Example responses
Profile result
{
"id": "acd_profile_cd_umls_latest",
"name": "Profile for the latest Concept Detection UMLS Library",
"description": "Provides configurations for running Concept Detection with the latest UMLS library",
"annotators": [
{
"name": "concept_detection",
"parameters": {
"libraries": [
"umls.latest"
]
}
}
]
}
400 Response
{
"code": 0,
"message": "string",
"level": "string",
"description": "string",
"moreInfo": "string",
"correlationId": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Profile result | ProfileResult |
| 400 | Bad Request | Invalid profile definition. | serviceError |
| 404 | Not Found | Profile ID not found. | serviceError |
Delete profile
Code samples
curl -X DELETE --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/v1/profiles/{id}?version={version}"
/*
* Delete an existing profile example.
*/
import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import com.merative.acd.v1.AnnotatorForClinicalData;
import com.ibm.cloud.sdk.core.http.Response;
import com.merative.acd.v1.model.DeleteProfileOptions;
BearerTokenAuthenticator authenticator = new BearerTokenAuthenticator({token});
AnnotatorForClinicalData acd = new AnnotatorForClinicalData(
{version},
AnnotatorForClinicalData.DEFAULT_SERVICE_NAME,
authenticator);
acd.setServiceUrl({url});
DeleteProfileOptions options = new DeleteProfileOptions
.Builder().id("my_profile").build();
Response<Void> resp = acd.deleteProfile(options).execute();
System.out.println("Response code: " + resp.getStatusCode());
# Delete profile
from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator
import acd_sdk.annotator_for_clinical_data as acd
acd_service = acd.AnnotatorForClinicalDataV1(
authenticator=BearerTokenAuthenticator(bearer_token={token}),
version={version}
)
acd_service.set_service_url({url})
try:
resp = acd_service.delete_profile("my_profile")
print("Response Code:",resp.status_code)
except acd.ACDException as ex:
print ("Error Code:", ex.code, " Message:", ex.message, " Correlation Id:", ex.correlation_id, "Error Description ", ex.err_description)
DELETE /v1/profiles/{id}
Using the specified profile ID, deletes the profile from the list of persisted profiles.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| version | query | string | true | The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. |
| id | path | string | true | Profile ID |
Example responses
Profile result
{
"id": "acd_profile_cd_umls_latest",
"name": "Profile for the latest Concept Detection UMLS Library",
"description": "Provides configurations for running Concept Detection with the latest UMLS library",
"annotators": [
{
"name": "concept_detection",
"parameters": {
"libraries": [
"umls.latest"
]
}
}
]
}
404 Response
{
"code": 0,
"message": "string",
"level": "string",
"description": "string",
"moreInfo": "string",
"correlationId": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Profile result | ProfileResult |
| 404 | Not Found | Profile ID not found. | serviceError |
Flows
Managing persisted flows
List flows
Code samples
curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/v1/flows?version={version}"
/*
* Get flow list example.
*/
import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import com.merative.acd.v1.AnnotatorForClinicalData;
import com.ibm.cloud.sdk.core.http.Response;
import com.merative.acd.v1.model.GetFlowsOptions;
import com.merative.acd.v1.model.AcdFlow;
BearerTokenAuthenticator authenticator = new BearerTokenAuthenticator({token});
AnnotatorForClinicalData acd = new AnnotatorForClinicalData(
{version},
AnnotatorForClinicalData.DEFAULT_SERVICE_NAME,
authenticator);
acd.setServiceUrl({url});
GetFlowsOptions options = new GetFlowsOptions.Builder().build();
Response<Map<String, AcdFlow>> resp = acd.getFlows(options).execute();
Map<String, AcdFlow> mapAcdFlow = resp.getResult();
for( String id:mapAcdFlow.keySet() )
System.out.println("Flow: " + id + " Desc: " + mapAcdFlow.get(id).description());
# Get list of available annotator flows example.
from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator
import acd_sdk.annotator_for_clinical_data as acd
acd_service = acd.AnnotatorForClinicalDataV1(
authenticator=BearerTokenAuthenticator(bearer_token={token}),
version={version}
)
acd_service.set_service_url({url})
try:
resp = acd_service.get_flows()
rslt = resp.result
for flow in rslt:
print("Flow ID:",flow)
except acd.ACDException as ex:
print ("Error Code:", ex.code, " Message:", ex.message, " Correlation Id:", ex.correlation_id, "Error Description ", ex.err_description)
GET /v1/flows
Returns a summary including ID and description of the available persisted flows.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| version | query | string | true | The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. |
Example responses
List flows results
{
"acd.acd_clinical_insights_v1.0_standard_flow": {
"description": "Default annotator flow for the insight cartridge",
"publishedDate": "2020-03-04T13:30:15.318Z"
}
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | List flows results | ListFlowsResults |
Create flow
Code samples
curl -X POST \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Authorization: Bearer {token}" \
-d @parameters.json \
"{url}/v1/flows?version={version}"
/*
* Create an annotator flow example.
*/
import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import com.merative.acd.v1.AnnotatorForClinicalData;
import com.ibm.cloud.sdk.core.http.Response;
import com.merative.acd.v1.model.Annotator;
import com.merative.acd.v1.model.FlowEntry;
import com.merative.acd.v1.model.Flow;
import com.merative.acd.v1.model.AnnotatorFlow;
import com.merative.acd.v1.model.CreateFlowsOptions;
import com.merative.acd.v1.model.AcdFlow;
BearerTokenAuthenticator authenticator = new BearerTokenAuthenticator({token});
AnnotatorForClinicalData acd = new AnnotatorForClinicalData(
{version},
AnnotatorForClinicalData.DEFAULT_SERVICE_NAME,
authenticator);
acd.setServiceUrl({url});
Annotator conceptDetection = new Annotator.Builder()
.name(Annotator.Name.CONCEPT_DETECTION).build();
Annotator negation = new Annotator.Builder()
.name(Annotator.Name.NEGATION).build();
FlowEntry cdFlowEntry = new FlowEntry
.Builder().annotator(conceptDetection).build();
FlowEntry negFlowEntry = new FlowEntry
.Builder().annotator(negation).build();
Flow flow = new Flow.Builder()
.elements(Arrays.asList(cdFlowEntry, negFlowEntry))
.async(true)
.build();
AnnotatorFlow annotatorFlow = new AnnotatorFlow.Builder()
.flow(flow)
.build();
AcdFlow acdFlow = new AcdFlow.Builder()
.id("my_flow")
.name("My flow name")
.description("My flow desc")
.annotatorFlows(Arrays.asList(annotatorFlow))
.build();
CreateFlowsOptions options = new CreateFlowsOptions
.Builder()
.acdFlow(acdFlow)
.build();
Response<Void> resp = acd.createFlows(options).execute();
System.out.println("Response code: " + resp.getStatusCode());
# Create annotator flow
from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator
import acd_sdk.annotator_for_clinical_data as acd
acd_service = acd.AnnotatorForClinicalDataV1(
authenticator=BearerTokenAuthenticator(bearer_token={token}),
version={version}
)
acd_service.set_service_url({url})
try:
anno_cd = acd.Annotator("concept_detection")
anno_neg = acd.Annotator("negation")
flow_entry_cd = acd.FlowEntry(annotator=anno_cd)
flow_entry_neg = acd.FlowEntry(annotator=anno_neg)
flow_entries = [ flow_entry_cd, flow_entry_neg ]
flow = acd.Flow(elements=flow_entries, async_=False)
anno_flow = acd.AnnotatorFlow(flow=flow)
anno_flows = [anno_flow]
resp = acd_service.create_flows(
new_id="my_flow1",
new_name="my flow",
new_description="my flow description",
new_annotator_flows=anno_flows)
print("Response Code:",resp.status_code)
except acd.ACDException as ex:
print ("Error Code:", ex.code, " Message:", ex.message, " Correlation Id:", ex.correlation_id, "Error Description ", ex.err_description)
POST /v1/flows
Create a new annotator flow
Body parameter
{
"id": "flow_simple",
"name": "flow simple",
"description": "A simple flow with two annotators",
"annotatorFlows": [
{
"flow": {
"elements": [
{
"annotator": {
"name": "concept_detection"
}
},
{
"annotator": {
"name": "symptom_disease"
}
}
],
"async": false
}
}
]
}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| version | query | string | true | The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. |
| body | body | AcdFlow | true | Input request data in JSON format containing a flow definition. |
Example responses
Flow result
{
"id": "flow_simple",
"name": "flow simple",
"description": "A simple flow with two annotators",
"annotatorFlows": [
{
"flow": {
"elements": [
{
"annotator": {
"name": "concept_detection"
}
},
{
"annotator": {
"name": "symptom_disease"
}
}
],
"async": false
}
}
]
}
400 Response
{
"code": 0,
"message": "string",
"level": "string",
"description": "string",
"moreInfo": "string",
"correlationId": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 201 | Created | Flow result | FlowResult |
| 400 | Bad Request | Invalid Flow ID, invalid (missing) flow object, or invalid request for persisting a flow | serviceError |
| 403 | Forbidden | Cannot persist artifact with a reserved prefix | serviceError |
| 409 | Conflict | Flow ID conflict. | serviceError |
Get flow
Code samples
curl -X GET \
--header "Authorization: Bearer {token}" \
--header "Accept: application/json" \
{url}/v1/flows/{flow_id}?version={version}"
/*
* Get flow by id example.
*/
import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import com.merative.acd.v1.AnnotatorForClinicalData;
import com.ibm.cloud.sdk.core.http.Response;
import com.merative.acd.v1.model.GetFlowsByIdOptions;
import com.merative.acd.v1.model.AcdFlow;
import com.merative.acd.v1.model.AnnotatorFlow;
import com.merative.acd.v1.model.Flow;
import com.merative.acd.v1.model.FlowEntry;
BearerTokenAuthenticator authenticator = new BearerTokenAuthenticator({token});
AnnotatorForClinicalData acd = new AnnotatorForClinicalData(
{version},
AnnotatorForClinicalData.DEFAULT_SERVICE_NAME,
authenticator);
acd.setServiceUrl({url});
GetFlowsByIdOptions options = new GetFlowsByIdOptions.Builder()
.id("acd.acd_clinical_insights_v1.0_standard_flow")
.build();
Response<AcdFlow> resp = acd.getFlowsById(options).execute();
AcdFlow flow = resp.getResult();
System.out.println("Id: " + flow.id());
System.out.println("Name: " + flow.name());
System.out.println("Description: " + flow.description());
System.out.println("Annotators:");
List<AnnotatorFlow> annotatorFlowList = flow.annotatorFlows();
for ( AnnotatorFlow annotatorFlow : annotatorFlowList ) {
Flow annotatorFlowFlow = annotatorFlow.flow();
List<FlowEntry> flowEntryList = annotatorFlowFlow.elements();
for( FlowEntry flowEntry : flowEntryList ) {
Annotator annotator = flowEntry.annotator();
System.out.println(' ' + annotator.name());
}
}
# Get flow by id example.
from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator
import acd_sdk.annotator_for_clinical_data as acd
acd_service = acd.AnnotatorForClinicalDataV1(
authenticator=BearerTokenAuthenticator(bearer_token={token}),
version={version}
)
acd_service.set_service_url({url})
try:
resp = acd_service.get_flows_by_id("acd.acd_clinical_insights_v1.0_standard_flow")
rslt = resp.result
print("Id:", rslt['id'])
print("Name:", rslt['name'])
print("Desc:", rslt['description'])
for anno_flow in rslt['annotatorFlows']:
flow = anno_flow['flow']
flow_entries = flow['elements']
for flow_entry in flow_entries:
print("Annotator:", flow_entry['annotator']['name'])
except acd.ACDException as ex:
print ("Error Code:", ex.code, " Message:", ex.message, " Correlation Id:", ex.correlation_id, "Error Description ", ex.err_description)
GET /v1/flows/{id}
Using the specified Flow ID, retrieves the flow definition.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| version | query | string | true | The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. |
| id | path | string | true | Flow ID |
Example responses
Flow result
{
"id": "flow_simple",
"name": "flow simple",
"description": "A simple flow with two annotators",
"annotatorFlows": [
{
"flow": {
"elements": [
{
"annotator": {
"name": "concept_detection"
}
},
{
"annotator": {
"name": "symptom_disease"
}
}
],
"async": false
}
}
]
}
404 Response
{
"code": 0,
"message": "string",
"level": "string",
"description": "string",
"moreInfo": "string",
"correlationId": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Flow result | FlowResult |
| 404 | Not Found | Flow ID not found. | serviceError |
Update flow
Code samples
curl -X PUT \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Authorization: Bearer {token}" \
-d @parameters.json \
"{url}/v1/flows/{flow_id}?version={version}"
/*
* Update an existing annotator flow example.
*/
import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import com.merative.acd.v1.AnnotatorForClinicalData;
import com.ibm.cloud.sdk.core.http.Response;
import com.merative.acd.v1.model.Annotator;
import com.merative.acd.v1.model.FlowEntry;
import com.merative.acd.v1.model.Flow;
import com.merative.acd.v1.model.AnnotatorFlow;
import com.merative.acd.v1.model.UpdateFlowsOptions;
import com.merative.acd.v1.model.AcdFlow;
BearerTokenAuthenticator authenticator = new BearerTokenAuthenticator({token});
AnnotatorForClinicalData acd = new AnnotatorForClinicalData(
{version},
AnnotatorForClinicalData.DEFAULT_SERVICE_NAME,
authenticator);
acd.setServiceUrl({url});
Annotator conceptDetection = new Annotator.Builder()
.name(Annotator.Name.CONCEPT_DETECTION).build();
Annotator hypothetical = new Annotator.Builder()
.name(Annotator.Name.HYPOTHETICAL).build();
FlowEntry cdFlowEntry = new FlowEntry
.Builder().annotator(conceptDetection).build();
FlowEntry hypoFlowEntry = new FlowEntry
.Builder().annotator(hypothetical).build();
Flow flow = new Flow.Builder()
.elements(Arrays.asList(cdFlowEntry, hypoFlowEntry))
.async(true)
.build();
AnnotatorFlow annotatorFlow = new AnnotatorFlow.Builder()
.flow(flow)
.build();
AcdFlow acdFlow = new AcdFlow.Builder()
.id("my_flow")
.name("My flow name - updated")
.description("My flow desc - updated")
.annotatorFlows(Arrays.asList(annotatorFlow))
.build();
UpdateFlowsOptions opts = new UpdateFlowsOptions.Builder()
.id("my_flow")
.acdFlow(acdFlow)
.build();
Response<Void> resp = acd.updateFlows(opts).execute();
System.out.println("Response code: " + resp.getStatusCode());
# Update an existing annotator flow example.
from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator
import acd_sdk.annotator_for_clinical_data as acd
acd_service = acd.AnnotatorForClinicalDataV1(
authenticator=BearerTokenAuthenticator(bearer_token={token}),
version={version}
)
acd_service.set_service_url({url})
try:
anno_med = acd.Annotator(name="medication")
anno_neg = acd.Annotator(name="negation")
flow_entry_med = acd.FlowEntry(annotator=anno_med)
flow_entry_neg = acd.FlowEntry(annotator=anno_neg)
flow_entries = [ flow_entry_med, flow_entry_neg ]
flow = acd.Flow(elements=flow_entries, async_=False)
anno_flow = acd.AnnotatorFlow(flow=flow)
anno_flows = [anno_flow]
acd_service.update_flows(
"my_flow",
new_id="my_flow",
new_name="my flow name",
new_description="my flow name - UPDATE",
new_annotator_flows=anno_flows)
print("Response Code:",resp.status_code)
except acd.ACDException as ex:
print ("Error Code:", ex.code, " Message:", ex.message, " Correlation Id:", ex.correlation_id, "Error Description ", ex.err_description)
PUT /v1/flows/{id}
Using the specified Flow ID, updates the persisted flow definition. This is a complete replacement of the existing flow definition using the JSON object provided in the request body.
Body parameter
{
"id": "flow_simple",
"name": "flow simple",
"description": "A simple flow with two annotators",
"annotatorFlows": [
{
"flow": {
"elements": [
{
"annotator": {
"name": "concept_detection"
}
},
{
"annotator": {
"name": "symptom_disease"
}
}
],
"async": false
}
}
]
}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| version | query | string | true | The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. |
| id | path | string | true | Flow ID |
| body | body | AcdFlow | true | The new flow definition |
Example responses
Flow result
{
"id": "flow_simple",
"name": "flow simple",
"description": "A simple flow with two annotators",
"annotatorFlows": [
{
"flow": {
"elements": [
{
"annotator": {
"name": "concept_detection"
}
},
{
"annotator": {
"name": "symptom_disease"
}
}
],
"async": false
}
}
]
}
400 Response
{
"code": 0,
"message": "string",
"level": "string",
"description": "string",
"moreInfo": "string",
"correlationId": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Flow result | FlowResult |
| 400 | Bad Request | Invalid flow definition. | serviceError |
| 404 | Not Found | Flow ID not found. | serviceError |
Delete flow
Code samples
curl -X DELETE \
--header "Authorization: Bearer {token}" \
--header "Accept: application/json" \
{url}/v1/flows/{flow_id}?version={version}"
/*
* Delete an existing annotatorflow example.
*/
import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import com.merative.acd.v1.AnnotatorForClinicalData;
import com.ibm.cloud.sdk.core.http.Response;
import com.merative.acd.v1.model.DeleteFlowsOptions;
import com.merative.acd.v1.model.AcdFlow;
BearerTokenAuthenticator authenticator = new BearerTokenAuthenticator({token});
AnnotatorForClinicalData acd = new AnnotatorForClinicalData(
{version},
AnnotatorForClinicalData.DEFAULT_SERVICE_NAME,
authenticator);
acd.setServiceUrl({url});
DeleteFlowsOptions opts = new DeleteFlowsOptions
.Builder()
.id("my_flow")
.build();
Response<AcdFlow> resp = acd.deleteFlows(opts).execute();
System.out.println("Response code: " + resp.getStatusCode());
# Delete an annotator flow
from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator
import acd_sdk.annotator_for_clinical_data as acd
acd_service = acd.AnnotatorForClinicalDataV1(
authenticator=BearerTokenAuthenticator(bearer_token={token}),
version={version}
)
acd_service.set_service_url({url})
try:
resp = acd_service.delete_flows("my_flow")
print("Response Code:",resp.status_code)
except acd.ACDException as ex:
print ("Error Code:", ex.code, " Message:", ex.message, " Correlation Id:", ex.correlation_id, "Error Description ", ex.err_description)
DELETE /v1/flows/{id}
Using the specified Flow ID, deletes the flow from the list of persisted flows.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| version | query | string | true | The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. |
| id | path | string | true | Flow ID |
Example responses
Flow result
{
"id": "flow_simple",
"name": "flow simple",
"description": "A simple flow with two annotators",
"annotatorFlows": [
{
"flow": {
"elements": [
{
"annotator": {
"name": "concept_detection"
}
},
{
"annotator": {
"name": "symptom_disease"
}
}
],
"async": false
}
}
]
}
404 Response
{
"code": 0,
"message": "string",
"level": "string",
"description": "string",
"moreInfo": "string",
"correlationId": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Flow result | FlowResult |
| 404 | Not Found | Flow ID not found. | serviceError |
Cartridges
Customize annotators using a knowledge cartridge
Deployed cartridges
Code samples
curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/v1/cartridges?version={version}"
/*
* GET list of deployed cartridges example.
*/
import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import com.merative.acd.v1.AnnotatorForClinicalData;
import com.ibm.cloud.sdk.core.http.Response;
import com.merative.acd.v1.model.AcdCartridgesList;
import com.merative.acd.v1.model.AcdCartridges;
BearerTokenAuthenticator authenticator = new BearerTokenAuthenticator({token});
AnnotatorForClinicalData acd = new AnnotatorForClinicalData(
{version},
AnnotatorForClinicalData.DEFAULT_SERVICE_NAME,
authenticator);
acd.setServiceUrl({url});
Response<AcdCartridgesList> response = acd.cartridgesGet().execute();
List<AcdCartridges> cartridges = response.getResult().getCartridges();
for (AcdCartridges cartridge : cartridges) {
System.out.println(cartridge.getId());
}
# Get list of deployed cartridges available to the requesting tenant example.
from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator
import acd_sdk.annotator_for_clinical_data as acd
acd_service = acd.AnnotatorForClinicalDataV1(
authenticator=BearerTokenAuthenticator(bearer_token={token}),
version={version}
)
acd_service.set_service_url({url})
try:
resp = acd_service.cartridges_get()
rslt = resp.result
for cartridge in rslt['cartridges']:
print(cartridge['id'])
print("status: ", cartridge['status'])
except acd.ACDException as ex:
print ("Error Code: ", ex.code, " Message: ", ex.message, " Correlation Id: ", ex.correlation_id, "Error Description ", ex.err_description)
GET /v1/cartridges
Returns a summary of the cumulative cartridge deployment status artifacts for a given tenant.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| version | query | string | true | The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. |
Example responses
List deployed cartridges
{
"cartridges": [
{
"id": "acd.acd_clinical_insights_v1.0",
"status": "completed",
"statusLocation": "api/v1/cartridges/acd.acd_clinical_insights_v1.0",
"startTime": "2020-03-24T18:25:45.835Z",
"endTime": "2020-03-24T18:25:55.847Z",
"duration": "10",
"correlationId": "718f14df-84ed-46ca-9aa8-923bcf1000ae",
"artifactResponseCode": 200
}
]
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | List deployed cartridges | ListCartridgesResults |
Deploy asynchronously
Code samples
curl -X POST \
--header "Content-Type: application/octet-stream" \
--header "Accept: application/json" \
--header "Authorization: Bearer {token}" \
--data-binary @/tmp/my_cartridge.zip \
"{url}/v1/cartridges?version={version}"
/*
* Deploy cartridge asynchronously example.
*/
import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import com.merative.acd.v1.AnnotatorForClinicalData;
import com.ibm.cloud.sdk.core.http.Response;
import com.merative.acd.v1.model.CartridgePostMultipartOptions;
import com.merative.acd.v1.model.DeployCartridgeResponse;
BearerTokenAuthenticator authenticator = new BearerTokenAuthenticator({token});
AnnotatorForClinicalData acd = new AnnotatorForClinicalData(
{version},
AnnotatorForClinicalData.DEFAULT_SERVICE_NAME,
authenticator);
acd.setServiceUrl({url});
File cartridgeZip = new File("/tmp/my_cartridge_v1.0.zip");
CartridgesPostMultipartOptions opts;
try {
opts = new CartridgesPostMultipartOptions.Builder()
.archiveFile(cartridgeZip)
.build();
Response<DeployCartridgeResponse> resp = acd.cartridgesPostMultipart(opts).execute();
System.out.println(resp.getStatusCode());
} catch (FileNotFoundException e) {
e.printStackTrace();
}
# Deploy cartridge asycnhronously example.
from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator
import acd_sdk.annotator_for_clinical_data as acd
acd_service = acd.AnnotatorForClinicalDataV1(
authenticator=BearerTokenAuthenticator(bearer_token={token}),
version={version}
)
acd_service.set_service_url({url})
try:
f = open("/tmp/my_cartridge_v1.0.zip", "rb")
# "multipart/form-data" is also supported for archive_file_content_type
resp = acd_service.cartridges_post_multipart(
archive_file=f,
archive_file_content_type="application/octet-stream")
print(resp.status_code)
except acd.ACDException as ex:
print ("Error Code: ", ex.code, " Message: ", ex.message, " Correlation Id: ", ex.correlation_id, "Error Description ", ex.err_description)
POST /v1/cartridges
Asynchronously deploys a cartridge, returning a reference to a status object for use in tracking the completion status and results of a cartridge deployment.
Body parameter
string
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| version | query | string | true | The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. |
| body | body | string(binary) | true | Cartridge archive file |
Example responses
Cartridge deployment results.
{
"id": "rheumatoid_arthritis_cartridge_v1.0",
"status": "submitted",
"statusCode": 202,
"statusLocation": "api/v1/cartridges/rheumatoid_arthritis_cartridge_v1.0",
"startTime": "2020-05-14T15:35:56.518Z",
"correlationId": "080dc0eb-9151-42bf-9b4f-1f7b456c29b3",
"artifactResponseCode": 0
}
400 Response
{
"code": 0,
"message": "string",
"level": "string",
"description": "string",
"moreInfo": "string",
"correlationId": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 202 | Accepted | Cartridge deployment results. | CartridgesResponseSubmit |
| 400 | Bad Request | Cartridge is not accessible. | serviceError |
| 403 | Forbidden | Cannot persist artifact with a reserved prefix | serviceError |
| 409 | Conflict | Cartridge deployment already exists (Use PUT for updating). | serviceError |
Redeploy asynchronously
Code samples
curl -X PUT \
--header "Content-Type: application/octet-stream" \
--header "Accept: application/json" \
--header "Authorization: Bearer {token}" \
--data-binary @/tmp/my_cartridge.zip \
"{url}/v1/cartridges?version={version}"
/*
* Redeploy cartridge asynchronously example.
*/
import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import com.merative.acd.v1.AnnotatorForClinicalData;
import com.ibm.cloud.sdk.core.http.Response;
import com.merative.acd.v1.model.CartridgePutMultipartOptions;
import com.merative.acd.v1.model.DeployCartridgeResponse;
BearerTokenAuthenticator authenticator = new BearerTokenAuthenticator({token});
AnnotatorForClinicalData acd = new AnnotatorForClinicalData(
{version},
AnnotatorForClinicalData.DEFAULT_SERVICE_NAME,
authenticator);
acd.setServiceUrl({url});
File cartridgeZip = new File("/tmp/my_cartridge_v1.0.zip");
CartridgesPutMultipartOptions opts;
try {
opts = new CartridgesPutMultipartOptions.Builder()
.archiveFile(cartridgeZip)
.build();
Response<DeployCartridgeResponse> resp = acd.cartridgesPutMultipart(opts).execute();
System.out.println(resp.getStatusCode());
} catch (FileNotFoundException e) {
e.printStackTrace();
}
# Redeploy a cartridge asynchronously example.
from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator
import acd_sdk.annotator_for_clinical_data as acd
acd_service = acd.AnnotatorForClinicalDataV1(
authenticator=BearerTokenAuthenticator(bearer_token={token}),
version={version}
)
acd_service.set_service_url({url})
try:
f = open("/tmp/my_cartridge_v1.0.zip", "rb")
# "multipart/form-data" is also supported for archive_file_content_type
resp = acd_service.cartridges_put_multipart(
archive_file=f,
archive_file_content_type="application/octet-stream")
print(resp.status_code)
except acd.ACDException as ex:
print ("Error Code: ", ex.code, " Message: ", ex.message, " Correlation Id: ", ex.correlation_id, "Error Description ", ex.err_description)
PUT /v1/cartridges
Asynchronously re-deploys a cartridge, returning a reference to a status object for use in tracking the completion status and results of a cartridge re-deployment.
Body parameter
string
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| version | query | string | true | The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. |
| body | body | string(binary) | true | Cartridge archive file |
Example responses
Cartridge deployment results.
{
"id": "rheumatoid_arthritis_cartridge_v1.0",
"status": "submitted",
"statusCode": 202,
"statusLocation": "api/v1/cartridges/rheumatoid_arthritis_cartridge_v1.0",
"startTime": "2020-05-14T15:35:56.518Z",
"correlationId": "080dc0eb-9151-42bf-9b4f-1f7b456c29b3",
"artifactResponseCode": 0
}
400 Response
{
"code": 0,
"message": "string",
"level": "string",
"description": "string",
"moreInfo": "string",
"correlationId": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 202 | Accepted | Cartridge deployment results. | CartridgesResponseSubmit |
| 400 | Bad Request | Cartridge is not accessible. | serviceError |
| 403 | Forbidden | Cannot persist artifact with a reserved prefix. | serviceError |
| 404 | Not Found | Cartridge deployment is NOT found (use POST for creation). | serviceError |
| 409 | Conflict | Cartridge deployment in progress. | serviceError |
Deployment status
Code samples
curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/v1/cartridges/{cartridge_id}?version={version}"
/*
* Get deployed cartridge by id example.
*/
import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import com.merative.acd.v1.AnnotatorForClinicalData;
import com.ibm.cloud.sdk.core.http.Response;
import com.merative.acd.v1.model.CartridgesGetIdOptions;
import com.merative.acd.v1.model.AcdCartridges;
BearerTokenAuthenticator authenticator = new BearerTokenAuthenticator({token});
AnnotatorForClinicalData acd = new AnnotatorForClinicalData(
{version},
AnnotatorForClinicalData.DEFAULT_SERVICE_NAME,
authenticator);
acd.setServiceUrl({url});
CartridgesGetIdOptions opts = new CartridgesGetIdOptions.Builder()
.id("my_cartridge_v1.0").build();
Response<AcdCartridges> resp = acd.cartridgesGetId(opts).execute();
System.out.println("Status code: " + resp.getStatusCode());
AcdCartridges cart = resp.getResult();
System.out.println("Id: " + cart.getId() + " status: " + cart.getStatus());
# Get details of specific cartridge deployment example.
from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator
import acd_sdk.annotator_for_clinical_data as acd
acd_service = acd.AnnotatorForClinicalDataV1(
authenticator=BearerTokenAuthenticator(bearer_token={token}),
version={version}
)
acd_service.set_service_url({url})
try:
resp = service.cartridges_get_id("my_cartridge_v1.0")
rslt = resp.result
print("id: ", rslt['id'])
print("status: ", rslt['status'])
except acd.ACDException as ex:
print ("Error Code: ", ex.code, " Message: ", ex.message, " Correlation Id: ", ex.correlation_id, "Error Description ", ex.err_description)
GET /v1/cartridges/{id}
Returns the deployment status for a given a cartridge ID.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | true | Cartridge ID |
| version | query | string | true | The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. |
Example responses
Cartridge deployment results.
{
"id": "rheumatoid_arthritis_cartridge_v1.0",
"status": "completed",
"statusLocation": "api/v1/cartridges/rheumatoid_arthritis_cartridge_v1.0",
"startTime": "2021-10-10T14:43:24.108Z",
"endTime": "2021-10-10T14:43:31.803Z",
"duration": "7",
"correlationId": "48c07fd1-befc-44ee-9c86-b5546834ed2c",
"artifactResponseCode": 200,
"artifactResponse": [
{
"code": 200,
"message": "OK",
"level": "INFO",
"artifact": "rheumatoid_arthritis_cartridge_v1.0_reactions_attributes_attribute_set"
},
{
"code": 200,
"message": "OK",
"level": "INFO",
"artifact": "rheumatoid_arthritis_cartridge_v1.0_reactions_derived_concepts_concept_inference_rules"
},
{
"code": 200,
"message": "OK",
"level": "INFO",
"artifact": "rheumatoid_arthritis_cartridge_v1.0_outcome_attributes_attribute_set"
},
{
"code": 200,
"message": "OK",
"level": "INFO",
"artifact": "rheumatoid_arthritis_cartridge_v1.0_rheumatoid_arthritis_attributes_attribute_set"
},
{
"code": 200,
"message": "OK",
"level": "INFO",
"description": "Flow rheumatoid_arthritis_cartridge_v1.0_no_context_flow updated.",
"artifact": "rheumatoid_arthritis_cartridge_v1.0_no_context_flow"
},
{
"code": 200,
"message": "OK",
"level": "INFO",
"artifact": "rheumatoid_arthritis_cartridge_v1.0_rheumatoid_arthritis_corpus_attributes_attribute_set"
},
{
"code": 200,
"message": "OK",
"level": "INFO",
"description": "Flow rheumatoid_arthritis_cartridge_v1.0_all_annotators_flow updated.",
"artifact": "rheumatoid_arthritis_cartridge_v1.0_all_annotators_flow"
},
{
"code": 200,
"message": "OK",
"level": "INFO",
"artifact": "rheumatoid_arthritis_cartridge_v1.0_general_medical_literature_dictionary_dictionary"
},
{
"code": 200,
"message": "OK",
"level": "INFO",
"artifact": "rheumatoid_arthritis_cartridge_v1.0_general_medical_literature_dictionary_dictionary"
},
{
"code": 200,
"message": "OK",
"level": "INFO",
"artifact": "rheumatoid_arthritis_cartridge_v1.0_general_medical_literature_dictionary_library"
},
{
"code": 200,
"message": "OK",
"level": "INFO",
"artifact": "rheumatoid_arthritis_cartridge_v1.0_general_medical_literature_derived_concepts_concept_inference_rules"
},
{
"code": 200,
"message": "OK",
"level": "INFO",
"artifact": "rheumatoid_arthritis_cartridge_v1.0_general_medical_literature_filter_concept_filter"
},
{
"code": 200,
"message": "OK",
"level": "INFO",
"description": "Profile rheumatoid_arthritis_cartridge_v1.0_profile updated.",
"artifact": "rheumatoid_arthritis_cartridge_v1.0_profile"
},
{
"code": 200,
"message": "OK",
"level": "INFO",
"description": "Flow rheumatoid_arthritis_cartridge_v1.0_default_flow updated.",
"artifact": "rheumatoid_arthritis_cartridge_v1.0_default_flow"
}
]
}
404 Response
{
"code": 0,
"message": "string",
"level": "string",
"description": "string",
"moreInfo": "string",
"correlationId": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Cartridge deployment results. | CartridgesResults |
| 404 | Not Found | Cartridge ID not found. | serviceError |
Deploy
Code samples
curl -X POST \
--header "Content-Type: application/octet-stream" \
--header "Accept: application/json" \
--header "Authorization: Bearer {token}" \
--data-binary @/tmp/my_cartridge.zip \
"{url}/v1/deploy?version={version}"
/*
* DEPRECATED. Deploy cartridge example.
*/
import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import com.merative.acd.v1.AnnotatorForClinicalData;
import com.ibm.cloud.sdk.core.http.Response;
import com.merative.acd.v1.model.DeployCartridgeOptions;
import com.merative.acd.v1.model.DeployCartridgeResponse;
BearerTokenAuthenticator authenticator = new BearerTokenAuthenticator({token});
AnnotatorForClinicalData acd = new AnnotatorForClinicalData(
{version},
AnnotatorForClinicalData.DEFAULT_SERVICE_NAME,
authenticator);
acd.setServiceUrl({url});
File cartridgeZip = new File("/tmp/my_cartridge_v2.0.zip");
DeployCartridgeOptions opts;
try {
opts = new DeployCartridgeOptions.Builder()
.archiveFile(cartridgeZip)
.archiveFileContentType("application/octet-stream")
.update(true).build();
Response<DeployCartridgeResponse> resp = acd.deployCartridge(opts).execute();
System.out.println("Response code: " + resp.getStatusCode());
} catch (FileNotFoundException e) {
e.printStackTrace();
}
# DEPRECATED. Deploy a cartridge example.
from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator
import acd_sdk.annotator_for_clinical_data as acd
acd_service = acd.AnnotatorForClinicalDataV1(
authenticator=BearerTokenAuthenticator(bearer_token={token}),
version={version}
)
acd_service.set_service_url({url})
try:
f = open("/tmp/my_cartridge_v1.0.zip", "rb")
# "multipart/form-data" is also supported for archive_file_content_type
resp = acd_service.deploy_cartridge(
archive_file=f,
archive_file_content_type="application/octet-stream",
update=True)
print(resp.status_code)
except acd.ACDException as ex:
print ("Error Code: ", ex.code, " Message: ", ex.message, " Correlation Id: ", ex.correlation_id, "Error Description ", ex.err_description)
POST /v1/deploy
DEPRECATED. See "Deploy asynchronously" or "Redeploy asynchronously" section.
Body parameter
string
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| version | query | string | true | The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. |
| update | query | boolean | false | Update resources if they already exist |
| body | body | string(binary) | false | Cartridge archive file |
Example responses
Cartridge deployment results.
{
"code": 201,
"artifactResponse": [
{
"code": 201,
"message": "Created",
"level": "INFO",
"correlationId": "9fbfb666-1857-4b7f-aeb2-a42de78d3960",
"artifact": "general_medical_v1.0_general_medical_attribute_set"
},
{
"code": 201,
"message": "Created",
"level": "INFO",
"correlationId": "9fbfb666-1857-4b7f-aeb2-a42de78d3960",
"artifact": "general_medical_v1.0_general_labs_attribute_set"
},
{
"code": 201,
"message": "Created",
"level": "INFO",
"description": "Flow general_medical_v1.0_general_medical_literature_flow created.",
"correlationId": "9fbfb666-1857-4b7f-aeb2-a42de78d3960",
"artifact": "general_medical_v1.0_general_medical_literature_flow"
},
{
"code": 201,
"message": "Created",
"level": "INFO",
"description": "Profile general_medical_v1.0_profile created.",
"correlationId": "9fbfb666-1857-4b7f-aeb2-a42de78d3960",
"artifact": "general_medical_v1.0_profile"
},
{
"code": 201,
"message": "Created",
"level": "INFO",
"description": "Flow general_medical_v1.0_default_flow created.",
"correlationId": "9fbfb666-1857-4b7f-aeb2-a42de78d3960",
"artifact": "general_medical_v1.0_default_flow"
}
]
}
{
"code": 201,
"artifactResponse": [
{
"code": 201,
"message": "Created",
"level": "INFO",
"correlationId": "9fbfb666-1857-4b7f-aeb2-a42de78d3960",
"artifact": "general_medical_v1.0_general_medical_attribute_set"
},
{
"code": 201,
"message": "Created",
"level": "INFO",
"correlationId": "9fbfb666-1857-4b7f-aeb2-a42de78d3960",
"artifact": "general_medical_v1.0_general_labs_attribute_set"
},
{
"code": 201,
"message": "Created",
"level": "INFO",
"description": "Flow general_medical_v1.0_general_medical_literature_flow created.",
"correlationId": "9fbfb666-1857-4b7f-aeb2-a42de78d3960",
"artifact": "general_medical_v1.0_general_medical_literature_flow"
},
{
"code": 201,
"message": "Created",
"level": "INFO",
"description": "Profile general_medical_v1.0_profile created.",
"correlationId": "9fbfb666-1857-4b7f-aeb2-a42de78d3960",
"artifact": "general_medical_v1.0_profile"
},
{
"code": 201,
"message": "Created",
"level": "INFO",
"description": "Flow general_medical_v1.0_default_flow created.",
"correlationId": "9fbfb666-1857-4b7f-aeb2-a42de78d3960",
"artifact": "general_medical_v1.0_default_flow"
}
]
}
{
"code": 201,
"artifactResponse": [
{
"code": 201,
"message": "Created",
"level": "INFO",
"correlationId": "9fbfb666-1857-4b7f-aeb2-a42de78d3960",
"artifact": "general_medical_v1.0_general_medical_attribute_set"
},
{
"code": 201,
"message": "Created",
"level": "INFO",
"correlationId": "9fbfb666-1857-4b7f-aeb2-a42de78d3960",
"artifact": "general_medical_v1.0_general_labs_attribute_set"
},
{
"code": 201,
"message": "Created",
"level": "INFO",
"description": "Flow general_medical_v1.0_general_medical_literature_flow created.",
"correlationId": "9fbfb666-1857-4b7f-aeb2-a42de78d3960",
"artifact": "general_medical_v1.0_general_medical_literature_flow"
},
{
"code": 201,
"message": "Created",
"level": "INFO",
"description": "Profile general_medical_v1.0_profile created.",
"correlationId": "9fbfb666-1857-4b7f-aeb2-a42de78d3960",
"artifact": "general_medical_v1.0_profile"
},
{
"code": 201,
"message": "Created",
"level": "INFO",
"description": "Flow general_medical_v1.0_default_flow created.",
"correlationId": "9fbfb666-1857-4b7f-aeb2-a42de78d3960",
"artifact": "general_medical_v1.0_default_flow"
}
]
}
403 Response
{
"code": 0,
"message": "string",
"level": "string",
"description": "string",
"moreInfo": "string",
"correlationId": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Cartridge deployment results. | DeployCartridgeResults |
| 201 | Created | Cartridge deployment results. | DeployCartridgeResults |
| 207 | Multi-Status | Cartridge deployment results. | DeployCartridgeResults |
| 403 | Forbidden | Cannot persist artifact with a reserved prefix | serviceError |
Analyze
Analyze text with dynamic flow
Code samples
curl -X POST \
--header "Content-Type: application/json" \
--header "Accept: application/json" \
--header "Authorization: Bearer {token}" \
-d @parameters.json \
"{url}/v1/analyze?version={version}"
/*
* Simple analyze request with a dynamic annotator flow example. The SDK will convert the text and flow
* parameters into JSON format before invoking the ACD service.
*/
import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import com.merative.acd.v1.AnnotatorForClinicalData;
import com.merative.acd.v1.model.Concept;
import com.merative.acd.v1.model.ContainerGroup;
import com.merative.acd.v1.model.Flow;
import com.merative.acd.v1.util.FlowUtil;
BearerTokenAuthenticator authenticator = new BearerTokenAuthenticator({token});
AnnotatorForClinicalData acd = new AnnotatorForClinicalData(
{version},
AnnotatorForClinicalData.DEFAULT_SERVICE_NAME,
authenticator);
acd.setServiceUrl({url});
String text = "Patient has lung cancer, but did not smoke. She may consider chemotherapy as part of a treatment plan.";
List<String> annotators = Arrays.asList(
Name.CONCEPT_DETECTION,
Name.NEGATION);
Flow flow = new FlowUtil.Builder().annotators(annotators).build();
ContainerGroup resp = acd.analyze(text, flow);
List<Concept> concepts = resp.getConcepts();
for (Concept c:concepts)
System.out.println("Type: " + c.getType()
+ " Name: " + c.getPreferredName()
+ "| Negated (t/f): " + c.get("negated"));
# Analyze unstructured text via a dynamic annotator flow defined in the request example. The SDK will
# convert the text and flow parameters into JSON format before invoking the ACD service.
from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator
import acd_sdk.annotator_for_clinical_data as acd
acd_service = acd.AnnotatorForClinicalDataV1(
authenticator=BearerTokenAuthenticator(bearer_token={token}),
version={version}
)
acd_service.set_service_url({url})
text = "Patient has lung cancer, but did not smoke. She may consider chemotherapy as part of a treatment plan."
try:
anno_cd = acd.Annotator(name="concept_detection")
anno_neg = acd.Annotator(name="negation")
flow_arr = [
acd.FlowEntry(annotator=anno_cd),
acd.FlowEntry(annotator=anno_neg)
]
flow = acd.Flow(elements=flow_arr, async_=False)
resp = acd_service.analyze(text, flow)
concepts = resp.concepts
for concept in concepts:
print("Type: ", concept.type, "~ Name: ", concept.preferred_name)
except acd.ACDException as ex:
print ("Error Occurred: Code ", ex.code, " Message ", ex.message, " CorrelationId ", ex.correlation_id, "Error Description ", ex.err_description)
POST /v1/analyze
Analyze text to detect medical concepts
Body parameter
{
"annotatorFlows": [
{
"flow": {
"elements": [
{
"annotator": {
"name": "concept_detection"
}
},
{
"annotator": {
"name": "attribute_detection"
}
}
],
"async": false
}
}
],
"unstructured": [
{
"text": "Patient has lung cancer, but did not smoke. She may consider chemotherapy as part of a treatment plan."
}
]
}
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| version | query | string | true | The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. |
| return_analyzed_text | query | boolean | false | Set this to true to show the analyzed text in the response. |
| body | body | string | true | Input request data in JSON format containing an annotatorFlow and an unstructured container. |
Example responses
Analysis results
{
"unstructured": [
{
"data": {
"concepts": [
{
"cui": "C1306460",
"preferredName": "Primary malignant neoplasm of lung",
"semanticType": "neop",
"source": "umls",
"sourceVersion": "2017AA",
"type": "umls.NeoplasticProcess",
"begin": 12,
"end": 23,
"coveredText": "lung cancer",
"uid": 2
},
{
"cui": "C0013216",
"preferredName": "Pharmacotherapy",
"semanticType": "topp",
"source": "umls",
"sourceVersion": "2017AA",
"type": "umls.TherapeuticOrPreventiveProcedure",
"begin": 61,
"end": 73,
"coveredText": "chemotherapy",
"uid": 3
}
],
"attributeValues": [
{
"preferredName": "Primary malignant neoplasm of lung",
"values": [
{
"value": "true"
}
],
"source": "General Medical",
"sourceVersion": "v1.0",
"concept": {
"uid": 2
},
"begin": 12,
"end": 23,
"coveredText": "lung cancer",
"name": "Disease"
},
{
"preferredName": "Pharmacotherapy",
"values": [
{
"value": "true"
}
],
"source": "General Medical",
"sourceVersion": "v1.0",
"concept": {
"uid": 3
},
"begin": 61,
"end": 73,
"coveredText": "chemotherapy",
"name": "Procedure"
}
]
}
}
]
}
400 Response
{
"code": 0,
"message": "string",
"level": "string",
"description": "string",
"moreInfo": "string",
"correlationId": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Analysis results | AnalysisResults |
| 400 | Bad Request | Invalid annotator ID, invalid (missing) annotatorFlow object, or invalid request for the annotator. | serviceError |
| 413 | Payload Too Large | The received text size exceeds the allowed maximum size. | serviceError |
| 503 | Service Unavailable | Annotator unavailable. | serviceError |
| 504 | Gateway Time-out | Timeout while processing request. | serviceError |
Analyze text with cartridge flow
Code samples
curl -X POST -u \
--header "Content-Type: text/plain" \
--header "Accept: application/json" \
--header "Authorization: Bearer {token}" \
--data-binary "Patient has lung cancer, but did not smoke. She may consider chemotherapy as part of a treatment plan." \
"{url}/v1/analyze/acd.acd_clinical_insights_v1.0_standard_flow?version={version}"
/*
* Simple analyze call referencing a persisted annotator flow example.
*/
import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import com.merative.acd.v1.AnnotatorForClinicalData;
import com.merative.acd.v1.model.Concept;
import com.merative.acd.v1.model.ContainerGroup;
BearerTokenAuthenticator authenticator = new BearerTokenAuthenticator({token});
AnnotatorForClinicalData acd = new AnnotatorForClinicalData(
{version},
AnnotatorForClinicalData.DEFAULT_SERVICE_NAME,
authenticator);
acd.setServiceUrl({url});
String flowId = "acd.acd_clinical_insights_v1.0_standard_flow";
String text = "Patient has lung cancer, but did not smoke. She may consider chemotherapy as part of a treatment plan.";
ContainerGroup resp = acd.analyzeWithFlow(flowId, text);
List<Concept> concepts = resp.getConcepts();
for (Concept c:concepts)
System.out.println("Type: " + c.getType() + " Name: " + c.getPreferredName());
# Analyze unstructured text via a predefined annotator flow example.
from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator
import acd_sdk.annotator_for_clinical_data as acd
acd_service = acd.AnnotatorForClinicalDataV1(
authenticator=BearerTokenAuthenticator(bearer_token={token}),
version={version}
)
acd_service.set_service_url({url})
flowId = "acd.acd_clinical_insights_v1.0_standard_flow"
text = "Patient has lung cancer, but did not smoke. She may consider chemotherapy as part of a treatment plan."
try:
response = acd_service.analyze_with_flow(flowId, text)
concepts = response.concepts
for concept in concepts:
print("Type: ", concept.type, "~ Name: ", concept.preferred_name)
except acd.ACDException as ex:
print ("Error Occurred: Code ", ex.code, " Message ", ex.message, " CorrelationId ", ex.correlation_id, "Error Description ", ex.err_description)
POST /v1/analyze/{flow_id}
Analyze text to detect medical concepts using a predefined annotator flow (e.g. deployed cartridge)
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| flow_id | path | string | true | flow identifier . |
| version | query | string | true | The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. |
| return_analyzed_text | query | boolean | false | Set this to true to show the analyzed text in the response. |
| body | body | string | true | Input request data in TEXT or JSON format . |
Example responses
Analysis results
{
"unstructured": [
{
"data": {
"concepts": [
{
"cui": "C1306460",
"preferredName": "Primary malignant neoplasm of lung",
"semanticType": "neop",
"source": "umls",
"sourceVersion": "2017AA",
"type": "umls.NeoplasticProcess",
"begin": 12,
"end": 23,
"coveredText": "lung cancer",
"uid": 2
},
{
"cui": "C0013216",
"preferredName": "Pharmacotherapy",
"semanticType": "topp",
"source": "umls",
"sourceVersion": "2017AA",
"type": "umls.TherapeuticOrPreventiveProcedure",
"begin": 61,
"end": 73,
"coveredText": "chemotherapy",
"uid": 3
}
],
"attributeValues": [
{
"preferredName": "Primary malignant neoplasm of lung",
"values": [
{
"value": "true"
}
],
"source": "General Medical",
"sourceVersion": "v1.0",
"concept": {
"uid": 2
},
"begin": 12,
"end": 23,
"coveredText": "lung cancer",
"name": "Disease"
},
{
"preferredName": "Pharmacotherapy",
"values": [
{
"value": "true"
}
],
"source": "General Medical",
"sourceVersion": "v1.0",
"concept": {
"uid": 3
},
"begin": 61,
"end": 73,
"coveredText": "chemotherapy",
"name": "Procedure"
}
]
}
}
]
}
400 Response
{
"code": 0,
"message": "string",
"level": "string",
"description": "string",
"moreInfo": "string",
"correlationId": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Analysis results | AnalysisResults |
| 400 | Bad Request | Invalid annotator ID, invalid (missing) annotatorFlow object, or invalid request for the annotator. | serviceError |
| 404 | Not Found | Flow ID not found. | serviceError |
| 413 | Payload Too Large | The received text size exceeds the allowed maximum size. | serviceError |
| 503 | Service Unavailable | Annotator unavailable. | serviceError |
| 504 | Gateway Time-out | Timeout while processing request. | serviceError |
Annotators
List annotators
Code samples
curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/v1/annotators?version={version}"
/*
* Get annotator list example.
*/
import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import com.merative.acd.v1.AnnotatorForClinicalData;
import com.ibm.cloud.sdk.core.http.Response;
import com.merative.acd.v1.model.ServiceApiBean;
BearerTokenAuthenticator authenticator = new BearerTokenAuthenticator({token});
AnnotatorForClinicalData acd = new AnnotatorForClinicalData(
{version},
AnnotatorForClinicalData.DEFAULT_SERVICE_NAME,
authenticator);
acd.setServiceUrl({url});
Response<Map<String, ServiceApiBean>> resp = acd.getAnnotators().execute();
Map<String, ServiceApiBean> annotators = resp.getResult();
for (String id:annotators.keySet()) {
System.out.println(id);
ServiceApiBean servApiBean = annotators.get(id);
System.out.println(servApiBean.toString());
}
# Get list of available annotators example.
from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator
import acd_sdk.annotator_for_clinical_data as acd
acd_service = acd.AnnotatorForClinicalDataV1(
authenticator=BearerTokenAuthenticator(bearer_token={token}),
version={version}
)
acd_service.set_service_url({url})
try:
resp = acd_service.get_annotators()
annotator_list = resp.result
for id in annotator_list:
print (id)
annotator = annotator_list[id]
print (json.dumps(annotator, indent=2))
except acd.ACDException as ex:
print ("Error Code:", ex.code, " Message:", ex.message, " Correlation Id:", ex.correlation_id, "Error Description ", ex.err_description)
GET /v1/annotators
Get list of available annotators that can be leveraged to detect information from unstructured data. One or more annotators can be leveraged within a single request to the service.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| version | query | string | true | The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. |
Example responses
List annotators results
{
"allergy": {
"description": "Detect allergy information from clinic notes.",
"version": "2020-08-12T20:12:46Z"
},
"attribute_detection": {
"description": "Detect clinical attributes from a set of concepts and concept values.",
"version": "2020-08-20T11:47:08Z"
},
"bathing_assistance": {
"description": "Detect the need for bathing assistance from case notes.",
"version": "2020-08-12T20:12:46Z"
},
"cancer": {
"description": "Detect cancer history & diagnoses from clinic notes.",
"version": "2020-08-12T20:12:46Z"
},
"concept_detection": {
"description": "Detect UMLS concepts from medical data.",
"version": "2020-08-20T12:25:01Z"
},
"concept_value": {
"description": "Detect values associated with a set of concepts.",
"version": "2020-08-17T07:02:02Z"
},
"disambiguation": {
"description": "Disambiguate medical concepts based on surrounding context.",
"version": "2020-08-18T19:44:41Z"
},
"dressing_assistance": {
"description": "Detect the need for dressing assistance from case notes.",
"version": "2020-08-12T20:12:46Z"
},
"eating_assistance": {
"description": "Detect the need for eating assistance from case notes.",
"version": "2020-08-12T20:12:46Z"
},
"ejection_fraction": {
"description": "Detect ejection fraction from clinic notes.",
"version": "2020-08-12T20:12:46Z"
},
"hypothetical": {
"description": "Detect spans of text deemed to be hypothetical in context such as 'An ultrasound guided biopsy is recommended'.",
"version": "2020-08-17T07:02:35Z"
},
"lab_value": {
"description": "Detect values from lab notes.",
"version": "2020-08-12T20:12:46Z"
},
"medication": {
"description": "Detect medications from clinic notes.",
"version": "2020-08-12T20:12:46Z"
},
"model_broker": {
"description": "Detect medications from clinic notes.",
"version": "2020-08-17T06:02:53Z"
},
"named_entities": {
"description": "Detect named entities from clinic notes.",
"version": "2020-08-12T20:12:46Z"
},
"negation": {
"description": "Detect negated spans from medical data.",
"version": "2020-08-17T08:02:05Z"
},
"procedure": {
"description": "Detect procedures from clinic notes.",
"version": "2020-08-12T20:12:46Z"
},
"relation": {
"description": "Detect ontology-based relationships within clinical data.",
"version": "2020-08-17T09:04:57Z"
},
"section": {
"description": "Detect sections within the case notes.",
"version": "2020-08-12T20:12:46Z"
},
"seeing_assistance": {
"description": "Detect the need for seeing assistance from case notes.",
"version": "2020-08-12T20:12:46Z"
},
"smoking": {
"description": "Detect smoking history from case notes.",
"version": "2020-08-12T20:12:46Z"
},
"spell_checker": {
"description": "Spell check word and phrases in documents.",
"version": "2020-08-17T12:56:53Z"
},
"symptom_disease": {
"description": "Detect symptoms & diseases from clinic notes.",
"version": "2020-08-12T20:12:46Z"
},
"toileting_assistance": {
"description": "Detect the need for bathroom assistance from case notes.",
"version": "2020-08-12T20:12:46Z"
},
"walking_assistance": {
"description": "Detect the need for walking assistance from case notes.",
"version": "2020-08-12T20:12:46Z"
}
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | List annotators results | ListAnnotatorsResults |
Get annotator
Code samples
curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/v1/annotators/{annotator_id}?version={version}"
/*
* Get annotator by id example.
*/
import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import com.merative.acd.v1.AnnotatorForClinicalData;
import com.ibm.cloud.sdk.core.http.Response;
import com.merative.acd.v1.model.Annotator;
import com.merative.acd.v1.model.GetAnnotatorsByIdOptions;
BearerTokenAuthenticator authenticator = new BearerTokenAuthenticator({token});
AnnotatorForClinicalData acd = new AnnotatorForClinicalData(
{version},
AnnotatorForClinicalData.DEFAULT_SERVICE_NAME,
authenticator);
acd.setServiceUrl({url});
GetAnnotatorsByIdOptions opts = new GetAnnotatorsByIdOptions.Builder()
.id("negation").build();
Response<Annotator> resp = acd.getAnnotatorsById(opts).execute();
System.out.println("Response code: " + resp.getStatusCode());
System.out.println(resp.getResult().description());
# Get annotator by id example.
from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator
import acd_sdk.annotator_for_clinical_data as acd
acd_service = acd.AnnotatorForClinicalDataV1(
authenticator=BearerTokenAuthenticator(bearer_token={token}),
version={version}
)
acd_service.set_service_url({url})
try:
resp = acd_service.get_annotator_by_id("concept_detection")
rslt = resp.result
print("Description:", rslt['description'])
except acd.ACDException as ex:
print ("Error Code:", ex.code, " Message:", ex.message, " Correlation Id:", ex.correlation_id, "Error Description ", ex.err_description)
GET /v1/annotators/{id}
Get details of an annotator that can be used to detect information from unstructured data.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| id | path | string | true | The ID the Service API was registered under. |
| version | query | string | true | The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. |
Example responses
Get annotator results
{
"description": "Detect UMLS concepts from medical data.",
"version": "2020-08-20T12:25:01Z"
}
404 Response
{
"code": 0,
"message": "string",
"level": "string",
"description": "string",
"moreInfo": "string",
"correlationId": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Get annotator results | GetAnnotatorResults |
| 404 | Not Found | Annotator ID not found. | serviceError |
Status
Health check
Code samples
curl -X GET --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/v1/status/health_check?version={version}"
/*
* Get ACD service health check status example.
*/
import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import com.merative.acd.v1.AnnotatorForClinicalData;
import com.ibm.cloud.sdk.core.http.Response;
import com.merative.acd.v1.model.ServiceStatus;
BearerTokenAuthenticator authenticator = new BearerTokenAuthenticator({token});
AnnotatorForClinicalData acd = new AnnotatorForClinicalData(
{version},
AnnotatorForClinicalData.DEFAULT_SERVICE_NAME,
authenticator);
acd.setServiceUrl({url});
Response<ServiceStatus> resp = acd.getHealthCheckStatus().execute();
System.out.println("Response code: " + resp.getStatusCode()
+ " Status: " + resp.getStatusMessage());
# Get health check status example.
from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator
import acd_sdk.annotator_for_clinical_data as acd
acd_service = acd.AnnotatorForClinicalDataV1(
authenticator=BearerTokenAuthenticator(bearer_token={token}),
version={version}
)
acd_service.set_service_url({url})
try:
resp = acd_service.get_health_check_status()
print("Response Code:",resp.status_code)
except acd.ACDException as ex:
print ("Error Code:", ex.code, " Message:", ex.message, " Correlation Id:", ex.correlation_id, "Error Description ", ex.err_description)
GET /v1/status/health_check
Get the health status of this service. The "serviceState" response field will be "OK" if the service if functioning properly, "ERROR" if otherwise.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| format | query | string | false | Override response format |
Enumerated Values
| Parameter | Value |
|---|---|
| format | json |
| format | xml |
Example responses
Flow result
{
"serviceState": "OK"
}
500 Response
{
"code": 0,
"message": "string",
"level": "string",
"description": "string",
"moreInfo": "string",
"correlationId": "string"
}
<?xml version="1.0" encoding="UTF-8" ?>
<serviceError>
<code>0</code>
<message>string</message>
<level>string</level>
<description>string</description>
<moreInfo>string</moreInfo>
<correlationId>string</correlationId>
</serviceError>
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 200 | OK | Flow result | HealthCheckResult |
| 500 | Internal Server Error | Service is not running properly | serviceError |
User Data
Delete
Code samples
curl -X DELETE --header "Authorization: Bearer {token}" --header "Accept: application/json" "{url}/v1/user_data?version={version}"
/*
* Delete user data example.
*/
import com.ibm.cloud.sdk.core.security.BearerTokenAuthenticator;
import com.merative.acd.v1.AnnotatorForClinicalData;
import com.ibm.cloud.sdk.core.http.Response;
import com.merative.acd.v1.model.DeleteUserSpecificArtifactsOptions;
BearerTokenAuthenticator authenticator = new BearerTokenAuthenticator({token});
AnnotatorForClinicalData acd = new AnnotatorForClinicalData(
{version},
AnnotatorForClinicalData.DEFAULT_SERVICE_NAME,
authenticator);
acd.setServiceUrl({url});
DeleteUserSpecificArtifactsOptions opts = new DeleteUserSpecificArtifactsOptions();
Response<Void> resp = acd.deleteUserSpecificArtifacts(opts).execute();
System.out.println("Response code: " + resp.getStatusCode());
# Delete user specific artifacts example.
from ibm_cloud_sdk_core.authenticators import BearerTokenAuthenticator
import acd_sdk.annotator_for_clinical_data as acd
acd_service = acd.AnnotatorForClinicalDataV1(
authenticator=BearerTokenAuthenticator(bearer_token={token}),
version={version}
)
acd_service.set_service_url({url})
try:
resp = acd_service.delete_user_specific_artifacts()
print("Response Code:",resp.status_code)
except acd.ACDException as ex:
print ("Error Code:", ex.code, " Message:", ex.message, " Correlation Id:", ex.correlation_id, "Error Description ", ex.err_description)
DELETE /v1/user_data
Delete tenant specific artifacts.
Parameters
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| version | query | string | true | The release date of the version of the API you want to use. Specify dates in YYYY-MM-DD format. |
Example responses
400 Response
{
"code": 0,
"message": "string",
"level": "string",
"description": "string",
"moreInfo": "string",
"correlationId": "string"
}
Responses
| Status | Meaning | Description | Schema |
|---|---|---|---|
| 204 | No Content | The request is successfully processed but no content is returned | None |
| 400 | Bad Request | The tenant id could not be determined from the request. | serviceError |
| 405 | Method Not Allowed | Operation is not supported for file-based object store | serviceError |
Schemas
ConfigurationEntity
{}
Annotator configuration object
Properties
None
Annotator
{
"name": "string",
"configurations": [
{}
]
}
Annotator object
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| name | string | true | none | Annotator name |
| configurations | [ConfigurationEntity] | false | none | Annotator configurations |
AcdProfile
{
"id": "string",
"name": "string",
"description": "string",
"annotators": [
{
"name": "string",
"configurations": [
{}
]
}
]
}
Annotator profile
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | false | none | Profile unique ID |
| name | string | false | none | Profile user friendly name |
| description | string | false | none | Profile description |
| annotators | [Annotator] | false | none | Applicable annotators for the designated configurations |
serviceError
{
"code": 0,
"message": "string",
"level": "string",
"description": "string",
"moreInfo": "string",
"correlationId": "string"
}
ACD error response object
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| code | integer(int32) | false | none | HTTP response code |
| message | string | false | none | HTTP response message |
| level | string | false | none | Error response level |
| description | string | false | none | Error response description |
| moreInfo | string | false | none | Error response details |
| correlationId | string | false | none | Error response correlation ID |
AcdFlow
{
"id": "string",
"name": "string",
"description": "string",
"annotatorFlows": [
{
"profile": "string",
"flow": {
"elements": [
{}
]
}
}
]
}
ACD flow object container
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| id | string | false | none | Flow ID |
| name | string | false | none | Flow name |
| description | string | false | none | Flow description |
| annotatorFlows | [AnnotatorFlow] | false | none | Flow array |
AnnotatorFlow
{
"profile": "string",
"flow": {
"elements": [
{}
]
}
}
ACD annotator flow object
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| profile | string | false | none | ACD profile reference |
| flow | Flow | true | none | ACD flow object |
Flow
{
"elements": [
{}
]
}
ACD flow object
Properties
| Name | Type | Required | Restrictions | Description |
|---|---|---|---|---|
| elements | [FlowEntry] | false | none | Flow element array |
FlowEntry
{}
ACD flow entry
Properties
None
AnalysisResults
{}
Results of the analysis
Properties
None
ListAnnotatorsResults
{}
Annotators available for use in analyzing text to detect medical concepts
Properties
None
GetAnnotatorResults
{}
Details of an available annotator
Properties
None
CartridgesResults
{}
Details of cartridge deployment
Properties
None
CartridgesResponseSubmit
{}
Details of cartridge deployment submit response
Properties
None
DeployCartridgeResults
{}
Details of cartridge deployment
Properties
None
ListFlowsResults
{}
Flows available for analyzing text
Properties
None
ListProfilesResults
{}
Profiles available for incorporating into an annotator flow
Properties
None
ListCartridgesResults
{}
Deployed cartridges
Properties
None
ProfileResult
{}
Persisted profile
Properties
None
FlowResult
{}
Persisted flow
Properties
None
HealthCheckResult
{}
Health check result
Properties
None