This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

API Reference

API reference and supporting information.

The APIs for the Classification service and the File Classification service are listed here

1 - Classify

APIs for the Classification Service.

The following APIs are exposed for the Classification Service.

  • Text
  • Tabular
  • JSON
  • XML

Classify Text

This API endpoint classifies plain text unstructured data.

POST http://<Host Address>/pty/discover/v2/classify/text

  • Content type must be a plain text and in an UTF-8 format.

Important:

  • Length of the body is limited to 10 KB. If the body exceeds this limit, it is recommended to use the File Classification Text API. For more information about this File Classification, refer to the File Classification API.
  • Non-Latin text is not supported. If the input contains a non-Latin text, the text is rejected with a 422 error code.

Query Parameters

score_threshold

  • Type: float
  • Description: Optional. Exclude results with a score lower than this threshold.
  • Values: Minimum 0, Maximum 1.0
  • Default: 0.7

Sample Request

curl -X POST "http://<Host_address>/pty/data-discovery/v2/classify/text?score_threshold=0.85" \
     -H "Content-Type: text/plain" \
     --data "You can reach Dave Elliot by phone 203-555-1286"
import requests

url = "http://<Host_address>/pty/data-discovery/v2/classify/text"
params = {"score_threshold": 0.85}
headers = {"Content-Type": "text/plain"}
data = "You can reach Dave Elliot by phone 203-555-1286"

response = requests.post(url, params=params, headers=headers, data=data, verify=False)

print("Status code:", response.status_code)
print("Response JSON:", response.json())
URL: POST `http://<Host_address>/pty/data-discovery/v2/classify/text`
Query Parameters:
-score_threshold (optional), float between 0.0 and 1.0, default: 0.7
Headers:
-Content-Type: text/plain
Body:
-You can reach Dave Elliot by phone 203-555-1286

Classify Tabular Data

This API endpoint classifies structured Tabular data.

POST http://<Host Address>/pty/discover/v2/classify/tabular

  • Content type must be text/csv and UTF-8 encoded.

Query Parameters

score_threshold

  • Type: float
  • Description: Optional. Exclude results with a score lower than this threshold.
  • Values: Minimum 0, Maximum 1.0
  • Default: 0.7

has_headers

  • Type: boolean
  • Description: Optional. Indicates whether the first row represents the column header.
  • Values: true/false
  • Default: true

column_delimiter

  • Type: char
  • Description: Optional. Delimiter to separate the columns.
  • Default: ,

quote_char

  • Type: char
  • Description: Optional. Character to quote fields containing special characters, such as, the column_delimiter or new-line characters.
  • Default: "

Body

  • Content type should be text/csv and in UTF-8 format.

  • Body size is limited to 10K Bytes

Sample Request

curl -X POST "http://<Host_address>/pty/data-discovery/v2/classify/tabular?score_threshold=0.85" \
--header 'Content-Type: text/csv' \
--data-raw 'Social Security Number,Credit Card Number,IBAN,Phone Number
589-25-1068,349384370543801,FR43 9255 4858 47BG 3EBG U4OK O18,(483) 9440301
636-36-3077,4041594844904,AL50 8947 4215 KAEY GAPM NLYC FNZG,(113) 5143119
748-82-2375,3558175715821800,AT34 4082 9269 0841 5702,(763) 5136237
516-62-9861,560221027976015000,FR22 0068 7181 11FB UG8H ECEM 306,(726) 6031636
121-49-9409,374283320982549,DK37 5687 8459 8060 79,(624) 9205200
838-73-3299,5558216060144900,CR54 8952 8144 6403 4765 0,(356) 9479541
439-11-5310,5048376143641900,RS76 6213 4824 0184 8983 74,(544) 5623326
564-06-8466,3543299511845640,EE51 6882 3443 7863 4703,(702) 6093849
518-54-5443,3543019452249540,IT65 D000 3874 2801 Z15I LNLL OOX,(584) 8618371'
import requests

