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://genai-code-buddy-api.stackspot.com/v1/knowledge-sources" -H "Authorization: Bearer $JWT" -H 'Content-Type: application/json' -d '{"slug": "<KS identifier in API>", "name": "<display name>", "description": "<more details about KS>", "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 Knowledge Source Objects to an existing Knowledge Source

danger

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

caution

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

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.

Step 1. Run the following script to start the uploading process:

upload_data=$(curl -X POST 'https://genai-code-buddy-api.stackspot.com/v1/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. To check the upload status, run the command below:

curl --location 'https://genai-code-buddy-api.stackspot.com/v1/file-upload/@<file upload id>' \
--header 'Authorization: Bearer $JWT'

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

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

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"

Only files removed from previous zip upload

There is a flag while uploading a zip via API to your Knowledge Source that enables the cleanup of files that were removed from the archive.

Enabling the delete flag

When calling the endpoint, add the query param auto-delete with the value true.

curl -s -X POST "https://genai-code-buddy-api.stackspot.com/v1/knowledge-sources/<KS slug>/objects/batch?auto-delete=true" -H "Authorization: Bearer $JWT" -F 'objects_zip=@"<your zip file path>"'