Endpoint documentation

Posted about 1 month ago by Harrison Gowers


TABLE OF CONTENTS




Uploading and managing data


Send files to Smartbox


Endpoint URL: (POST) ${ host }/osprey-0.1.0/v1/externalAPI/upload


Header input: 

  • Content-Type: multipart/form-data
  • Authorization: Bearer [access token key]


Request body:

  • externalAPIUploadDTO (object)
  • boxID (string)
  • files (list multipartFile)


Output: 

  • Status / Error message 




List boxes


Endpoint URL: (GET) ${ host }/osprey-0.1.0/v1/externalAPI/boxes


Header input:

  • Content-Type: application/json
  • Authorization: Bearer [access token key]


Request parameters:

  • pageNumber (numeric) - required - value starts from 1
  • pageRows (numeric) - required - value starts from 1
  • sort (string) - Accepted values: "creation date"; "modified date"; "A-Z"; "Z-A"


Output:

  • externalAPIBoxesDTO(object)
    • total (integer)
    • boxList (list object)
      • boxId (string)
      • boxName (string)
      • sharingAvailability (boolean)
      • visibleToDownload (boolean)
      • visibleAllUsers (boolean)
      • usersAccessDownload (map < numeric, string>)
      • usersBoxVisible (map < numeric, string>)


N.B. "total" = total number of boxes (value used for pagination logic - if total equals 35 it is possible to list out a max of 4 pages of results with 10 results per page).




Create box (default configuration)


Endpoint URL: (POST) ${ host }/osprey-0.1.0/v1/externalAPI/create-box


Header input:

  • Content-Type: application/json
  • Authorization: Bearer [access token key]


Request body:

  • CreateBoxAPIRequest (object) – required 
    • boxName (string) - required

Output:

  • CreateBoxAPIResponse(object)
    • boxId (string) – created box id
    • boxName (string) - created box name
    • status  - operation status –  Returned values: "Success!", "Failed!”
    • message – operation message (success messages, error messages)





Create box (advanced configuration)


Endpoint URL: (POST) ${ host }/osprey-0.1.0/v1/externalAPI/create-box


Header input:

  • Content-Type: application/json
  • Authorization: Bearer [access token key]


Request body:

  • CreateBoxAPIRequest (object) – required 
    • boxName (string) - required
    • boxConfiguration (string) - required - Accepted value: "Advanced Configuration"
    • analysisConfiguration (object):
      • selectedPIICategorieschosen PII categories for analysis (see ALL_CATEGORIES_PII list below for available options)
      • selectedRegexList   – chosen regular expressions for analysis
      • selectedBusinessTerms - chosen Dictionaries for analysis
    • securityConfiguration(object):
      • shareFolder - chose whether to share the box.
      • visibleAllUsers - set whether box is visible to all users.
      • visibleToDownload - set whether box can be downloaded by other users.
      • usersAccessDownload - if visibleToDownload field is false then list specified user id(s) to give download permissions to.
      • usersBoxVisible –  if visibleAllUsersfield is false then list specified user id(s) to give visibility to.


Output:

  • CreateBoxAPIResponse(object)
    • boxId (string) – created box id
    • boxName (string) - created box name
    • status  - operation status – returned values: "Success!";"Failed!”
    • message – operation message (success messages, error messages)



ALL_CATEGORIES_PII = "doc_annotate_address_email, doc_annotate_address_url, doc_annotate_address_phone, doc_annotate_address_postcode, doc_annotate_address_complete, doc_annotate_address_ip,doc_annotate_person, doc_annotate_person_female, doc_annotate_person_male, doc_annotate_identifier, doc_annotate_location_country, doc_annotate_location_city, doc_annotate_location_region, doc_annotate_location_airport, doc_annotate_location_country_abbrev, doc_annotate_location_county, doc_annotate_location_province, doc_annotate_location_other, doc_annotate_location_pre, doc_annotate_money, doc_annotate_percent, doc_annotate_organization_company, doc_annotate_organization_department, doc_annotate_organization_government, doc_annotate_organization_newspaper, doc_annotate_organization_university, doc_annotate_organization_team, doc_annotate_date, doc_annotate_ssn, doc_annotate_creditcard, doc_annotate_password"





Query box status


Endpoint URL: (GET) ${ host }/osprey-0.1.0/v1/externalAPI/box-status

  • Example: http://localhost:8080/osprey-0.1.0/v1/externalAPI/box-status?boxId=1708428177639


Header input:

  • Content-Type: application/json
  • Authorization: Bearer [access token key]


