External API - Shieldbase AI Documentation

Overview

The Shieldbase External API provides a comprehensive set of endpoints for integrating AI capabilities into your applications. This API supports:

Models Management - List available AI models
File Upload & Indexing - Upload documents for semantic search
Library Management - Browse and manage uploaded files
Semantic Search - Hybrid BM25 + vector search across your content
Chat Streaming - Real-time AI conversations via SSE
Headless Agents - Blocking agentic task execution

All endpoints are mounted at /external-docs and require API key authentication. Interactive documentation is available at /external-docs/docs (Scalar UI).

Authentication

All API endpoints (except /external/keys/*) require three headers:

X-Client-ID: your-client-id
X-API-Key: your-api-key  
X-Secret: your-secret

Getting API Keys

Login to your Shieldbase account at https://app.sbai.cloud/
Navigate to Settings → API
Click “Generate” to create your API credentials
Save them securely - the API key is only shown once!

Keep your API credentials secure. Never commit them to version control or expose them in client-side code.

Base URLs

https://api.shieldbase.ai

Quick Start

1. Set Environment Variables

export SBAI_CLIENT_ID="sbai_client_xxx"
export SBAI_API_KEY="sbai_sk_xxx"
export SBAI_SECRET="sbai_secret_xxx"
export SBAI_BASE_URL="https://api.shieldbase.ai"

2. Test Connection

curl -X GET "${SBAI_BASE_URL}/external/models" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}"

Endpoints

Models

List Available Models

GET /external/models Returns all AI models available in the system with real-time availability status. Example Request:

curl -X GET "${SBAI_BASE_URL}/external/models" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}"

Example Response:

{
  "success": true,
  "data": [
    {
      "id": "gpt-5.1",
      "name": "GPT-5.1",
      "image": "openai-logo.png",
      "group_name": "OpenAI",
      "is_available": true
    },
    {
      "id": "gemini-2.5-pro",
      "name": "Gemini 2.5 Pro",
      "image": "google-logo.png",
      "group_name": "Google",
      "is_available": true
    }
  ]
}

Upload

Upload Files to Library

POST /external/upload Upload files asynchronously. Files are queued for indexing and become searchable once processing completes. Supported file types:
pdf, doc, docx, xls, xlsx, csv, json, txt, html, ppt, pptx, zip, md, sql, yml, yaml, png, jpg, jpeg, gif, webp Max file size: 1 GB per file Example Request:

curl -X POST "${SBAI_BASE_URL}/external/upload" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" \
  -F "files=@report.pdf" \
  -F "files=@data.csv" \
  -F "folder_paths=reports/2024"

Example Response:

{
  "message": "Uploaded content is being processed",
  "data": [
    {
      "id": "abc123",
      "file_name": "report.pdf",
      "state": "loading",
      "provider": "file"
    },
    {
      "id": "def456",
      "file_name": "data.csv",
      "state": "loading",
      "provider": "file"
    }
  ]
}

Libraries

List Library Files

GET /external/libraries Retrieve paginated list of library files with advanced filtering options. Query Parameters:

Parameter	Type	Default	Description
`page`	int	1	Page number (starts at 1)
`page_size`	int	40	Items per page (max 100)
`search`	string	-	Search by file name or folder path
`provider`	string	-	Filter by provider (e.g. `file`, `google_drive`)
`folder_paths`	string	-	Filter by folder path
`file_types`	string	-	Comma-separated file extensions (e.g. `pdf,docx`)
`sort_by`	string	-	Field to sort by (e.g. `created_at`, `file_name`)
`sort_order`	string	desc	Sort direction: `asc` or `desc`

Example Request:

curl -X GET "${SBAI_BASE_URL}/external/libraries?page=1&page_size=40&sort_order=desc" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}"

Example Response:

{
  "total_items": 120,
  "providers": { "file": 80, "google_drive": 40 },
  "page": 1,
  "page_size": 40,
  "total_pages": 3,
  "items": [
    {
      "id": "abc123",
      "file_name": "report.pdf",
      "provider": "file",
      "mime_type": "application/pdf",
      "state": "success",
      "download_link": "https://cdn.shieldbase.ai/...",
      "created_at": "2024-06-22T10:00:00",
      "folder_path": ["reports", "2024"],
      "is_shared": false
    }
  ]
}

Search

Semantic + Keyword Search

POST /external/search Combine keyword matching (BM25) with semantic similarity (vector search) for best results. Payload Fields:

Field	Type	Default	Description
`keyword` or `query`	string	required	Search query
`limit` or `top_k`	int	20	Max results (max 100)
`group_by_file`	bool	false	Merge chunks from same file
`types`	string[]	-	Filter by type: `file`, `workflow`, `conversation`
`use_bm25`	bool	true	Enable BM25 keyword search
`use_vector`	bool	true	Enable semantic vector search
`bm25_weight`	float	0.7	BM25 score weight (0–1)
`vector_weight`	float	0.3	Vector score weight (0–1)
`relative_threshold`	float	0.7	Min score as % of top result

Example Request:

curl -X POST "${SBAI_BASE_URL}/external/search" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "quarterly revenue",
    "limit": 40,
    "group_by_file": true
  }'

Advanced Search Example:

curl -X POST "${SBAI_BASE_URL}/external/search" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "quarterly revenue report",
    "top_k": 20,
    "types": ["file", "workflow"],
    "use_bm25": true,
    "use_vector": true,
    "bm25_weight": 0.7,
    "vector_weight": 0.3,
    "relative_threshold": 0.7,
    "group_by_file": true
  }'

Example Response:

{
  "success": true,
  "results": [
    {
      "id": "local-user##report.pdf",
      "title": "Q1 Revenue Report 2024.pdf",
      "content": "The quarterly revenue increased by...",
      "type": "library",
      "provider": "file",
      "score": 0.95
    }
  ]
}

Chat (Streaming)

Create New Conversation

POST /external/conversations Create a new conversation and receive real-time AI responses via SSE streaming. Payload Fields:

Field	Type	Default	Description
`content`	string	required	The user message
`model`	string	gpt-5.1	AI model ID (see `/external/models`)
`document_ids`	string[]	-	Library file IDs to include as context
`file_ids`	string[]	-	Uploaded file IDs (from `/external/upload`)
`user_timezone`	string	UTC	IANA timezone (e.g. `Asia/Jakarta`)
`quoted_text`	string	-	Text to quote/reply to
`additional_metadata`	object	-	Extended options (see below)

additional_metadata Options:

Field	Type	Default	Description
`web_search`	bool	true	Enable web search
`think`	bool	false	Extended thinking mode
`agentic_mode`	bool	false	Agentic multi-step mode
`agent_id`	string	-	Specific agent ID
`preferences`	object	-	`{language, output_style, tones, character}`
`side_by_side`	bool	false	Run two models in parallel
`models`	string[]	-	`[modelA, modelB]` for side-by-side

Example Request:

curl -N -X POST "${SBAI_BASE_URL}/external/conversations" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "What is machine learning?",
    "model": "gpt-5.1",
    "additional_metadata": {
      "web_search": true
    }
  }'

SSE Event Types:

Event	Payload	Notes
`stream_meta`	`{run_id, conversation_id}`	First event; persist `conversation_id`
`conversation_created`	`{conversation_id}`	New-conversation endpoint only
`message_start`	`{message_id, user_message_id}`	AI reply started
`content`	`{content: "…chunk…"}`	Stream text chunk
`thinking`	`{content: "…"}`	Extended-thinking mode only
`done`	`{conversation_id, message_id, …}`	Stream complete
`error`	`{content: "stream_error", error_id}`	Fatal error

Continue Existing Conversation

POST /external/conversations/ Send a follow-up message to an existing conversation and stream the AI reply. Example Request:

curl -N -X POST "${SBAI_BASE_URL}/external/conversations/{conversation_id}" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Can you explain that in more detail?",
    "model": "gpt-5.1"
  }'

Use the conversation_id from the conversation_created event to continue the thread.

Agents (Headless Execution)

Run Agentic Task

POST /external/agents/run Headless agentic execution - perfect for automation, scripts, and webhooks. Payload Fields:

Field	Type	Default	Description
`prompt`	string	required	The task / instruction to execute
`agent_id`	string	-	Specific agent ID to use
`model`	string	-	AI model override (see `/external/models`)
`document_ids`	string[]	-	Library file IDs to include as context
`file_ids`	string[]	-	Uploaded file IDs (from `/external/upload`)
`user_timezone`	string	UTC	IANA timezone
`timeout_seconds`	int	600	Max wait time (max 1800)
`additional_metadata`	object	-	Extra options passed through to the model

Example Request:

curl -X POST "${SBAI_BASE_URL}/external/agents/run" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Analyze the Q1 sales data and generate a summary report with charts",
    "document_ids": ["local-user##q1_sales.xlsx"],
    "timeout_seconds": 300
  }'

Example Response:

{
  "conversation_id": "8e5245f6-...",
  "output": "## Q1 Sales Summary\n\nKey highlights: ...",
  "generated_files": [
    {
      "url": "https://cdn.shieldbase.ai/...",
      "filename": "q1_summary.pdf",
      "size": 204800
    }
  ],
  "success": true,
  "error": null
}

When to use /external/agents/run vs /external/conversations:

	`/external/agents/run`	`/external/conversations`
Response	Blocking JSON	SSE stream
Best for	Headless automation, scripts, webhooks	Real-time UI, progress display
`generated_files`	Included directly in response	Requires fetching conversation after `done`

Timeout: Default 10 minutes, max 30 minutes. Returns HTTP 408 if exceeded.

Privacy & Data Redaction

Redacting Sensitive Information

To protect sensitive data in prompts and responses, you can enable automatic redaction of:

PII (Personally Identifiable Information): Names, emails, phone numbers, addresses
Financial Data: Credit card numbers, bank account numbers
Credentials: API keys, passwords, tokens
Custom Patterns: Define your own regex patterns for domain-specific data

Example configuration (backend):

# backend/sbai/config.py or environment variables
ENABLE_PII_REDACTION = True
REDACTION_PATTERNS = {
    "email": r"\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b",
    "phone": r"\b\d{3}[-.]?\d{3}[-.]?\d{4}\b",
    "credit_card": r"\b\d{4}[-\s]?\d{4}[-\s]?\d{4}[-\s]?\d{4}\b",
}

Example usage in API request:

curl -X POST "${SBAI_BASE_URL}/external/conversations" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Process this customer data: John Doe, john@example.com, 555-1234",
    "model": "gpt-5.1",
    "additional_metadata": {
      "redact_pii": true
    }
  }'

The system will automatically redact sensitive information:

Input: "John Doe, john@example.com, 555-1234"
Processed: "[REDACTED_NAME], [REDACTED_EMAIL], [REDACTED_PHONE]"

Rate Limits

100 requests per minute per API key

Rate limit headers are included in responses:

X-RateLimit-Limit: Total requests allowed per minute
X-RateLimit-Remaining: Requests remaining in current window
X-RateLimit-Reset: Unix timestamp when the limit resets

Error Handling

All errors follow this format:

{
  "error": "error_code",
  "message": "Human readable error message"
}

Common error codes:

Code	HTTP Status	Description
`invalid_credentials`	403	Invalid API credentials
`invalid_model`	400	Model not found
`not_found`	404	Resource not found
`rate_limit_exceeded`	429	Too many requests
`internal_error`	500	Server error

Testing Script

Save this as test-external-api.sh:

#!/bin/bash

# Configuration
export SBAI_CLIENT_ID="sbai_client_xxx"
export SBAI_API_KEY="sbai_sk_xxx"
export SBAI_SECRET="sbai_secret_xxx"
export SBAI_BASE_URL="http://localhost:8000"

echo "🧪 Testing Shieldbase External API"
echo "=================================="

# Test 1: List Models
echo -e "\n1️⃣  Testing GET /external/models"
curl -s -X GET "${SBAI_BASE_URL}/external/models" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" | jq '.'

# Test 2: Upload File
echo -e "\n2️⃣  Testing POST /external/upload"
echo "Sample content for testing" > test-file.txt
curl -s -X POST "${SBAI_BASE_URL}/external/upload" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" \
  -F "files=@test-file.txt" \
  -F "folder_paths=test" | jq '.'
rm test-file.txt

# Test 3: List Libraries
echo -e "\n3️⃣  Testing GET /external/libraries"
curl -s -X GET "${SBAI_BASE_URL}/external/libraries?page=1&page_size=10" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" | jq '.'

# Test 4: Search
echo -e "\n4️⃣  Testing POST /external/search"
curl -s -X POST "${SBAI_BASE_URL}/external/search" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "keyword": "test",
    "limit": 10,
    "group_by_file": true
  }' | jq '.'

# Test 5: Chat (New Conversation)
echo -e "\n5️⃣  Testing POST /external/conversations (SSE stream)"
curl -N -X POST "${SBAI_BASE_URL}/external/conversations" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Hello! What is 2+2?",
    "model": "gpt-5.1"
  }' 2>&1 | head -n 20

# Test 6: Agents Run
echo -e "\n6️⃣  Testing POST /external/agents/run"
curl -s -X POST "${SBAI_BASE_URL}/external/agents/run" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Calculate 5 + 3 and explain the result",
    "timeout_seconds": 60
  }' | jq '.'

echo -e "\n✅ All tests completed!"

Make it executable and run:

chmod +x test-external-api.sh
./test-external-api.sh

Additional Resources

Interactive API Docs - Explore the API with Scalar UI (dark mode, modern layout)
OpenAPI Spec - Download the OpenAPI specification
Support - Contact our support team
Status Page - Check API status and uptime

Coming Soon

Python SDK
JavaScript/TypeScript SDK
Go SDK
Webhook support for async notifications
GraphQL endpoint
Batch processing API

​Overview

​Authentication

​Getting API Keys

​Base URLs

​Quick Start

​1. Set Environment Variables

​2. Test Connection

​Endpoints

​Models

​List Available Models

​Upload

​Upload Files to Library

​Libraries

​List Library Files

​Search

​Semantic + Keyword Search

​Chat (Streaming)

​Create New Conversation

​Continue Existing Conversation

​Agents (Headless Execution)

​Run Agentic Task

​Privacy & Data Redaction

​Redacting Sensitive Information

​Rate Limits

​Error Handling

​Testing Script

​Additional Resources

​Coming Soon

Overview

Authentication

Getting API Keys

Base URLs

Quick Start

1. Set Environment Variables

2. Test Connection

Endpoints

Models

List Available Models

Upload

Upload Files to Library

Libraries

List Library Files

Search

Semantic + Keyword Search

Chat (Streaming)

Create New Conversation

Continue Existing Conversation

Agents (Headless Execution)

Run Agentic Task

Privacy & Data Redaction

Redacting Sensitive Information

Rate Limits

Error Handling

Testing Script

Additional Resources

Coming Soon