SecureAI API Overview

SecureAI provides a REST API that gives you programmatic access to conversations, knowledge bases, assistants, models, and administrative functions. Whether you are automating workflows, building custom integrations, or embedding AI capabilities into your own applications, the API is the foundation.

This guide covers what the API can do, how it is organized, rate limits, error handling, and versioning. For authentication setup, see the API Authentication Guide. For embedding and integration patterns, see Embedding SecureAI in Your Applications.

Base URL

All API requests use your SecureAI instance's base URL:

https://your-secureai-instance.com/api/v1

Self-hosted deployments use whatever domain or IP address your instance is running on. If you are unsure, check with your administrator.

API Capabilities

The API is organized around resources. Each resource supports standard CRUD operations plus resource-specific actions.

Request Format

All requests use JSON for request and response bodies.

Required headers:

Authorization: Bearer <your-api-key>
Content-Type: application/json

Example -- list your conversations:

curl -X GET https://your-secureai-instance.com/api/v1/chats \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json"

Example -- send a message and get a completion:

curl -X POST https://your-secureai-instance.com/api/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [
      {"role": "system", "content": "You are a helpful automotive parts assistant."},
      {"role": "user", "content": "What brake pads fit a 2019 Honda Civic?"}
    ]
  }'

Response Format

Successful responses return a JSON object with the resource data. List endpoints return paginated results.

Single resource:

{
  "id": "chat-abc123",
  "title": "Brake pad compatibility",
  "created_at": "2026-03-15T10:30:00Z",
  "updated_at": "2026-03-15T10:35:00Z"
}

List response:

{
  "data": [
    { "id": "chat-abc123", "title": "Brake pad compatibility" },
    { "id": "chat-def456", "title": "OEM cross-reference" }
  ],
  "total": 42,
  "page": 1,
  "page_size": 20
}

Pagination

List endpoints accept page and page_size query parameters:

GET /api/v1/chats?page=2&page_size=50

• page defaults to 1.
• page_size defaults to 20. Maximum is 100.

Streaming Responses

The chat completions endpoint supports server-sent events (SSE) for streaming responses token by token. This is useful for building real-time chat interfaces.

To enable streaming, set "stream": true in your request:

curl -X POST https://your-secureai-instance.com/api/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [
      {"role": "user", "content": "Explain catalytic converter replacement."}
    ],
    "stream": true
  }'

Each event in the stream follows this format:

data: {"id":"resp-123","object":"chat.completion.chunk","choices":[{"delta":{"content":"A catalytic"}}]}

data: {"id":"resp-123","object":"chat.completion.chunk","choices":[{"delta":{"content":" converter"}}]}

data: [DONE]

The stream ends with data: [DONE].

Authentication

Every API request must include a valid authentication credential. SecureAI supports two methods:

For full details on generating keys, OAuth flows, token refresh, and security best practices, see the API Authentication Guide.

Rate Limits

SecureAI enforces rate limits to protect system stability and ensure fair usage across all users.

Default Limits

Chat completion requests (which consume AI model tokens) have separate, lower limits than metadata-only requests like listing chats or users.

Rate Limit Headers

Every API response includes headers that tell you your current rate limit status:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1711234567

Handling Rate Limits

When you exceed the limit, the API returns a 429 Too Many Requests response:

{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Retry after 23 seconds.",
    "retry_after": 23
  }
}

Best practices for handling rate limits:

• Check headers proactively. Monitor X-RateLimit-Remaining and slow down before hitting zero.
• Implement exponential backoff. On a 429 response, wait the retry_after duration, then retry with increasing delays (e.g., 1s, 2s, 4s).
• Queue requests. For batch operations, use a queue that respects your per-minute limit rather than firing all requests simultaneously.
• Cache responses. If you repeatedly fetch the same data (e.g., model list, assistant configurations), cache the result and use If-None-Match / ETag headers to avoid unnecessary requests.

Error Handling

The API uses standard HTTP status codes. Error responses include a JSON body with details.

Status Codes

Error Response Format