url = "http://<Host_address>/pty/data-discovery/v2/classify/tabular"
params = {"score_threshold": 0.85}
headers = {"Content-Type": "text/csv"}
data = """Social Security Number,Credit Card Number,IBAN,Phone Number
589-25-1068,349384370543801,FR43 9255 4858 47BG 3EBG U4OK O18,(483) 9440301
636-36-3077,4041594844904,AL50 8947 4215 KAEY GAPM NLYC FNZG,(113) 5143119
748-82-2375,3558175715821800,AT34 4082 9269 0841 5702,(763) 5136237
516-62-9861,560221027976015000,FR22 0068 7181 11FB UG8H ECEM 306,(726) 6031636
121-49-9409,374283320982549,DK37 5687 8459 8060 79,(624) 9205200
838-73-3299,5558216060144900,CR54 8952 8144 6403 4765 0,(356) 9479541
439-11-5310,5048376143641900,RS76 6213 4824 0184 8983 74,(544) 5623326
564-06-8466,3543299511845640,EE51 6882 3443 7863 4703,(702) 6093849
518-54-5443,3543019452249540,IT65 D000 3874 2801 Z15I LNLL OOX,(584) 8618371
"""

response = requests.post(url, params=params, headers=headers, data=data, verify=False)

print("Status code:", response.status_code)
try:
    print("Response JSON:", response.json())
except ValueError:
    print("Response Text:", response.text)

URL: POST `http://<Host_address>/pty/data-discovery/v2/classify/tabular`
   Query Parameters:
   -score_threshold (optional), float between 0.0 and 1.0, default: 0.
   -has_headers (optional), Indicates whether the first row represents the column header.
   -column_delimiter (optional), Delimiter to separate the columns.
   -quote_char (optional), Character to quote fields containing special characters, such as, the column_delimiter or new-line characters.
   Headers:
   -Content-Type: text/csv
   Body:
   -Social Security Number,Credit Card Number,IBAN,Phone Number
  589-25-1068,349384370543801,FR43 9255 4858 47BG 3EBG U4OK O18,(483) 9440301
  636-36-3077,4041594844904,AL50 8947 4215 KAEY GAPM NLYC FNZG,(113) 5143119
  748-82-2375,3558175715821800,AT34 4082 9269 0841 5702,(763) 5136237
  516-62-9861,560221027976015000,FR22 0068 7181 11FB UG8H ECEM 306,(726) 6031636
  121-49-9409,374283320982549,DK37 5687 8459 8060 79,(624) 9205200
  838-73-3299,5558216060144900,CR54 8952 8144 6403 4765 0,(356) 9479541
  439-11-5310,5048376143641900,RS76 6213 4824 0184 8983 74,(544) 5623326
  564-06-8466,3543299511845640,EE51 6882 3443 7863 4703,(702) 6093849
  518-54-5443,3543019452249540,IT65 D000 3874 2801 Z15I LNLL OOX,(584) 8618371

Classify JSON Data

This API endpoint classifies structured JSON data.

POST http://<Host Address>/pty/discover/v2/classify/json

Query Parameters

score_threshold

  • Type: float
  • Description: Optional. Exclude results with a score lower than this threshold.
  • Values: Minimum 0, Maximum 1.0
  • Default: 0.7

Body

  • Content type must be application/json and encoded in UTF-8 format.

  • Length of the body is limited to 10K Bytes.

Sample Request

curl --location '<Host_address>/pty/data-discovery/v2/classify/json' \
--header 'Content-Type: application/json' \
--data '{
    "address": "64.219.62.68"
}'
import requests
import json

url = "http://<Host_address>/pty/data-discovery/v2/classify/json"
params = {"score_threshold": 0.85}
headers = {"Content-Type": "application/json"}
data = json.dumps({
  "address": "64.219.62.68"
})

response = requests.post(url, params=params, headers=headers, data=data, verify=False)

print("Status code:", response.status_code)
try:
    print("Response JSON:", response.json())
except ValueError:
    print("Response Text:", response.text)

URL: POST `http://<Host_address>/pty/data-discovery/v2/classify/json`
Query Parameters:
-score_threshold (optional), float between 0.0 and 1.0, default: 0.7
Headers:
-Content-Type: application/json
Body:
-{"address": "64.219.62.68"}

Classify XML Data

This API endpoint classifies structured XML data.

POST https://<Host Address>/pty/data-discovery/v2/classify/xml

Query Parameters

score_threshold

  • Type: float
  • Description: Optional. Exclude results with a score lower than this threshold.
  • Values: Minimum 0, Maximum 1.0
  • Default: 0.7

Body

  • Content type must be application/xml and encoded in UTF-8 format.

  • Length of the body is limited to 10K Bytes.