Request Parameters:

  • boxId (string) - required


Output:

  • BoxStatusExternalAPIDTO(object)
    • totalFiles (integer) – number of files in box
    • extractionInProgress (boolean) - indicates if box has an upload in progress
    • boxAnalysed (boolean) - indicates if box has been analysed
    • boxRedacted (boolean) – indicates if box has been redacted
    • apiCallStatus (string)  - operation success status - Possible returned values: "Success";"Failed”
    • apiCallMessage (string) – operation message (success / error messages)





List box content


Endpoint URL: (POST) ${ host }/osprey-0.1.0/v1/externalAPI/box-content


Header input:

  • Content-Type: application/json
  • Authorization: Bearer [access token key]


Request body:

  • ListBoxContentRequestDTO(object) 
    • boxId (string) - required
    • pageNumber (integer) – required (value starts from 1)
    • resultsPerPage (integer) - required


Output:

  • ListBoxContentResponseDTO(object)
    • totalDocuments (integer) - number of documents in box
    • apiCallStatus (string) - operation success status - Possible returned values: "Success";"Failed”.
    • apiCallMessage (string) – operation message ( success / error messages) 
    • documents (list <object>)
      • docId (string)
      • path (string) – relative document path
      • name (string)
      • size (integer) – bytes number


N.B. List content API is not supported for sub-directories.






Query document status


Endpoint URL: (GET) ${ host }/osprey-0.1.0/v1/externalAPI/document-status

  • Example: http://localhost:8080/osprey-0.1.0/v1/externalAPI/document-status?docId=17086706721830.2042866083994982


Header input:

  • Content-Type: application/json
  • Authorization: Bearer [access token key]

 

Input: Requested Parameters: 

  • docId (string) - required

 

Output:

  • documentStatusResponseDTO(object)
    • analysisStatus (boolean) - indicates if document has been analysed
    • redactionStatus (boolean) - indicates if document has been redacted
    • apiCallStatus (string) - operation success status – Possible returned values: "Success";"Failed”
    • apiCallMessage(String) – operation message ( success / error messages)
      • metadata (object)
      • size (integer) - bytes number
      • path (string)
      • name (string)
      • id (string)





Culling


Request hash values for duplicates


Endpoint URL: (POST) ${ host }/osprey-0.1.0/v1/externalAPI/request-hash-list-deduplication

  • Example: http://localhost:8080/osprey-0.1.0/v1/externalAPI/request-hash-list-deduplication


Header input:

  • Content-Type: application/json
  • Authorization: Bearer [access token key]


Request body:

  • RequestHashListDeduplicationDTO (object)
    • boxId (string) – required
    • pageNumber (integer) – required (starts from 1)
    • resultsPerPage (integer) - required
    • searchWord (string) - returns only hashes where filename contains [searchWord]


Output:

  • HashListDuplicateResponseDTO (object)
  • hashList (list: object){
    • String fileName (string);
    • String hash (string);
    • Integer numberOfDuplicates (string);

           }

  • totalRows (integer) - number of hashes in box






Request hash values for near-duplicates


Endpoint URL: (POST) ${ host }/osprey-0.1.0/v1/externalAPI/request-hash-list-near-deduplication

  • Example: http://localhost:8080/osprey-0.1.0/v1/externalAPI/request-hash-list-near-deduplication


Header input:

  • Content-Type: application/json
  • Authorization: Bearer [access token key]


Request body:

  • RequestHashListNearDeduplicationDTO (object)
    • boxId (string) – required
    • pageNumber (integer) – required (starts from 1)
    • resultsPerPage (integer) - required
    • searchWord (string) - returns only hashes where filename contains [searchWord]


Output:

  • HashListDuplicateResponseDTO (object)
  • hashList (list: object){
    • String fileName (string);
    • String hash (string);
    • Integer numberOfDuplicates (string);

           }

  • totalRows (integer) - number of hashes in box




Trigger deduplication


Endpoint URL: (POST) ${ host }/osprey-0.1.0/v1/externalAPI/trigger-deduplication

  • Example: http://localhost:8080/osprey-0.1.0/v1/externalAPI/trigger-deduplication


Header input:

  • Content-Type: application/json
  • Authorization: Bearer [access token key]

 

Request body

  • triggerDeduplicationRequestDTO (object)  
    • boxId (string) – required
    • triggerDeduplicationUponAllFiles (boolean) – required
    • selectedHashes (list: string) 
    • excludedHashes (list: string)

Output:

  • Status/error message






Trigger near-deduplication


