Make an API Call (HTTP)

Make an API call in your preferred programming language; Python users should use the Python SDK.

Step 1: Get Models Request (Optional)

ScienceIO offers a number of models (these are also our endpoints) that can be called when you query the API. To get a list of available endpoints, use the following query:

curl https://api.aws.science.io/v2/models

The result looks like this:

{"models":["structure","identify-phi","redact-phi"]}

Step 2: Configure Environment Variables

You must configure environment variables to hold your API keys. Remember that environment variables are used per session and must be reconfigured for each new session. To avoid this, consider adding these variables to your ~/.bashrc or ~/.zshrc depending on your shell.

export SCIENCEIO_KEY_ID={YOUR_API_KEY_ID}
export SCIENCEIO_KEY_SECRET={YOUR_API_SECRET_KEY}

It should look like this:

export SCIENCEIO_KEY_ID=ABCDEFGHIJK123456789
export SCIENCEIO_KEY_SECRET=2a384c12-df4c-4ee4-a14c-7762e8e9dcf3

Step 3: Submit the Inference Request (POST)

Create an inference request using POST with the endpoint of your choosing. Do this by updating the curl URL to the desired endpoint; in this example, we are posting to the structure endpoint. Your API keys will be pulled from your variables.

curl https://api.aws.science.io/v2/structure \
  --request POST \
  --header "Content-type: application/json" \
  --header "x-api-id: $SCIENCEIO_KEY_ID" \
  --header "x-api-secret: $SCIENCEIO_KEY_SECRET" \
  --data '{ "text": "ALS is often called Lou Gehrigs disease, after the baseball player who was diagnosed with it. Doctors usually do not know why ALS occurs."}'

An initial JSON response will be returned to you. Note the request_id (which you will need for Step 4) and the inference status:

{
  "request_id": "12345ab6-c78d-9101-e11f-213141ghijkl",
  "text": "ALS is often called Lou Gehrigs disease, after the baseball player who was diagnosed with it. Doctors usually do not know why ALS occurs.",
  "model_type": "structure",
  "inference_status": "SUBMITTED",
  "message": "Created a new inference request for Structure."
}

Step 4: Retrieve the API Response (GET)

Retrieve the completed JSON response using GET. Use the request_id from the initial response (Step 3) to complete the URL in the first line of code:

curl https://api.aws.science.io/v2/structure/<REQUEST_ID> \
  --request GET \
  --header "x-api-id: $SCIENCEIO_KEY_ID" \
  --header "x-api-secret: $SCIENCEIO_KEY_SECRET"

It should look like this:

curl https://api.aws.science.io/v2/structure/12345ab6-c78d-9101-e11f-213141ghijkl \
  --request GET \
  --header "x-api-id: $SCIENCEIO_KEY_ID" \
  --header "x-api-secret: $SCIENCEIO_KEY_SECRET"

Note that the JSON response includes a new inference status of COMPLETED and an array of dictionaries. For more information about each key:value pair, see JSON Schema: Structure.

{
  "request_id": "12345ab6-c78d-9101-e11f-213141ghijkl",
  "inference_result": {
    "text": "ALS is often called Lou Gehrigs disease, after the baseball player who was diagnosed with it. Doctors usually do not know why ALS occurs.",
    "spans": [
      {
        "concept_id": "UMLS:C0002736",
        "concept_name": "Amyotrophic Lateral Sclerosis",
        "concept_type": "Medical Conditions",
        "pos_end": 3,
        "pos_start": 0,
        "score_id": 0.9996367692947388,
        "score_type": 0.9998749494552612,
        "text": "ALS"
      },
      {
        "concept_id": "UMLS:C0012634",
        "concept_name": "Disease",
        "concept_type": "Medical Conditions",
        "pos_end": 40,
        "pos_start": 33,
        "score_id": 0.99982750415802,
        "score_type": 0.9999518394470215,
        "text": "disease"
      },
      {
        "concept_id": "UMLS:C0004795",
        "concept_name": "Baseball Game",
        "concept_type": "Context",
        "pos_end": 60,
        "pos_start": 52,
        "score_id": 0.9998605251312256,
        "score_type": 0.9998250603675842,
        "text": "baseball"
      },
      {
        "concept_id": "UMLS:C0031831",
        "concept_name": "Physicians",
        "concept_type": "Context",
        "pos_end": 102,
        "pos_start": 95,
        "score_id": 0.9998593330383301,
        "score_type": 0.9999227523803711,
        "text": "Doctors"
      },
      {
        "concept_id": "UMLS:C0002736",
        "concept_name": "Amyotrophic Lateral Sclerosis",
        "concept_type": "Medical Conditions",
        "pos_end": 130,
        "pos_start": 127,
        "score_id": 0.9995817542076111,
        "score_type": 0.9998552799224854,
        "text": "ALS"
      }
    ]
  },
  "model_type": "structure",
  "inference_status": "COMPLETED",
  "message": "Your inference results are ready."
}