Sample Request

curl --location '<Host_address>/pty/data-discovery/v2/classify/xml' \
--header 'Content-Type: application/xml' \
--data '<address>64.219.62.68</address>'
import requests

url = "http://<Host_address>/pty/data-discovery/v2/classify/xml"
params = {"score_threshold": 0.85}
headers = {"Content-Type": "application/xml"}
data = "<address>64.219.62.68</address>"

response = requests.post(url, params=params, headers=headers, data=data, verify=False)

print("Status code:", response.status_code)
try:
    print("Response JSON:", response.json())
except ValueError:
    print("Error", response.text)

URL: POST `http://<Host_address>/pty/data-discovery/v2/classify/xml`
Query Parameters:
-score_threshold (optional), float between 0.0 and 1.0, default: 0.7
Headers:
-Content-Type: application/xml
Body:
-<address>64.219.62.68</address>

2 - File Classification

APIs for the File Classification Service.

The following APIs are exposed for the File Classification Service.

  • Text
  • JSON
  • XML

Detect Text

This API classifies sensitive entities in plain text unstructured data.

POST http://<Host Address>/pty/data-discovery/detection/v2/detect/text

  • Content type must be a plain text and in an UTF-8 format.

score_threshold

  • Type: float
  • Description: Optional. Exclude results with a score lower than this threshold.
  • Values: Must be greater than 0.
  • Default: 0.7

Body

  • Content type must be multipart/form-data.

  • The content field contains the plain text to scan.

  • Length of the content is limited to 5 MB.

Sample Request

curl -X POST "http://localhost:8053/pty/data-discovery/detection/v2/detect/text" \
  -F "file=@customer_data.txt"
import os
import json
import requests

# Path to the text file to submit
INPUT_FILEPATH = os.path.join(os.path.dirname(__file__), "fixtures", "example.txt")
#INPUT_FILEPATH = os.path.abspath("/opt/workspaces/discover/classification/deployment_qa/tests/features/common/detection/fixtures/xml_data/5mb_with_pii.xml")

# Detection service endpoint
url = "http://localhost:8053/pty/data-discovery/detection/v2/detect/text"

with open(INPUT_FILEPATH, "rb") as input_file:
    
    response = requests.post(
        url, 
        files={
            "file": (
                os.path.basename(INPUT_FILEPATH), 
                input_file
            )
        }
    )

print("Status Code:", response.status_code)

try:
    print("Response:", json.dumps(response.json(), indent=2))
except ValueError:
    
    print("Response is not valid JSON:", response.text)
URL: POST `http://<Host_address>/pty/data-discovery/detection/v2/detect/text`
Query Parameters:
-score_threshold (optional), float greater than 0 and up to 1.0, default: 0.7
Headers:
-Content-Type: multipart/form-data
Body (form-data):
-content: You can reach Dave Elliot by phone 203-555-1286

Classify JSON Files API

Query Parameters

score_threshold

  • Type: float
  • Description: Optional. Exclude results with a score lower than this threshold.
  • Values: Must be greater than 0.
  • Default: 0.7

Body

  • Content type must be multipart/form-data.

  • The content field contains the JSON text to scan.

  • Length of the content is limited to 5 MB.

Sample Request

curl -X POST "http://localhost:8053/pty/data-discovery/detection/v2/detect/json" \
  -F "file=@customer_data.json"
import os
import json
import requests

# Path to the text file to submit
INPUT_FILEPATH = os.path.join(os.path.dirname(__file__), "fixtures", "complex_hr.json")
# Detection service endpoint
url = "http://localhost:8053/pty/data-discovery/detection/v2/detect/json"

with open(INPUT_FILEPATH, "rb") as input_file:
    
    response = requests.post(
        url, 
        files={
            "file": (
                os.path.basename(INPUT_FILEPATH), 
                input_file
            )
        }
    )

print("Status Code:", response.status_code)

try:
    print("Response:", json.dumps(response.json(), indent=2))
except ValueError:
    
    print("Response is not valid JSON:", response.text)
URL: POST `http://<Host_address>/pty/data-discovery/detection/v2/detect/json`
Query Parameters:
-score_threshold (optional), float greater than 0 and up to 1.0, default: 0.7
Headers:
-Content-Type: multipart/form-data
Body (form-data):
-content: You can reach Dave Elliot by phone 203-555-1286

