Skip to main content

Create, update, and delete KS via API

The examples below use curl and shell scripts. You can change it. Use StackSpot AI to adapt it to the language you want.

Requirements

  • Due to authentication restrictions, uploading directly via API is only available for Enterprise accounts.

  • Authenticate to get to use the script.

Follow the steps to authenticate on the Services Credential page refer to the StackSpot EDP documentation.

caution

Activate the following permissions:

  • ai_dev and ai_admin.

Contact your account administrator if you cannot create a Service Credential.

  • Copy the 'client id', 'client key', and 'realm' fields to use as environment variables (the first two should be secrets) or the curl example at the bottom of the page in the 'how to use it' section. You won't be able to see them again.
danger

If you lose them, revoke the credential and create a new one.

  • The following examples consider the access token to be set as the JWT environment variable. You can extract it from the authentication curl with the jq command to get the value for the access_token key from the returned JSON, then save it as an environment variable using the export command, such as:
export JWT=$(curl -s "https://idm.stackspot.com/$REALM/oidc/oauth/token" -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials' -d "client_id=$CLIENT_ID" -d "client_secret=$CLIENT_KEY" | jq -r '.access_token')

Create Knowledge Source via API

Follow the steps below:

Step 1. Run to create the KS:

curl -s -X POST "https://data-integration-api.stackspot.com/v1/knowledge-sources" -H "Authorization: Bearer $JWT" -H 'Content-Type: application/json' -d '{"slug": "my-cli-ks-v2", "name": "my-cli-ks-v2", "description": "KS created via CLI using form v2", "type": "<one of api, snippet or custom>"}'

Step 2. Go to the StackSpot AI Portal.

  • Access the ‘Knowledge Sources’ section on the left-side menu and search for the one you just created.

Upload files to an existing Knowledge Source

danger

When adding new files to a Knowledge Source, the limit is 10 MiB.

caution

When you upload files to a Knowledge Source, the file extension in the file_name the field is important. StackSpot AI relies on the file extension to identify the content’s syntax, ensuring the uploaded file is processed and categorized correctly.

Why is the file extension important?

The file extension allows StackSpot AI to:

  1. Automatically identify the file content’s syntax;
  2. Apply the correct parsing rules for accurate processing;
  3. Make the content easy to search and usable within the Knowledge Source.

Example

If you upload a file named example.json, StackSpot AI will process it as a JSON file. If the extension is missing or incorrect, the system may not interpret the content properly.

Which extensions are allowed?

This list varies according to the Knowledge Source type:

  • API: json and yaml.
  • Custom: txt, md, json, yaml and pdf.
  • Snippet: abap, ada, adb, ads, aes, cls, azcli, bat, cmd, bicep, c, h, cs, cpp, cc, cxx, hh, hpp, hxx, mligo, prg, clj, cljs, cljc, edn, cob, cbl, coffee, csp, css, d, dart, dockerfile, ecl, ex, exs, erl, hrl, fs, fsi, ml, mli, flow, f90, f, for, f77, ftl, go, graphql, gql, groovy, gvy, gy, gsh, handlebars, hbs, hs, hcl, tf, html, htm, ini, java, js, mjs, jsx, json, jl, kt, kts, less, lex, liquid, lua, m3, md, dax, asm, sql, m, pas, pp, ligo, pl, pm, php, pla, txt, dats, sats, hats, pq, ps1, psm1, psd1, proto, pug, py, qs, r, rkt, cshtml, redis, rego, rst, rb, rs, sb, lisp, scala, scm, scss, sh, sol, rq, st, swift, sv, tcl, twig, ts, tsx, vb, v, xml, yaml, yml.

All types accept ZIP files, but only process the files within the ZIP that have individually permitted extensions in the Knowledge Source.

You can upload one or more files to an existing Knowledge Source. You can also choose to upload a zip file. Follow the steps below to do it.

caution

You need to have already created a Knowledge Source here. If you still need to make it, please create it now.

Step 1. Run the following script to start the upload process by sending the file to StackSpot AI:

You need to replace all example fields (placeholders) with the correct values for your environment.

upload_data=$(curl -X POST 'https://data-integration-api.stackspot.com/v2/file-upload/form' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $JWT" \
  -d '{"file_name": "<desired file's name>", "target_id": "<KS slug>", "target_type": "KNOWLEDGE_SOURCE", "expiration": 600 }')

echo -n 'file upload id = '
echo "$upload_data" | jq -r '.id'

curl -X POST "$(echo "$upload_data" | jq -r '.url')" \
  -F "key=$(echo "$upload_data" | jq -r '.form.key')" \
  -F "x-amz-algorithm=$(echo "$upload_data" | jq -r '.form["x-amz-algorithm"]')" \
  -F "x-amz-credential=$(echo "$upload_data" | jq -r '.form["x-amz-credential"]')" \
  -F "x-amz-date=$(echo "$upload_data" | jq -r '.form["x-amz-date"]')" \
  -F "x-amz-security-token=$(echo "$upload_data" | jq -r '.form["x-amz-security-token"]')" \
  -F "policy=$(echo "$upload_data" | jq -r '.form.policy')" \
  -F "x-amz-signature=$(echo "$upload_data" | jq -r '.form["x-amz-signature"]')" \
  -F 'file=@"<absolute path to desired file>"

Step 2. Run the command below to start the conversion of the uploaded file into objects in the Knowledge Source:

curl -X POST "https://data-integration-api.stackspot.com/v1/file-upload/$(echo "$upload_data" | jq -r '.id')/knowledge-objects" \
-H 'Content-Type: application/json' \
-H "Authorization: Bearer $JWT" \
-d '{ "split_strategy": "<one of NONE, LINES_QUANTITY, TOKENS_QUANTITY, CHARACTERS_QUANTITY, SYNTACTIC>", "split_quantity": 500, "split_overlap": 50 }'

Split Strategy is valid based on the Knowledge Source type:

  • API: NONE, ENDPOINT.
  • SNIPPET: NONE, LINES_QUANTITY, TOKENS_QUANTITY, SYNTACTIC.
  • CUSTOM: NONE, LINES_QUANTITY, TOKENS_QUANTITY, CHARACTERS_QUANTITY, SYNTACTIC.

To visualize the split process and better understand these parameters, use the StackSpot AI Portal and attempt to add the file to your Knowledge Source.

Step 3. To check the upload status, run the command below:

curl --location "https://data-integration-api.stackspot.com/v1/file-upload/$(echo "$upload_data" | jq -r '.id')" --header "Authorization: Bearer $JWT"

Response example:

{
  "id": "ULID",
  "file_name": "string",
  "target_id": "string",
  "target_type": "KNOWLEDGE_SOURCE",
  "status": "NEW | PROCESSING | SPLITTED | INDEXED | SPLIT_ERROR | ERROR",
  "error_description": "string",
  "summary": {
    "added": "int",
    "preserved": "int",
    "removed": "int",
    "errors": {"string": "string"}
  }
}

Step 4. After the upload is done, access the StackSpot AI Portal;

Step 5. On the left side menu, click ‘Knowledge Sources’ and then check if your Knowledge Source has new objects.

tip
  • If you receive a 403 error, you do not have permission to access the Knowledge Source.

Upload standalone content to an existing Knowledge Source

caution

You must have already created a Knowledge Source here. If you still need to create it, please do so now.

Only the KS types mentioned support this.

Snippet

curl -L 'https://genai-code-buddy-api.stackspot.com/v1/knowledge-sources/<KS slug>/snippets' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $JWT" \
  -d '{
      "use_case": "<description>",
      "code": "<content>",
      "language": "<one of sql, csp, freemarker2, systemverilog, sb, scheme, groovy, postiats, sol, mips, twig, php, aes, coffeescript, json, ocaml, sparql, xml, powershell, haskell, rust, scala, plaintext, octave, abap, lua, shell, less, r, yaml, fortran, bat, cobol, hcl, msdax, graphql, qsharp, objective-c, bicep, st, cpp, css, redis, javascript, julia, apex, dart, pug, markdown, flow9, sbcl, pascal, kotlin, c, csharp, pascaligo, scss, go, swift, proto, typescript, liquid, m3, razor, html, lexon, java, azcli, tcl, fsharp, ruby, vb, python, cameligo, ini, clojure, ada, elixir, restructuredtext, dockerfile, handlebars, racket, ecl, pla, perl, erlang, powerquery, verilog, d>" 
  }'

Custom

curl -L 'https://genai-code-buddy-api.stackspot.com/v1/knowledge-sources/<KS slug>/custom' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $JWT" \
  -d '{"content": "<content>"}'

Delete Knowledge Sources Objects

All files

If you want to delete all the Knowledge Source Objects, run on your terminal:

curl -s -X DELETE "https://genai-code-buddy-api.stackspot.com/v1/knowledge-sources/<KS slug>/objects" -H "Authorization: Bearer $JWT"

Standalone

If you want to delete only the standalone, you’ve manually added:

curl -s -X DELETE "https://genai-code-buddy-api.stackspot.com/v1/knowledge-sources/<KS slug>/objects?standalone=true" -H "Authorization: Bearer $JWT"

Only uploaded

To delete the zip files, run the following:

curl -s -X DELETE "https://genai-code-buddy-api.stackspot.com/v1/knowledge-sources/<KS slug>/objects?standalone=false" -H "Authorization: Bearer $JWT"