Skip to main content

Upload Files to Contextualize Your Agent Requests

Agent Chat API

In StackSpot AI, you can upload files or images in the StackSpot AI chat to use in your interactions with Agents.

Portal

Step 1. In the StackSpot AI Portal, access the Chat;

Step 2. Click on the 'More Options' button and select Upload File;

Step 3. Choose the image or files you want to add;

Step 4. StackSpot AI will now have the context of the file you uploaded to use it in your chat.

IDE

Step 1. In the StackSpot AI IDE, access the Chat;

Step 2. Click on the 'More Options' button and select Upload File;

Step 3. Choose the image or files you want to add;

Step 4. StackSpot AI will now have the context of the file you uploaded to use it in your chat.

File Upload API (use with Agents API)

How to upload files

Prerequisites

You need to authenticate to use this feature. You have two options:

1. Authenticate with a Service Credential

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

info

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')
tip

To execute the request, add x-account-id to the headers.

Authenticate with Personal Access Token

If you have a Freemium account, use the following authentication method:

  1. In the StackSpot AI Portal, click your avatar and then select 'My Profile';
  2. In the Access Token section, click the 'Generate Client Key' button;
  3. Copy the Client Key.

For more details, see the Personal Access Token documentation.

How to call the API to upload a file

Example script:

file_paths=(
  "/path/to/file1.pdf"
  "/path/to/file2.pdf"
  "/path/to/file3.pdf"
)

upload_ids=()

for file in "${file_paths[@]}"; do
  upload_data=$(curl -s 'https://data-integration-api.stackspot.com/v2/file-upload/form' \
      -H 'Content-Type: application/json' \
      -H "Authorization: Bearer $JWT" \
      -d "{\"file_name\": \"$(basename "$file")\", \"target_type\": \"CONTEXT\", \"expiration\": 60 }")

  curl -s "$(jq -r '.url' <<< "$upload_data")" \
    -F "key=$(jq -r '.form.key' <<< "$upload_data")" \
    -F "x-amz-algorithm=$(jq -r '.form["x-amz-algorithm"]' <<< "$upload_data")" \
    -F "x-amz-credential=$(jq -r '.form["x-amz-credential"]' <<< "$upload_data")" \
    -F "x-amz-date=$(jq -r '.form["x-amz-date"]' <<< "$upload_data")" \
    -F "x-amz-security-token=$(jq -r '.form["x-amz-security-token"]' <<< "$upload_data")" \
    -F "policy=$(jq -r '.form.policy' <<< "$upload_data")" \
    -F "x-amz-signature=$(jq -r '.form["x-amz-signature"]' <<< "$upload_data")" \
    -F "file=@$file"

  upload_ids+=("$(jq -r '.id' <<< "$upload_data")")
done

Use this script to integrate the API wherever needed, such as within a GitHub Actions workflow, Postman, etc.

Example

Here is an example of integration through the terminal:

  1. Open the terminal and authenticate with JWT;
  2. Run the command:

echo $JWT

  1. Execute the script provided by StackSpot AI; this example includes two images.
# Authenticate
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')

# Upload files and keep their ids
file_paths=(
  '/home/user/Pictures/StackSpot.png'
  '/home/user/Pictures/StackSpot.jpg'
)

upload_ids=()

for file in "${file_paths[@]}"; do
  upload_data=$(curl -s 'https://data-integration-api.stackspot.com/v2/file-upload/form' \
      -H 'Content-Type: application/json' \
      -H "Authorization: Bearer $JWT" \
      -d "{\"file_name\": \"$(basename "$file")\", \"target_type\": \"CONTEXT\", \"expiration\": 60 }")

  curl -s "$(jq -r '.url' <<< "$upload_data")" \
    -F "key=$(jq -r '.form.key' <<< "$upload_data")" \
    -F "x-amz-algorithm=$(jq -r '.form["x-amz-algorithm"]' <<< "$upload_data")" \
    -F "x-amz-credential=$(jq -r '.form["x-amz-credential"]' <<< "$upload_data")" \
    -F "x-amz-date=$(jq -r '.form["x-amz-date"]' <<< "$upload_data")" \
    -F "x-amz-security-token=$(jq -r '.form["x-amz-security-token"]' <<< "$upload_data")" \
    -F "policy=$(jq -r '.form.policy' <<< "$upload_data")" \
    -F "x-amz-signature=$(jq -r '.form["x-amz-signature"]' <<< "$upload_data")" \
    -F "file=@$file"

  upload_ids+=("$(jq -r '.id' <<< "$upload_data")")
done

# Chat with this agent
curl 'https://genai-inference-app.stackspot.com/v1/agent/01JS0SSFDKPYXATPQ1J9RAW3B2/chat' \
  -H 'Content-Type: application/json' \
  -H "Authorization: Bearer $JWT" \
  -d "{
      \"streaming\": false,
      \"user_prompt\": \"What information is contained in these images?\",
      \"stackspot_knowledge\": false,
      \"return_ks_in_response\": true,
      \"upload_ids\": $(jq -c -n '$ARGS.positional' --args "${upload_ids[@]}")
  }"
  1. Execute the following command to store the IDs in the array:

echo $upload_ids

The response will include the IDs of the files or images:


> echo $upload_ids
01JFAKEIDEXAMPLE

> echo ${upload_ids[@]}
02XFAKEIDEXAMPLE 01XFAKEIDEXAMPLE
  1. Use these these returned IDs (upload_ids) to make API requests.