Classify XML Files API

POST http://<Host Address>/pty/data-discovery/detection/v2/detect/xml

score_threshold

  • Type: float
  • Description: Optional. Exclude results with a score lower than this threshold.
  • Values: Must be greater than 0.
  • Default: 0.7

Body

  • Content type must be multipart/form-data.

  • The content field contains the XML text to scan.

  • Length of the content is limited to 5 MB.

Sample Request

curl -X POST \
  "http://localhost:8053/pty/data-discovery/detection/v2/detect/xml" \
  -F "file=@/path/to/fixtures/complex_hr.xml"
import os
import json
import requests

# Path to the text file to submit
INPUT_FILEPATH = os.path.join(os.path.dirname(__file__), "fixtures", "complex_hr.xml")
# Detection service endpoint
url = "http://localhost:8053/pty/data-discovery/detection/v2/detect/xml"

with open(INPUT_FILEPATH, "rb") as input_file:
    
    response = requests.post(
        url, 
        files={
            "file": (
                os.path.basename(INPUT_FILEPATH), 
                input_file
            )
        }
    )

print("Status Code:", response.status_code)

try:
    print("Response:", json.dumps(response.json(), indent=2))
except ValueError:
    
    print("Response is not valid JSON:", response.text)
URL: POST `http://<Host_address>/pty/data-discovery/detection/v2/detect/xml`
Query Parameters:
-score_threshold (optional), float greater than 0 and up to 1.0, default: 0.7
Headers:
-Content-Type: multipart/form-data
Body (form-data):
-content: You can reach Dave Elliot by phone 203-555-1286

Response Codes

Response CodeDescription
200Successful Response.
206Partial Content. Some classifications succeeded; others failed.
400Bad Request. Invalid input parameters or content.
413Payload too large.
422Validation Error.
500Internal server error. Check server logs.
502Bad Gateway. More than half of the classification calls failed.

3 - Transform

Identify, classify & transform sensitive data.

Identify and classify plain-text sensitive data. Replace the sensitive data with labels of the classified data types, such as, <CREDIT_CARD> and so on.

POST http://<Host Address>/pty/data-discovery/v2/transform/label

Query Parameters

score_threshold

  • Type: float
  • Description: Optional. Label results where the score is greater than this threshold.
  • Values: Minimum 0, Maximum 1.0
  • Default: 0.7

include_providers

  • Type: binary
  • Description: Optional. Include details of the service providers in the response.
  • Values: Yes / No
  • Default: No

include_classification_details

  • Type: binary
  • Description: Optional. Include classification details in the response.
  • Values: Yes / No
  • Default: No

Body

  • Content type must be text/plain and in UTF-8 format.

  • Body size is limited to 10K Bytes

Sample Request

curl -X POST "http://<Host_address>/pty/data-discovery/v2/transform/label?score_threshold=0.85" \
          -H "Content-Type: text/plain" \
          --data "Jake lives at 15 Main st, Hamden 06517, Connecticut."
import requests
    
    url = "http://<Host_address>/pty/data-discovery/v2/transform/label"
    params = {"score_threshold": 0.85}
    headers = {"Content-Type": "text/plain"}
    data = "Jake lives at 15 Main st, Hamden 06517, Connecticut."
    
    response = requests.post(url, params=params, headers=headers, data=data, verify=False)
    
    print("Status code:", response.status_code)
    print("Response JSON:", response.json())
URL: POST `http://<Host_address>/pty/data-discovery/v2/transform/label`
   Query Parameters:
   -score_threshold (optional), float between 0.0 and 1.0, default: 0.
   Headers:
   -Content-Type: text/plain
   Body:
   -Jake lives at 15 Main st, Hamden 06517, Connecticut.

4 - Common APIs

Standard operational endpoints available on the service.

These endpoints provide operational capabilities such as retrieving the API specification, managing log levels, checking version information, and monitoring service health.

Version API

View runtime version information.

GET http://<Host Address>/version

Sample Request

curl -X GET "http://<Host_address>/version"
     
import requests
    
    url = "http://<Host_address>/version"
    response = requests.get(url, verify=False)
    
    print("Status code:", response.status_code)
    try:
        print("Response JSON:", response.json())
    except ValueError:
        print("Response Text:", response.text)
    
