{"id":5524,"date":"2025-10-17T15:35:45","date_gmt":"2025-10-17T13:35:45","guid":{"rendered":"https:\/\/kairntech.com\/doc\/?page_id=5524"},"modified":"2025-10-17T15:47:18","modified_gmt":"2025-10-17T13:47:18","slug":"getting-started-with-the-api","status":"publish","type":"page","link":"https:\/\/kairntech.com\/doc\/getting-started-with-the-api\/","title":{"rendered":"Getting started with the API"},"content":{"rendered":"\n<h1 class=\"wp-block-heading\">Base URL<\/h1>\n\n\n\n<p>Identify the URL of the Sherpa instance to use.<\/p>\n\n\n\n<p>Basic Sherpa staging environment: <a href=\"https:\/\/sherpa-sandbox.kairntech.com\/\"><strong>https:\/\/sherpa-sandbox.kairntech.com\/<\/strong><\/a><\/p>\n\n\n\n<h1 class=\"wp-block-heading\">Authentication<\/h1>\n\n\n\n<p>To authenticate you must use an HTTP header with name \u201cX-Kairntech-key&#8221; and value your API token.<\/p>\n\n\n\n<h1 class=\"wp-block-heading\">Endpoints<\/h1>\n\n\n\n<p>The available REST API endpoints are documented at \u201c<em>base url<\/em>\/swagger-ui\/\u201d.<\/p>\n\n\n\n<p>Basic Sherpa staging environment: <a href=\"https:\/\/sherpa-sandbox.kairntech.com\/swagger-ui\/\"><strong>https:\/\/sherpa-sandbox.kairntech.com\/swagger-ui\/<\/strong><\/a><\/p>\n\n\n\n<h1 class=\"wp-block-heading\">Main endpoints<\/h1>\n\n\n\n<h2 class=\"wp-block-heading\">List Projects<\/h2>\n\n\n\n<p>GET \/projects<\/p>\n\n\n\n<p>Returns a list of the projects available to the authenticated user<\/p>\n\n\n\n<p><strong>Swagger UI: <a href=\"https:\/\/sherpa-sandbox.kairntech.com\/swagger-ui\/#\/projects\/getProjects\">https:\/\/sherpa-sandbox.kairntech.com\/swagger-ui\/#\/projects\/getProjects<\/a><\/strong><\/p>\n\n\n\n<p>Example query: <\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>curl -X GET \"https:\/\/sherpa-sandbox.kairntech.com\/api\/projects?computeMetrics=false&amp;computeOwners=false&amp;computeEngines=false&amp;estimatedCounts=false\" -H \"accept: application\/json\" -H \"X-Kairntech-key: <em>your_api_key<\/em>\"<\/code><\/pre>\n\n\n\n<h2 class=\"wp-block-heading\">Annotate a text fragment<\/h2>\n\n\n\n<p>POST \/annotate\/projects\/{<em>projectName<\/em>}\/annotators\/{<em>annotator<\/em>}\/_annotate<\/p>\n\n\n\n<p>Annotates a text fragment with an annotator of a project<\/p>\n\n\n\n<p><strong>Swagger UI: <a href=\"https:\/\/sherpa-sandbox.kairntech.com\/swagger-ui\/#\/annotate\/annotateTextWithProjectAnnotator\">https:\/\/sherpa-sandbox.kairntech.com\/swagger-ui\/#\/annotate\/annotateTextWithProjectAnnotator<\/a><\/strong><\/p>\n\n\n\n<p>Example query: <\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>curl -X POST \"https:\/\/sherpa-sandbox.kairntech.com\/api\/annotate\/projects\/entity_detection_media\/annotators\/pipeline\/_annotate?inlineLabels=true&amp;inlineLabelIds=true&amp;inlineText=true&amp;debug=false&amp;parallelize=false\" -H \"accept: application\/json\" - -H \"X-Kairntech-key: <em>your_api_key<\/em>\" -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.\"<\/code><\/pre>\n\n\n\n<h2 class=\"wp-block-heading\">Annotate the Kairntech JSON format<\/h2>\n\n\n\n<p>POST \/annotate\/projects\/{<em>projectName<\/em>}\/annotators\/{<em>annotator<\/em>}\/_annotate_documents<\/p>\n\n\n\n<p>Annotates documents in the Kairntech Json format<\/p>\n\n\n\n<p><strong>Swagger UI: <a href=\"https:\/\/sherpa-sandbox.kairntech.com\/swagger-ui\/#\/annotate\/annotateDocumentsWithProjectAnnotator\">https:\/\/sherpa-sandbox.kairntech.com\/swagger-ui\/#\/annotate\/annotateDocumentsWithProjectAnnotator<\/a><\/strong><\/p>\n\n\n\n<p>Example query: <\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>curl -X POST \"https:\/\/sherpa-sandbox.kairntech.com\/api\/annotate\/projects\/entity_detection_media\/annotators\/pipeline\/_annotate_documents?inlineLabels=true&amp;inlineLabelIds=true&amp;inlineText=true&amp;debug=false&amp;parallelize=false\" -H \"accept: application\/json\" -H \"X-Kairntech-key: <em>your_api_key<\/em>\" -H \"Content-Type: application\/json\" -H \"X-Requested-With: XMLHttpRequest\" -d \"&#91;{\"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.\"}]\"<\/code><\/pre>\n\n\n\n<h2 class=\"wp-block-heading\">Annotate a binary file (PDF)<\/h2>\n\n\n\n<p>POST \/annotate\/projects\/{<em>projectName<\/em>}\/annotators\/{<em>annotator<\/em>}\/_annotate_binary<\/p>\n\n\n\n<p>Annotates a binary file with an annotator of a project<\/p>\n\n\n\n<p><strong>Swagger UI: <a href=\"https:\/\/sherpa-sandbox.kairntech.com\/swagger-ui\/#\/annotate\/annotateBinaryWithProjectAnnotator\">https:\/\/sherpa-sandbox.kairntech.com\/swagger-ui\/#\/annotate\/annotateBinaryWithProjectAnnotator<\/a><\/strong><\/p>\n\n\n\n<p>Example query with the file path \u201c\/tmp\/news.pdf &#8220;:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>curl -X POST \"https:\/\/sherpa-sandbox.kairntech.com\/api\/annotate\/projects\/entity_detection_media\/annotators\/pipeline\/_annotate_binary?inlineLabels=true&amp;inlineLabelIds=true&amp;inlineText=true&amp;debug=false&amp;parallelize=false\" -H \"accept: application\/json\" -H \"X-Kairntech-key: <em>your_api_key<\/em>\" -H \"Content-Type: multipart\/form-data\" -H \"X-Requested-With: XMLHttpRequest\" -F \u201cfile=@\/tmp\/news.pdf\u201d<\/code><\/pre>\n\n\n\n<p>RAG Scenario with the example project \u201cVenty Energy\u201d<\/p>\n\n\n\n<h2 class=\"wp-block-heading\">Select a predefined PDF converter for a project<\/h2>\n\n\n\n<p>POST \/projects\/{projectName}\/plans\/{name}<\/p>\n\n\n\n<p>Partially updates a processing plan in a project<\/p>\n\n\n\n<p><strong>Swagger UI: <a href=\"https:\/\/sherpa-sandbox.kairntech.com\/swagger-ui\/#\/plans\/patchPlan\">https:\/\/sherpa-sandbox.kairntech.com\/swagger-ui\/#\/plans\/patchPlan<\/a><\/strong><\/p>\n\n\n\n<p>Example query with a predefined converter named \u201cpdf\u201d:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>curl -X PATCH \"https:\/\/sherpa-sandbox.kairntech.com\/api\/projects\/ventys_energy\/plans\/pdf?dryRun=false\" -H&nbsp; \"accept: application\/json\" -H \"X-Kairntech-key: <em>your_api_key<\/em>\" -H&nbsp; \"Content-Type: application\/merge-patch+json\" -H&nbsp; \"X-Requested-With: XMLHttpRequest\" -d \"{\\\"tags\\\":&#91;\\\"conversion\\\",\\\"project-conversion\\\"]}\"<\/code><\/pre>\n\n\n\n<h2 class=\"wp-block-heading\">Upload a PDF document to a project<\/h2>\n\n\n\n<p>POST \/projects\/{<em>projectName<\/em>}\/documents<\/p>\n\n\n\n<p>Allows you to add one or more files to an existing project<\/p>\n\n\n\n<p><strong>Swagger UI: <a href=\"https:\/\/sherpa-sandbox.kairntech.com\/swagger-ui\/#\/documents\/launchDocumentImport\">https:\/\/sherpa-sandbox.kairntech.com\/swagger-ui\/#\/documents\/launchDocumentImport<\/a><\/strong><\/p>\n\n\n\n<p>Example query with the file path \u201c\/documents\/my_file.pdf\u201d:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>curl -X POST \u201chttps:\/\/sherpa-sandbox.kairntech.com\/api\/projects\/ventys_energy\/documents\u201d -H \"accept: application\/json\" -H \"X-Kairntech-key: <em>your_api_key<\/em>\" -H \"Content-Type: multipart\/form-data\" -F \"file=@\/documents\/my_file.pdf\"<\/code><\/pre>\n\n\n\n<h2 class=\"wp-block-heading\">Ask a question to RAG (Retrieval-Augmented Generation)<\/h2>\n\n\n\n<p>POST \/projects\/{<em>projectName<\/em>}\/segments\/_do_search<\/p>\n\n\n\n<p>Searches for segments and provides an answer based on an input query<\/p>\n\n\n\n<p><strong>Swagger UI: <a href=\"https:\/\/sherpa-sandbox.kairntech.com\/swagger-ui\/#\/segments\/searchSegments2\">https:\/\/sherpa-sandbox.kairntech.com\/swagger-ui\/#\/segments\/searchSegments2<\/a><\/strong><\/p>\n\n\n\n<p>Example query excluding the hits from the response for simplification:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>curl -X POST \"https:\/\/sherpa-sandbox.kairntech.com\/api\/projects\/ventys_energy\/segments\/_do_search?defaultSavedSearch=true&amp;htmlVersion=false&amp;asyncAnswer=false\" -H \"accept: application\/json\" -H \"X-Kairntech-key: <em>your_api_key<\/em>\" -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?\"}}\"<\/code><\/pre>\n\n\n\n<p>The corresponding answer indicating 240 segment matches:<\/p>\n\n\n\n<pre class=\"wp-block-code\"><code>{ \"total\": { \"value\": 240, \"relation \": \"eq\" }, \"hits\": &#91;], \"aggregations\": &#91;], \"answer\": \"The compensation policy for a L1 employee, specifically a Junior Engineer, includes a fixed salary range of \u20ac38,000 to \u20ac45,000, a bonus potential of 0 to 5%, and no BSPCE units allocated &#91;2].\" }\"<\/code><\/pre>\n\n\n\n<hr class=\"wp-block-separator has-alpha-channel-opacity\"\/>\n\n\n\n<p class=\"has-text-align-center\">Contact: <a href=\"mailto:support@kairntech.com\">support@kairntech.com<\/a><\/p>\n\n\n\n<p><\/p>\n","protected":false},"excerpt":{"rendered":"<p>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 \u201cX-Kairntech-key&#8221; and value your API token. Endpoints The available REST API endpoints are documented at \u201cbase url\/swagger-ui\/\u201d. Basic Sherpa staging environment: https:\/\/sherpa-sandbox.kairntech.com\/swagger-ui\/ Main endpoints List Projects GET \/projects [&hellip;]<\/p>\n","protected":false},"author":6,"featured_media":0,"parent":0,"menu_order":0,"comment_status":"closed","ping_status":"closed","template":"","meta":{"footnotes":""},"class_list":["post-5524","page","type-page","status-publish","hentry"],"yoast_head":"<!-- This site is optimized with the Yoast SEO plugin v26.8 - https:\/\/yoast.com\/product\/yoast-seo-wordpress\/ -->\n<title>Getting started with the API - Kairntech Documentation<\/title>\n<meta name=\"robots\" content=\"index, follow, max-snippet:-1, max-image-preview:large, max-video-preview:-1\" \/>\n<link rel=\"canonical\" href=\"https:\/\/kairntech.com\/doc\/getting-started-with-the-api\/\" \/>\n<meta property=\"og:locale\" content=\"en_GB\" \/>\n<meta property=\"og:type\" content=\"article\" \/>\n<meta property=\"og:title\" content=\"Getting started with the API - Kairntech Documentation\" \/>\n<meta property=\"og:description\" content=\"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 \u201cX-Kairntech-key&#8221; and value your API token. Endpoints The available REST API endpoints are documented at \u201cbase url\/swagger-ui\/\u201d. Basic Sherpa staging environment: https:\/\/sherpa-sandbox.kairntech.com\/swagger-ui\/ Main endpoints List Projects GET \/projects [&hellip;]\" \/>\n<meta property=\"og:url\" content=\"https:\/\/kairntech.com\/doc\/getting-started-with-the-api\/\" \/>\n<meta property=\"og:site_name\" content=\"Kairntech Documentation\" \/>\n<meta property=\"article:modified_time\" content=\"2025-10-17T13:47:18+00:00\" \/>\n<meta name=\"twitter:card\" content=\"summary_large_image\" \/>\n<meta name=\"twitter:label1\" content=\"Estimated reading time\" \/>\n\t<meta name=\"twitter:data1\" content=\"2 minutes\" \/>\n<script type=\"application\/ld+json\" class=\"yoast-schema-graph\">{\"@context\":\"https:\/\/schema.org\",\"@graph\":[{\"@type\":\"WebPage\",\"@id\":\"https:\/\/kairntech.com\/doc\/getting-started-with-the-api\/\",\"url\":\"https:\/\/kairntech.com\/doc\/getting-started-with-the-api\/\",\"name\":\"Getting started with the API - Kairntech Documentation\",\"isPartOf\":{\"@id\":\"https:\/\/kairntech.com\/doc\/#website\"},\"datePublished\":\"2025-10-17T13:35:45+00:00\",\"dateModified\":\"2025-10-17T13:47:18+00:00\",\"breadcrumb\":{\"@id\":\"https:\/\/kairntech.com\/doc\/getting-started-with-the-api\/#breadcrumb\"},\"inLanguage\":\"en-GB\",\"potentialAction\":[{\"@type\":\"ReadAction\",\"target\":[\"https:\/\/kairntech.com\/doc\/getting-started-with-the-api\/\"]}]},{\"@type\":\"BreadcrumbList\",\"@id\":\"https:\/\/kairntech.com\/doc\/getting-started-with-the-api\/#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Home\",\"item\":\"https:\/\/kairntech.com\/doc\/\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Getting started with the API\"}]},{\"@type\":\"WebSite\",\"@id\":\"https:\/\/kairntech.com\/doc\/#website\",\"url\":\"https:\/\/kairntech.com\/doc\/\",\"name\":\"Kairntech Documentation\",\"description\":\"All the information you need to use Kairntech Software, methodology,  user and installation guides.\",\"potentialAction\":[{\"@type\":\"SearchAction\",\"target\":{\"@type\":\"EntryPoint\",\"urlTemplate\":\"https:\/\/kairntech.com\/doc\/?s={search_term_string}\"},\"query-input\":{\"@type\":\"PropertyValueSpecification\",\"valueRequired\":true,\"valueName\":\"search_term_string\"}}],\"inLanguage\":\"en-GB\"}]}<\/script>\n<!-- \/ Yoast SEO plugin. -->","yoast_head_json":{"title":"Getting started with the API - Kairntech Documentation","robots":{"index":"index","follow":"follow","max-snippet":"max-snippet:-1","max-image-preview":"max-image-preview:large","max-video-preview":"max-video-preview:-1"},"canonical":"https:\/\/kairntech.com\/doc\/getting-started-with-the-api\/","og_locale":"en_GB","og_type":"article","og_title":"Getting started with the API - Kairntech Documentation","og_description":"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 \u201cX-Kairntech-key&#8221; and value your API token. Endpoints The available REST API endpoints are documented at \u201cbase url\/swagger-ui\/\u201d. Basic Sherpa staging environment: https:\/\/sherpa-sandbox.kairntech.com\/swagger-ui\/ Main endpoints List Projects GET \/projects [&hellip;]","og_url":"https:\/\/kairntech.com\/doc\/getting-started-with-the-api\/","og_site_name":"Kairntech Documentation","article_modified_time":"2025-10-17T13:47:18+00:00","twitter_card":"summary_large_image","twitter_misc":{"Estimated reading time":"2 minutes"},"schema":{"@context":"https:\/\/schema.org","@graph":[{"@type":"WebPage","@id":"https:\/\/kairntech.com\/doc\/getting-started-with-the-api\/","url":"https:\/\/kairntech.com\/doc\/getting-started-with-the-api\/","name":"Getting started with the API - Kairntech Documentation","isPartOf":{"@id":"https:\/\/kairntech.com\/doc\/#website"},"datePublished":"2025-10-17T13:35:45+00:00","dateModified":"2025-10-17T13:47:18+00:00","breadcrumb":{"@id":"https:\/\/kairntech.com\/doc\/getting-started-with-the-api\/#breadcrumb"},"inLanguage":"en-GB","potentialAction":[{"@type":"ReadAction","target":["https:\/\/kairntech.com\/doc\/getting-started-with-the-api\/"]}]},{"@type":"BreadcrumbList","@id":"https:\/\/kairntech.com\/doc\/getting-started-with-the-api\/#breadcrumb","itemListElement":[{"@type":"ListItem","position":1,"name":"Home","item":"https:\/\/kairntech.com\/doc\/"},{"@type":"ListItem","position":2,"name":"Getting started with the API"}]},{"@type":"WebSite","@id":"https:\/\/kairntech.com\/doc\/#website","url":"https:\/\/kairntech.com\/doc\/","name":"Kairntech Documentation","description":"All the information you need to use Kairntech Software, methodology,  user and installation guides.","potentialAction":[{"@type":"SearchAction","target":{"@type":"EntryPoint","urlTemplate":"https:\/\/kairntech.com\/doc\/?s={search_term_string}"},"query-input":{"@type":"PropertyValueSpecification","valueRequired":true,"valueName":"search_term_string"}}],"inLanguage":"en-GB"}]}},"jetpack_sharing_enabled":true,"_links":{"self":[{"href":"https:\/\/kairntech.com\/doc\/wp-json\/wp\/v2\/pages\/5524","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/kairntech.com\/doc\/wp-json\/wp\/v2\/pages"}],"about":[{"href":"https:\/\/kairntech.com\/doc\/wp-json\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"https:\/\/kairntech.com\/doc\/wp-json\/wp\/v2\/users\/6"}],"replies":[{"embeddable":true,"href":"https:\/\/kairntech.com\/doc\/wp-json\/wp\/v2\/comments?post=5524"}],"version-history":[{"count":10,"href":"https:\/\/kairntech.com\/doc\/wp-json\/wp\/v2\/pages\/5524\/revisions"}],"predecessor-version":[{"id":5537,"href":"https:\/\/kairntech.com\/doc\/wp-json\/wp\/v2\/pages\/5524\/revisions\/5537"}],"wp:attachment":[{"href":"https:\/\/kairntech.com\/doc\/wp-json\/wp\/v2\/media?parent=5524"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}