Endpoint URL: (POST) ${ host }/osprey-0.1.0/v1/externalAPI/trigger-near-deduplication

  • Example: http://localhost:8080/osprey-0.1.0/v1/externalAPI/trigger-near-deduplication


Header input:

  • Content-Type: application/json
  • Authorization: Bearer [access token key]

 

Request body

  • triggerNearDeduplicationRequestDTO (object)  
    • boxId (string) – required
    • fileToKeepOption (string) – Accepted values: "keep_newest_file" (default); "keep_biggest_file"
    • triggerNearDeduplicationUponAllFiles (boolean) – required
    • selectedHashes (list: string) - available if triggerNearDeduplicationUponAllFiles = true
    • excludedHashes (list: string) - available if triggerNearDeduplicationUponAllFiles = true

Output:

  • Status/error message






Trigger de-threading


Endpoint URL: (POST) ${ host }/osprey-0.1.0/v1/externalAPI/trigger-de-threading

  • Example: http://localhost:8080/osprey-0.1.0/v1/externalAPI/trigger-de-threading


Header input:

  • Content-Type: application/json
  • Authorization: Bearer [access token key]


Request body:

  • triggerDeThreadingRequestDTO (object)  
    • boxId (string) – required
    • triggerEmailThreading (boolean) – required
    • removeEmptyFolders (boolean) – required


Output:

  • Status/error message






Redaction


Trigger bulk redaction


Endpoint URL: (POST) ${ host }/osprey-0.1.0/v1/externalAPI/trigger-bulk-redaction

  • Example: http://localhost:8080/osprey-0.1.0/v1/externalAPI/trigger-bulk-redaction


Header input:

  • Content-Type: application/json
  • Authorization: Bearer [access token key]


Request body:

  • triggerBulkRedactionRequestDTO (object) 
    • boxId (string) – required
    • redactAllTerms (boolean) – required - Default value: "false"
    • selectedTerms ( list(string) ) available if redactAllTerms = false
    • excludedTerms( list(string) ) available if redactAllTerms = false
    • selectedPIICategories( list(string) ) available if redactAllTerms = false
    • excludedPIICategories( list(string) ) available if redactAllTerms = false
    • selectedDictionaries( list(string) ) available if redactAllTerms = false
    • excludedDictionaries( list(string) ) available if redactAllTerms = false


Output:

  • Status success/error message


N.B. 

  • If "redactAllTerms = false" at least one entry in a "selected" field is required for a successful request.
  • Excluded values supersede included values - if a term is contained within both an included and excluded selection, it will not be redacted.






Downloading files


Download original file


Endpoint URL: (GET) ${ host }/osprey-0.1.0/v1/externalAPI/download-original

  • Example: http://localhost:8080/osprey-0.1.0/v1/externalAPI/download-original?docId=17084162668800.14521117726950772


Header input:

  • Content-Type: application/json
  • Authorization: Bearer [access token key]

 

Request parameters: 

  • docId (string) - required 

 

Output:

  • File Content (byte[])






Download redacted file


Endpoint URL: (GET) ${ host }/osprey-0.1.0/v1/externalAPI/download-redacted-copy

  • Examplehttp://localhost:8080/osprey-0.1.0/v1/externalAPI/download-redacted-copy?docId=17084162668800.14521117726950772


Header input:

  • Content-Type: application/json
  • Authorization: Bearer [access token key]

 

Request parameters: 

  • docId (string) - required 

 

Output:

  • File Content (byte[])





Download audit copy


Endpoint URL: (GET) ${ host }/osprey-0.1.0/v1/externalAPI/download-audit-copy

  • Examplehttp://localhost:8080/osprey-0.1.0/v1/externalAPI/download-audit-copy?docId=17084162668800.14521117726950772


Header input:

  • Content-Type: application/json
  • Authorization: Bearer [access token key]

 

Request parameters: 

  • docId (string) - required 

 

Output:

  • File Content (byte[])




Settings


List dictionaries


Endpoint URL: (GET) ${ host }/osprey-0.1.0/v1/externalAPI/dictionaries

  • Example: http://localhost:8080/osprey-0.1.0/v1/externalAPI/dictionaries


Header input:

  • Content-Type: application/json
  • Authorization: Bearer [access token key]


Output:

  • (List:Object){
    • dictionaryName (string)
    • dictionaryId (integer)

}




List dictionary terms


Endpoint URL: (GET) ${ host }/osprey-0.1.0/v1/externalAPI/dictionary-terms

  • Example: http://localhost:8080/osprey-0.1.0/v1/externalAPI/dictionary-terms?dictionaryName=ABC123