URL: GET `http: //<Host_address>/version`

Response Codes

CodeDescription
200Version information retrieved successfully.

Readiness Probe

This is used by Kubernetes as a readiness probe.

GET http://<Host Address>/ready

Sample Request

curl -X GET "http://<Host_address>/ready"
     
import requests
    
    url = "http://<Host_address>/ready"
    response = requests.get(url, verify=False)
    
    print("Status code:", response.status_code)

The file /docs/discover/restapi/commonapis/output/postman.json was not found.

Response Codes

CodeDescription
204Service is fully initialized and can handle requests.
503Service is not yet ready to serve requests.

Liveness Probe

Used by Kubernetes as a liveness probe.

GET http://<Host Address>/live

Used by Kubernetes as a liveness probe.

Sample Request

curl -X GET "http://<Host_address>/live"
     
import requests
    
    url = "http://<Host_address>/live"
    response = requests.get(url, verify=False)
    
    print("Status code:", response.status_code)
    
URL: GET `http: //<Host_address>/live`

Response Codes

CodeDescription
204Service can handle requests.

Health Check

Returns service health status including individual component-level checks.

GET http://<Host Address>/health

Sample Request

curl -X GET "http://<Host_address>/health"
     
import requests
    
    url = "http://<Host_address>/health"
    response = requests.get(url, verify=False)
    
    print("Status code:", response.status_code)
    try:
        print("Response JSON:", response.json())
    except ValueError:
        print("Response Text:", response.text)
    
URL: GET `http: //<Host_address>/health`

Response Codes

CodeDescription
200Service is running normally.
503Service is unhealthy. Its components may be initializing or may need a restart.

Retrieve Logs

GET http://<Host Address>/log

Returns the current runtime logging level.

Sample Request

curl -X GET "http://<Host_address>/log"
     
import requests
    
    url = "http://<Host_address>/log"
    response = requests.get(url, verify=False)
    
    print("Status code:", response.status_code)
    try:
        print("Response JSON:", response.json())
    except ValueError:
        print("Response Text:", response.text)
    
URL: GET `http://<Host_address>/log`

Update the Logging Level

Updates the runtime logging level.

POST http://<Host Address>/log

Request Body

NameTypeRequiredDescription
levelstringYesThe log level to set. Possible values: debug, info, warn.

Sample Request

curl -X POST "http://<Host_address>/log" \
       -H "Content-Type: application/json" \
       -d '{"level": "debug"}'
     
import requests
    
    url = "http://<Host_address>/log"
    payload = {"level": "debug"}
    headers = {"Content-Type": "application/json"}
    response = requests.post(url, json=payload, headers=headers, verify=False)
    
    print("Status code:", response.status_code)
    try:
        print("Response JSON:", response.json())
    except ValueError:
        print("Response Text:", response.text)
    
URL: POST `http: //<Host_address>/log`
   Body (JSON): {
       "level": "debug"
   }

Response Codes

CodeDescription
200Log level updated successfully.
500An error occurred (e.g., invalid log level specified).

Note: The service currently returns 500 for invalid log level values. The OpenAPI spec defines 400 for this case — this is a known discrepancy to be addressed in a future release.

Supported Entities

List the entities supported by Classify.

GET http://<Host Address>/pty/data-discovery/v2/entities

Query Parameters

None

Sample Request

curl -X GET "http://<Host_address>/entities"
     
import requests
    
    url = "http://<Host_address>/entities"
    response = requests.get(url, verify=False)
    
    print("Status code:", response.status_code)
    try:
        print("Response JSON:", response.json())
    except ValueError:
        print("Response Text:", response.text)
    
URL: GET `http://<Host_address>/entities`
CodeDescription
200Entities retrieved successfully.
502Bad Gateway. The service has no entity list it can serve.
598Internal Server Error. Check server logs.

API Specification

Returns the OpenAPI specification for the Classify API.

GET http://<Host Address>/doc

Sample Request

curl -X GET "http://<Host_address>/doc"
     
import requests
    
    url = "http://<Host_address>/doc"
    response = requests.get(url, verify=False)
    
    print("Status code:", response.status_code)
    print("Response YAML:", response.text)
    
URL: GET `http: //<Host_address>/doc`

Response Codes

CodeDescription
200The OpenAPI specification is returned in YAML format.