Getting started with the API

Base URL

Identify the URL of the Sherpa instance to use.

Basic Sherpa staging environment: https://sherpa-sandbox.kairntech.com/

Authentication

To authenticate you must use an HTTP header with name “X-Kairntech-key” and value your API token.

Endpoints

The available REST API endpoints are documented at “base url/swagger-ui/”.

Basic Sherpa staging environment: https://sherpa-sandbox.kairntech.com/swagger-ui/

Main endpoints

List Projects

GET /projects

Returns a list of the projects available to the authenticated user

Swagger UI: https://sherpa-sandbox.kairntech.com/swagger-ui/#/projects/getProjects

Example query: 

curl -X GET "https://sherpa-sandbox.kairntech.com/api/projects?computeMetrics=false&computeOwners=false&computeEngines=false&estimatedCounts=false" -H "accept: application/json" -H "X-Kairntech-key: your_api_key"

Annotate a text fragment

POST /annotate/projects/{projectName}/annotators/{annotator}/_annotate

Annotates a text fragment with an annotator of a project

Swagger UI: https://sherpa-sandbox.kairntech.com/swagger-ui/#/annotate/annotateTextWithProjectAnnotator

Example query: 

curl -X POST "https://sherpa-sandbox.kairntech.com/api/annotate/projects/entity_detection_media/annotators/pipeline/_annotate?inlineLabels=true&inlineLabelIds=true&inlineText=true&debug=false&parallelize=false" -H "accept: application/json" - -H "X-Kairntech-key: your_api_key" -H "Content-Type: text/plain" -H "X-Requested-With: XMLHttpRequest" -d "Iranian foreign ministry spokesman Saeed Khatibzadeh said that the country's negotiators would not return to Vienna, the site of the year-long talks to restore the Joint Comprehensive Plan of Action (JCPOA), until Washington settles outstanding issues."

Annotate the Kairntech JSON format

POST /annotate/projects/{projectName}/annotators/{annotator}/_annotate_documents

Annotates documents in the Kairntech Json format

Swagger UI: https://sherpa-sandbox.kairntech.com/swagger-ui/#/annotate/annotateDocumentsWithProjectAnnotator

Example query: 

curl -X POST "https://sherpa-sandbox.kairntech.com/api/annotate/projects/entity_detection_media/annotators/pipeline/_annotate_documents?inlineLabels=true&inlineLabelIds=true&inlineText=true&debug=false&parallelize=false" -H "accept: application/json" -H "X-Kairntech-key: your_api_key" -H "Content-Type: application/json" -H "X-Requested-With: XMLHttpRequest" -d "[{"text":"Iranian foreign ministry spokesman Saeed Khatibzadeh said that the country's negotiators would not return to Vienna, the site of the year-long talks to restore the Joint Comprehensive Plan of Action (JCPOA), until Washington settles outstanding issues."}]"

Annotate a binary file (PDF)

POST /annotate/projects/{projectName}/annotators/{annotator}/_annotate_binary

Annotates a binary file with an annotator of a project

Swagger UI: https://sherpa-sandbox.kairntech.com/swagger-ui/#/annotate/annotateBinaryWithProjectAnnotator

Example query with the file path “/tmp/news.pdf “:

curl -X POST "https://sherpa-sandbox.kairntech.com/api/annotate/projects/entity_detection_media/annotators/pipeline/_annotate_binary?inlineLabels=true&inlineLabelIds=true&inlineText=true&debug=false&parallelize=false" -H "accept: application/json" -H "X-Kairntech-key: your_api_key" -H "Content-Type: multipart/form-data" -H "X-Requested-With: XMLHttpRequest" -F “file=@/tmp/news.pdf”

RAG Scenario with the example project “Venty Energy”

Select a predefined PDF converter for a project

POST /projects/{projectName}/plans/{name}

Partially updates a processing plan in a project

Swagger UI: https://sherpa-sandbox.kairntech.com/swagger-ui/#/plans/patchPlan

Example query with a predefined converter named “pdf”:

curl -X PATCH "https://sherpa-sandbox.kairntech.com/api/projects/ventys_energy/plans/pdf?dryRun=false" -H  "accept: application/json" -H "X-Kairntech-key: your_api_key" -H  "Content-Type: application/merge-patch+json" -H  "X-Requested-With: XMLHttpRequest" -d "{\"tags\":[\"conversion\",\"project-conversion\"]}"

Upload a PDF document to a project

POST /projects/{projectName}/documents

Allows you to add one or more files to an existing project

Swagger UI: https://sherpa-sandbox.kairntech.com/swagger-ui/#/documents/launchDocumentImport

Example query with the file path “/documents/my_file.pdf”:

curl -X POST “https://sherpa-sandbox.kairntech.com/api/projects/ventys_energy/documents” -H "accept: application/json" -H "X-Kairntech-key: your_api_key" -H "Content-Type: multipart/form-data" -F "file=@/documents/my_file.pdf"

Ask a question to RAG (Retrieval-Augmented Generation)

POST /projects/{projectName}/segments/_do_search

Searches for segments and provides an answer based on an input query

Swagger UI: https://sherpa-sandbox.kairntech.com/swagger-ui/#/segments/searchSegments2

Example query excluding the hits from the response for simplification:

curl -X POST "https://sherpa-sandbox.kairntech.com/api/projects/ventys_energy/segments/_do_search?defaultSavedSearch=true&htmlVersion=false&asyncAnswer=false" -H "accept: application/json" -H "X-Kairntech-key: your_api_key" -H "Content-Type: application/json" -H "X-Requested-With: XMLHttpRequest" -d "{"output":{"returnHits":false},"questionAnswering":{"enabled":true},"search":{"query":"What is the compensation policy for a L1 employee?"}}"

The corresponding answer indicating 240 segment matches:

{ "total": { "value": 240, "relation ": "eq" }, "hits": [], "aggregations": [], "answer": "The compensation policy for a L1 employee, specifically a Junior Engineer, includes a fixed salary range of €38,000 to €45,000, a bonus potential of 0 to 5%, and no BSPCE units allocated [2]." }"

Contact: support@kairntech.com