External API

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
Workflow Execution - Queue published workflows for background execution
Chat Streaming - Real-time AI conversations via SSE
Headless Agents - Blocking agentic task execution

API endpoints use the /external/* path. 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

For multitenant accounts, add the optional X-Tenant-ID header to select the tenant whose workflows, library, and data the request should use. The API key owner must have access to the selected tenant. The examples below include a tenant ID; omit that header if you do not need to select a tenant.

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

http://localhost:8000

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

Workflows (Background Execution)

The workflow endpoints let you find published workflows available to the API key owner, inspect their current input steps, queue a run, and check its progress. A queued workflow continues in the background after the trigger request returns.

Find a Workflow

GET /external/workflows Returns the latest published version of each workflow group the API key owner can access. Use group_id as the workflow path parameter in the active-workflow and run endpoints. The workflow_id in this response identifies a particular published version and is not used in those paths. Query parameters: page (default 1), page_size (default 20, maximum 100), and optional search (matches workflow title or description).

curl "${SBAI_BASE_URL}/external/workflows?page=1&page_size=20&search=intake" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" \
  -H "X-Tenant-ID: tenant-id"

Example response:

{
  "data": [
    {
      "group_id": "workflow-group-id",
      "workflow_id": "published-workflow-id",
      "title": "Customer Intake",
      "description": "Collect customer documents",
      "purpose_type": "public_data_collection",
      "version": 3,
      "first_step_id": "step-id",
      "updated_at": "2026-06-22T08:00:00"
    }
  ],
  "pagination": {
    "current_page": 1,
    "page_size": 20,
    "total_items": 1,
    "total_pages": 1
  }
}

Inspect Workflow Inputs

GET /external/workflows//active Returns the latest published workflow, including its steps and connectors. Use each step’s id or workflow_step_group_id as a key when sending form or file inputs. This lets integrations keep using the same step key when a workflow is republished with new version-specific step IDs.

curl "${SBAI_BASE_URL}/external/workflows/workflow-group-id/active" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" \
  -H "X-Tenant-ID: tenant-id"

Queue a Workflow Run

POST /external/workflows//runs Queues the latest published version for background execution. inputs is optional when the workflow does not need external form or file values.

Field	Type	Description
`run_id`	string, optional	Caller-provided run identifier. If omitted, the server generates one. Use the returned ID to check status.
`executor_timezone`	integer, optional	Executor timezone offset in minutes; defaults to `0`.
`external_user`	object, optional	Caller metadata (`id`, `email`, `name`). This is stored with the run and does not authenticate or impersonate a tenant user.
`inputs.form_inputs`	object, optional	Form values keyed by an active step ID or `workflow_step_group_id`. Values may be JSON objects, arrays, strings, numbers, or booleans.
`inputs.file_urls`	object, optional	File URLs keyed by an active step ID or `workflow_step_group_id`. Each value can be one URL, a list of URLs, or a map from input field names to URLs or URL lists.

File URLs must be reachable by the workflow runtime. Use signed URLs when the file source requires access credentials.

curl -X POST "${SBAI_BASE_URL}/external/workflows/workflow-group-id/runs" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" \
  -H "X-Tenant-ID: tenant-id" \
  -H "Content-Type: application/json" \
  -d '{
    "executor_timezone": 420,
    "external_user": {
      "id": "partner-user-123",
      "email": "user@example.com",
      "name": "Example User"
    },
    "inputs": {
      "form_inputs": {
        "stable-step-group-id": {
          "customer_name": "Example Corp",
          "request_type": "onboarding"
        }
      },
      "file_urls": {
        "file-step-group-id": [
          "https://files.example.com/customer-doc.pdf"
        ]
      }
    }
  }'

The response includes the generated or supplied run_id, the selected version-specific workflow_id, and the initial queue status:

{
  "data": {
    "run_id": "4d4c65cf-6b63-4d37-bb8e-99a090862012",
    "queue_id": "queue-id",
    "status": "queued",
    "queue_status": "pending",
    "group_id": "workflow-group-id",
    "workflow_id": "published-workflow-id",
    "current_step_id": "step-id",
    "external_user": {
      "id": "partner-user-123",
      "email": "user@example.com",
      "name": "Example User"
    }
  }
}

Check Run Status

GET /external/workflows/runs/ Poll this endpoint using the run_id returned by the trigger request. The response’s data.run contains the workflow run and step details; data.queue contains the latest queue item’s status. Requests must use the same API credentials and tenant selection as the trigger request.

curl "${SBAI_BASE_URL}/external/workflows/runs/4d4c65cf-6b63-4d37-bb8e-99a090862012" \
  -H "X-Client-ID: ${SBAI_CLIENT_ID}" \
  -H "X-API-Key: ${SBAI_API_KEY}" \
  -H "X-Secret: ${SBAI_SECRET}" \
  -H "X-Tenant-ID: tenant-id"

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

API Documentation

Endpoint Examples

Workflow Execution

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

Workflows (Background Execution)

Find a Workflow

Inspect Workflow Inputs

Queue a Workflow Run

Check Run Status

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

​Workflows (Background Execution)

​Find a Workflow

​Inspect Workflow Inputs

​Queue a Workflow Run

​Check Run Status

​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

Workflows (Background Execution)

Find a Workflow

Inspect Workflow Inputs

Queue a Workflow Run

Check Run Status

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