Header input:

  • Content-Type: application/json
  • Authorization: Bearer [access token key]


Request parameters:

  • dictionaryName (string) - required


Output:

  • DictionaryTermsResponseDTO (object){ 
    • total (number) – number of terms in dictionary.
    • terms (list: string) – the list of terms in dictionary.
    • status (string)  - operation success status - Possible values: "Success";"Failed”.
    • message (string) – operation message (success / error messages).
       }




Create dictionary


Endpoint URL: (POST) ${ host }/osprey-0.1.0/v1/externalAPI/create-dictionary

  • Example: http://localhost:8080/osprey-0.1.0/v1/externalAPI/create-dictionary


Header input:

  • Content-Type: application/json
  • Authorization: Bearer [access token key]


Request body:

  • CreateDictionaryRequestDTO (object) 
    • dictionaryName (string) – required
    • dictionaryDescription (string)


Output:

  • CreateDictionaryResponseDTO (object){
    • status (string)  - operation status - Possible values: "Success";"Failed”.
    • message (string) – operation message (success / error messages).
    • dictionaryName (string)
    • dictionaryId (number)

                    }




Add terms to dictionary


Endpoint URL: (POST) ${ host }/osprey-0.1.0/v1/externalAPI/edit-dictionary

  • Example: http://localhost:8080/osprey-0.1.0/v1/externalAPI/edit-dictionary


Header input:

  • Content-Type: application/json
  • Authorization: Bearer [access token key]


Request body:

  • EditDictionaryTermsRequestDTO (object) 
    • dictionaryId (string) – required
    • file (multipartFile) - required - only CSV files supported


Output:

  • EditDictionaryTermsResponseDTO (object){
    • status (string)  - operation status - Possible values: "Success";"Failed”.
    • message (string) – operation message (success / error messages).

                    }




Overwrite dictionary terms


Endpoint URL: (POST) ${ host }/osprey-0.1.0/v1/externalAPI/overwrite-dictionary

  • Example: http://localhost:8080/osprey-0.1.0/v1/externalAPI/overwrite-dictionary


Header input:

  • Content-Type: application/json
  • Authorization: Bearer [access token key]


Request body:

  • EditDictionaryTermsRequestDTO (object) 
    • dictionaryId (string) – required
    • file (multipartFile) - required - only CSV files supported


Output:

  • EditDictionaryTermsResponseDTO (object){
    • status (string)  - operation status - Possible values: "Success";"Failed”.
    • message (string) – operation message (success / error messages).

                    }




Remove terms from dictionary


Endpoint URL: (POST) ${ host }/osprey-0.1.0/v1/externalAPI/remove-dictionary-terms

  • Example: http://localhost:8080/osprey-0.1.0/v1/externalAPI/remove-dictionary-terms


Header input:

  • Content-Type: application/json
  • Authorization: Bearer [access token key]


Request body:

  • EditDictionaryTermsRequestDTO (object) 
    • dictionaryId (string) – required
    • file (multipartFile) - required - only CSV files supported


Output:

  • EditDictionaryTermsResponseDTO (object){
    • status (string)  - operation status - Possible values: "Success";"Failed”.
    • message (string) – operation message (success / error messages).

                    }




Delete dictionary


Endpoint URL: (POST) ${ host }/osprey-0.1.0/v1/externalAPI/delete-dictionary

  • Example: http://localhost:8080/osprey-0.1.0/v1/externalAPI/delete-dictionary?dictionaryName=ABC123


Header input:

  • Content-Type: application/json
  • Authorization: Bearer [access token key]


Request parameters:

  • dictionaryName (string) – required


Output:

  • DeleteDictionaryResponseDTO (object){
    • status (string)  - operation status - Possible values: "Success";"Failed”.
    • message (string) operation message (success / error messages).
      }




List regular expressions


Endpoint URL(GET) ${ host }/osprey-0.1.0/v1/externalAPI/regular-expressions

  • Examplehttp://localhost:8080/osprey-0.1.0/v1/externalAPI/regular-expressions


Header input:

  • Content-Type: application/json
  • Authorization: Bearer [access token key]


Output:

  • (List:Object){
    • id (integer)
    • title (string)
    • description (string)
    • regex (string)

}





<< Access Tokens

Was this article helpful?

That’s Great!

Thank you for your feedback

Sorry! We couldn't be helpful

Thank you for your feedback

Let us know how can we improve this article!

Select at least one of the reasons
CAPTCHA verification is required.

Feedback sent

We appreciate your effort and will try to fix the article