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

• You need to authenticate to get to use the script.
• For Freemium accounts: Set up your Personal Access Token (PAT).
  • For Enterprise accounts: Choose between using Service Credentials or a PAT.

  Follow the steps to authenticate on the Services Credential page refer to the StackSpot EDP documentation. Contact your account administrator if you cannot create a Service Credential.

  • Enable the ai_dev and ai_admin permissions to create credentials;

tip

• 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.

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

• After you generate your token (PAT or Service Credential), you can reuse it whenever you need to perform integrations via API in StackSpot AI. There is no need to create a new token for each use.

• 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 this command to create a Knowledge Source (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. Open StackSpot AI Portal, go to ‘Knowledge Sources’, and confirm your KS appears in the list.

Upload files to an existing Knowledge Source

Maximum file size: 10 MB per file.

caution

Important: File Extensions

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.

• You can upload ZIP files, but only supported files inside the ZIP will be processed.

Follow the steps below to upload files to an existing Knowledge Source

danger

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:

Replace placeholders with your values.

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 }'

tip

Use split Strategy to divide the Knowledge Objects (KOs) 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 understand the split process better, use the StackSpot AI Portal to add the file to your Knowledge Source.

Step 3. Check the upload status:

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. Click ‘Knowledge Sources’ and then check if your Knowledge Source has new objects.

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

List all Knowledge Objects (KO)

You can list all Knowledge Objects to retrieve their content. Execute:

curl -s -X GET "https://data-integration-api.stackspot.com/v1/knowledge-sources/<KS slug>/objects" -H "Authorization: Bearer $JWT"

Delete Knowledge Objects

Delete a Knowledge Object by ID

If you want to delete a Knowledge Object by ID, run on your terminal:

curl -X 'DELETE' 'https://data-integration-api.stackspot.com/v1/knowledge-sources/<ks slug>/objects/<ko id>' -H "Authorization: Bearer $JWT"

Delete all Knowledge Objects

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

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

Delete only Standalone (manual) objects

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

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

Delete only uploaded files (zip, etc)

To delete the zip files, run the following:

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