{
  "error": {
    "type": "validation_error",
    "message": "The 'model' field is required.",
    "details": {
      "field": "model",
      "constraint": "required"
    }
  }
}

Tips for debugging errors:

• Read the message field -- it usually tells you exactly what to fix.
• For 400 errors, check that your JSON is valid and all required fields are present.
• For 401 errors, verify your API key is correct and has not been revoked.
• For 403 errors, check that your user role has permission for the requested action. Some endpoints (user management, configs, audit logs) require admin privileges.

Versioning

The API is versioned via the URL path (/api/v1/). The current and only version is v1.

When breaking changes are introduced, a new version (e.g., /api/v2/) will be released. The previous version will remain available for a deprecation period of at least 6 months with advance notice.

Non-breaking changes (new fields in responses, new optional parameters, new endpoints) are added to the current version without a version bump.

Webhooks

SecureAI can send webhook notifications to your application when certain events occur. Webhooks are configured in Admin Panel > Settings > Webhooks.

Available Events

Webhook Payload

{
  "event": "document.indexed",
  "timestamp": "2026-03-15T10:35:00Z",
  "data": {
    "document_id": "doc-xyz789",
    "knowledge_base_id": "kb-abc123",
    "filename": "brake-pads-catalog-2026.pdf",
    "status": "indexed",
    "page_count": 47
  }
}

SecureAI signs webhook payloads with a shared secret so you can verify they are authentic. The signature is sent in the X-SecureAI-Signature header.

SDKs and Client Libraries

While the REST API works with any HTTP client, official and community SDKs simplify common operations:

Python example:

from secureai import SecureAIClient

client = SecureAIClient(
    base_url="https://your-secureai-instance.com",
    api_key="sk-your-api-key-here"
)

# Send a message
response = client.chat.completions.create(
    model="gpt-4",
    messages=[
        {"role": "user", "content": "What oil filter fits a 2020 Toyota Camry?"}
    ]
)

print(response.choices[0].message.content)

JavaScript example:

import { SecureAIClient } from "secureai-js";

const client = new SecureAIClient({
  baseUrl: "https://your-secureai-instance.com",
  apiKey: "sk-your-api-key-here",
});

const response = await client.chat.completions.create({
  model: "gpt-4",
  messages: [
    { role: "user", content: "What oil filter fits a 2020 Toyota Camry?" },
  ],
});

console.log(response.choices[0].message.content);

Common Integration Patterns

Parts Lookup Automation

Automate parts compatibility checks by sending structured queries:

curl -X POST https://your-secureai-instance.com/api/v1/chat/completions \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [
      {
        "role": "system",
        "content": "You are a parts compatibility expert. Return results as JSON with fields: part_number, manufacturer, compatible, notes."
      },
      {
        "role": "user",
        "content": "Is Bosch BP1087 compatible with a 2021 Ford F-150?"
      }
    ]
  }'

Knowledge Base Upload Pipeline

Automate document ingestion into a knowledge base:

# 1. Upload a document
curl -X POST https://your-secureai-instance.com/api/v1/knowledge/kb-abc123/documents \
  -H "Authorization: Bearer sk-your-api-key-here" \
  -F "file=@brake-catalog-2026.pdf"

# 2. Check indexing status
curl -X GET https://your-secureai-instance.com/api/v1/knowledge/kb-abc123/documents/doc-xyz789 \
  -H "Authorization: Bearer sk-your-api-key-here"

Batch Chat Export

Export all conversations for a date range for compliance or analytics:

curl -X GET "https://your-secureai-instance.com/api/v1/chats?created_after=2026-03-01&created_before=2026-03-15&page_size=100" \
  -H "Authorization: Bearer sk-your-api-key-here"

Next Steps

• API Authentication Guide -- Set up API keys or OAuth credentials.
• Embedding SecureAI in Your Applications -- Build chat widgets, custom tools, and automation pipelines.
• Understanding Token Usage and Costs -- Monitor API usage and optimize costs.
• Integration Overview -- See all available integrations and connection options.