# StackSpine — Complete Documentation

> Open-source (Apache 2.0) control plane and system of record for production AI. Enforce policy, budgets, and compliance guardrails across every AI provider, with a full audit trail.

---

## Quick Start

Get up and running with StackSpine in under 5 minutes.

### Step 1: Get your API key

Create an API key in the dashboard. Keys use the prefix `ss_live_` for production and `ss_test_` for development.

### Step 2: Install the SDK

```
npm install @stackspine/sdk
```

### Step 3: Make your first request

```javascript
import { StackSpine } from '@stackspine/sdk';

const client = new StackSpine({
  apiKey: process.env.STACKSPINE_API_KEY,
});

const response = await client.invoke('chat-support', [
  { role: 'user', content: 'Hello!' }
]);

console.log(response.content);
```

---

## API Reference

### Base URL

```
https://api.stackspine.com/v1
```

### Authentication

All API requests require an API key in the `x-api-key` header.

```
curl -X POST "https://api.stackspine.com/v1/invoke" \
  -H "x-api-key: ss_live_your_api_key_here" \
  -H "Content-Type: application/json"
```

- `ss_live_` — Production keys
- `ss_test_` — Development/Testing keys

### POST /invoke

Execute an AI inference request through the routing layer.

#### Request Body

| Parameter | Required | Description |
|-----------|----------|-------------|
| task_key | Yes | Task identifier |
| messages | Yes | Array of messages |
| max_tokens | No | Override max tokens |
| temperature | No | Override temperature |
| stream | No | Enable streaming (SSE) |

#### Response

```json
{
  "id": "call_7b8c9d0e-1234-5678-9abc-def012345678",
  "task": "chat-support",
  "model": "gpt-4-turbo",
  "provider": "OpenAI Production",
  "content": "Hello! How can I help you today?",
  "usage": {
    "input_tokens": 25,
    "output_tokens": 12,
    "total_tokens": 37
  },
  "cost_usd": 0.00111,
  "latency_ms": 850,
  "route_strategy": "primary"
}
```

### Rate Limits

| Scope | Limit | Window |
|-------|-------|--------|
| Per API Key | 60 requests | 1 minute |
| Per Client IP | 120 requests | 1 minute |

Dual-layer enforcement: both per-key and per-IP limits are checked simultaneously. If either is exceeded, the request returns 429.

#### Rate Limit Response Headers

| Header | Description |
|--------|-------------|
| X-RateLimit-Limit | Maximum requests allowed in current window |
| X-RateLimit-Remaining | Requests remaining in current window |
| X-RateLimit-Reset | Unix timestamp when the window resets |
| Retry-After | Seconds to wait before retrying (only on 429) |

The system is designed to fail-open: if the rate limit check is temporarily unavailable, requests are allowed through. Pro & Enterprise plans can request custom rate limits.

### Prompt Caching

StackSpine supports exact-match prompt caching to eliminate redundant provider calls.

- Enable in Settings → Data per organization
- Configurable TTL: 1 to 1,440 minutes (1 min to 24 hours)
- Cache keys derived from SHA-256 hash of the full request payload (task, messages, parameters)
- Streaming requests bypass the cache
- Cached responses return `X-Cache: HIT` header with `cost_usd: 0` and near-zero latency
- Cache misses return `X-Cache: MISS` header

### Fallback & Circuit Breaker

Three-layer routing strategy with automatic circuit breakers:

**Route Priority:**
1. Primary — Default route for all requests
2. Canary — Weighted percentage of traffic for A/B testing
3. Fallback — Used when primary/canary unavailable, ordered by weight

**Circuit Breaker States:**

| State | Behavior |
|-------|----------|
| Closed | Normal operation — requests flow to the provider |
| Open | Provider disabled — consecutive failures exceeded threshold. Requests skip to next route. |
| Half-Open | Cooldown expired — a test request is allowed. Success resets to Closed; failure reopens. |

Configuration per provider: failure threshold (consecutive failures before opening) and cooldown period (minutes before transitioning from Open to Half-Open).

**Request Flow:**
```
Request → Auth → Rate Limit Check
  → Cache Check (if enabled)
    → HIT: Return cached response
    → MISS: Route Selection
      → Primary route healthy? → Call provider
      → Primary circuit open? → Try canary/fallback
      → All routes exhausted? → Return 503
```

### Predictive Routing & Latency Optimization

StackSpine can automatically optimize traffic distribution across routes based on real-time performance.

- Routes are periodically re-scored using a composite of success rate, latency, and cost
- Higher-performing routes automatically receive a larger share of traffic
- Safety guardrails prevent drastic weight swings in any single optimization cycle
- Self-optimizing routing is opt-in per task — enable in the task's route settings
- Optimization history is visible in the Route Optimization Panel per task
- The `route_strategy` response field indicates how the route was selected (e.g. "optimized", "primary", "fallback")

### Regional Steering

StackSpine automatically detects the origin region of each request and routes to the nearest provider endpoint for lower latency.

| Region | Coverage |
|--------|----------|
| US | North & South America |
| EU | Europe, Middle East, Africa |
| APAC | Asia-Pacific, Oceania |

- Region is detected automatically from the request origin — no client-side configuration required
- Routes tagged with a region are preferred when the request origin matches
- Global (untagged) routes serve as fallback when no regional match exists
- The resolved region is returned in the response as `region` metadata

---

## SDK Documentation

Official SDKs for TypeScript, Python, Go, Ruby, and Rust — 5 languages with full feature parity.

### Installation

**TypeScript/JavaScript:**
```
npm install @stackspine/sdk
```

**Python:**
```
pip install stackspine
```

**Go:**
```
go get github.com/stackspine/go-sdk
```

**Ruby:**
```
gem install stackspine
```

**Rust:**
```
cargo add stackspine
```

### Basic Usage

**TypeScript:**
```typescript
import { StackSpine } from '@stackspine/sdk';

const client = new StackSpine({
  apiKey: process.env.STACKSPINE_API_KEY!,
});

const response = await client.invoke('chat-support', [
  { role: 'user', content: 'Hello!' }
]);

console.log(response.content);
console.log(`Cost: $${response.cost_usd}`);
```

**Python:**
```python
from stackspine import StackSpine

client = StackSpine(api_key=os.environ["STACKSPINE_API_KEY"])

resp = client.invoke(
    task="chat-support",
    messages=[{"role": "user", "content": "Hello!"}]
)

print(resp.content)
```

**Go:**
```go
client := stackspine.NewClient(os.Getenv("STACKSPINE_API_KEY"))

resp, err := client.Invoke("chat-support", []stackspine.Message{
    {Role: "user", Content: "Hello!"},
})
```

**Ruby:**
```ruby
client = StackSpine::Client.new(api_key: ENV["STACKSPINE_API_KEY"])

response = client.run("chat-support", {
  messages: [{ role: "user", content: "Hello!" }]
})
```

### Streaming

Stream responses in real-time for chat interfaces.

**TypeScript:**
```typescript
for await (const chunk of client.stream('chat-support', messages)) {
  process.stdout.write(chunk.content);
  if (chunk.done) {
    console.log('\n\nTokens:', chunk.usage?.total_tokens);
  }
}
```

**Python:**
```python
for chunk in client.stream("chat-support", messages):
    print(chunk.content, end="", flush=True)
    if chunk.done:
        print(f"\nTokens: {chunk.usage.total_tokens}")
```

### Error Handling

The SDK provides typed errors for precise error handling:

| Error Class | Status | When | Retryable |
|------------|--------|------|-----------|
| RateLimitError | 429 | Too many requests | Yes |
| BudgetExceededError | 402 | Monthly budget limit reached | No |
| AllProvidersFailedError | 503 | All routes exhausted | Yes |
| TimeoutError | 408 | Request exceeded timeout | Yes |
| AuthenticationError | 401 | Invalid or missing API key | No |

### Retry Strategy

SDK includes built-in exponential backoff:

| Attempt | Delay | Total Wait |
|---------|-------|------------|
| 1st retry | 1 second | 1s |
| 2nd retry | 2 seconds | 3s |
| 3rd retry | 4 seconds | 7s |

Configure retry behavior:
```typescript
const client = new StackSpine({
  apiKey: process.env.STACKSPINE_API_KEY!,
  maxRetries: 3,
  timeout: 30000,
});
```

---

## Webhooks

Receive real-time notifications when events occur in your organization.

### Supported Events

| Event | Description |
|-------|-------------|
| call.completed | AI request completed successfully |
| call.failed | AI request failed after all fallbacks |
| budget.threshold | Spend reaches alert threshold |
| budget.exceeded | Hard budget limit reached |
| provider.unhealthy | Provider health check failed |
| provider.recovered | Provider is healthy again |

### Payload Format

```json
{
  "id": "evt_abc123xyz",
  "event": "budget.threshold",
  "timestamp": "2026-02-03T12:00:00.000Z",
  "organization_id": "org_xyz789",
  "data": {
    "scope": "org",
    "current_spend_usd": 85.50,
    "limit_usd": 100.00,
    "threshold_percent": 80
  }
}
```

### Signature Verification

Always verify webhook signatures using HMAC-SHA256 with timing-safe comparison.

---

## Platform Overview

StackSpine is the open-source (Apache 2.0) control plane and system of record for production AI. It enforces policy, budgets, and compliance guardrails at the request edge, keeps a full audit trail, and routes across 10+ AI providers from a single governed entry point.

### Key Features

- **Governed Entry Point** — One OpenAI-compatible endpoint in front of every provider, so policy, budgets, and audit apply uniformly. No vendor lock-in.
- **Smart Routing** — Automatic failover, canary deployments, and weighted routing.
- **Cost Management** — Set budgets, get alerts, and track spend across all providers.
- **Health Monitoring** — Real-time provider health checks and automatic recovery.
- **5 SDK Languages** — Official SDKs for TypeScript, Python, Go, Ruby, and Rust.
- **Self-Host Option** — Deploy on your own infrastructure via Docker or Helm charts.
- **MCP Support** — Connect to external Model Context Protocol servers for tool discovery.
- **A/B Experiments** — Prompt and model A/B testing with traffic splitting and variant analytics.

### Supported AI Providers

OpenAI, Anthropic, Google AI, Lovable AI, DeepSeek, Mistral, Groq, Together AI, Fireworks, Perplexity, Custom HTTP.

---

## Core Concepts

### Organizations

Multi-tenant isolation for teams and companies. Each organization is an isolated workspace with its own providers, tasks, API keys, and team members. Plans: Free, Pro, Enterprise.

### Users & Roles

| Role | Providers | Tasks | API Keys | Team | Billing |
|------|-----------|-------|----------|------|---------|
| Owner | ✓ | ✓ | ✓ | ✓ | ✓ |
| Admin | ✓ | ✓ | ✓ | ✓ | — |
| Developer | ✓ | ✓ | ✓ | — | — |
| Viewer | Read | Read | — | — | — |

### Tasks & Routes

Tasks are reusable AI operations with configurable routing:

- **Primary** — Default route for all requests
- **Fallback** — Used when primary fails
- **Canary** — A/B testing with traffic split
- **Weighted** — Distribute by percentage

### Budget Rules

Control AI spending at organization and task levels with monthly limits, alert thresholds, and optional hard limits.

### Per-Organization Data Isolation

Every resource is scoped to a single organization via `org_id` columns and Row-Level Security (RLS) policies. Zero cross-tenant leakage.

---

## Security

### Authentication Methods

- Email & Password (12-character minimum with strength indicator)
- Social Login (Google, Apple)
- SSO/SAML + OIDC (Enterprise plan)
- API Keys (scoped, programmatic access)

### Multi-Factor Authentication (MFA)

TOTP-based verification using Google Authenticator, Authy, or 1Password. 10 one-time recovery codes generated on enrollment.

### Account Protection

- 30-minute lockout after 5 failed login attempts
- Email notifications for sign-ins from new devices
- Trusted device management
- Session viewing and revocation
- Leaked password detection

### API Key Security

- Keys shown only once at creation
- Only key prefix stored for identification
- Optional expiration dates
- Instant revocation

### Provider API Key Encryption

Provider credentials encrypted at rest using AES-256-GCM. Only backend functions with service role can decrypt at runtime. Plaintext never exposed in logs or API responses.

---

## SSO/SAML Setup (Enterprise)

### Prerequisites

- Enterprise Plan subscription
- Admin access to your StackSpine organization
- Administrator access to your Identity Provider
- Control over email domain(s) to configure

### Service Provider Information

- Entity ID: `https://api.stackspine.com/sso/metadata?org={your-org-slug}`
- ACS URL: `https://api.stackspine.com/sso/acs`
- NameID Format: `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`

### Supported Identity Providers

Okta, Azure AD (Entra ID), OneLogin, Google Workspace.

---

## Error Handling

### Error Types

| Error Class | Status | When | Retryable |
|------------|--------|------|-----------|
| RateLimitError | 429 | Too many requests | Yes |
| BudgetExceededError | 402 | Monthly budget limit reached | No |
| AllProvidersFailedError | 503 | All routes exhausted | Yes |
| TimeoutError | 408 | Request exceeded timeout | Yes |
| AuthenticationError | 401 | Invalid or missing API key | No |

### Retry Strategy

Built-in exponential backoff: 1s → 2s → 4s (3 attempts by default, configurable).

---

## User Guide

### 1. Getting Started

1. Navigate to the StackSpine landing page
2. Click "Get Started" or "Sign Up"
3. Enter your email and create a strong password (minimum 12 characters)
4. Check your inbox for a verification email
5. Click the verification link to confirm your account
6. Select your persona: Developer, CTO/Tech Lead, or Ops Engineer
7. Create your organization with a name and URL-friendly slug
8. Follow the interactive Quick Start wizard

### 2. Dashboard Overview

| Section | Description |
|---------|-------------|
| Home | Overview of calls, spend, and recent activity |
| Tasks | Manage reusable AI task configurations |
| Providers | Connect and monitor AI provider connections |
| Logs | View detailed API call history |
| Analytics | Visualize usage, costs, and performance |
| Budgets | Set spending limits and alerts |
| Settings | Configure account and organization |

### 3. Connecting AI Providers

1. Navigate to Providers in the sidebar
2. Click "Add Provider"
3. Select provider type
4. Enter a friendly name and your API key
5. Click "Save Provider"

### 4. Creating Tasks

1. Navigate to Tasks and click "Create Task"
2. Enter a Task Name and Task Key for API calls
3. Add an optional System Prompt
4. Click "Create Task"

### 5. Configuring Routes

| Strategy | Description |
|----------|-------------|
| Primary | Default route for all requests |
| Fallback | Used when primary fails (sequential by weight) |
| Canary | A/B testing with traffic percentage based on weight |

### 6. Generating API Keys

1. Go to Settings → API Keys
2. Click "Generate New Key"
3. Enter a descriptive name
4. Optionally set an expiration date
5. Copy and store immediately — shown only once

### 7-12. Monitoring, Budgets, Team, Security, Account

See the full User Guide at https://stackspine.com/docs?section=user-guide

---

## Who Uses StackSpine?

### Primary Users: Startup CTOs & Tech Leads

StackSpine is designed for tech-savvy startup founders and engineering leaders who are building AI-powered products but don't want the operational complexity of managing multiple AI vendor integrations.

### Core Use Cases

**1. Multi-Vendor AI API Management**
- Scenario: A SaaS startup uses GPT-4 for chatbot, Claude for document analysis, Gemini for summarization.
- Problem: Each provider has different SDKs, auth methods, rate limits, pricing. Managing 3+ integrations creates technical debt.
- Solution: Single `/invoke` API endpoint routing to 10+ providers (OpenAI, Anthropic, Google, DeepSeek, Mistral, Groq, Together, Fireworks, Perplexity).

**2. Cost Control & Budget Management**
- Scenario: Early-stage startup has $5,000/month AI budget with no visibility into token consumption.
- Problem: AI costs spiral unexpectedly; runaway loops or viral features exhaust budgets in hours.
- Solution: Real-time cost tracking per task, budget rules with alert thresholds (e.g., 80%), hard limits returning 402.

**3. Reliability Through Fallback Routing**
- Scenario: Customer support platform relies on Claude, but Anthropic has an outage during peak hours.
- Problem: Single-provider dependency means downtime = lost revenue.
- Solution: Primary → Claude 3 Opus, Fallback → GPT-4 Turbo (auto-switches), Canary → test new models at 10%.

**4. A/B Testing AI Models (Canary Deployments)**
- Scenario: Team wants to evaluate GPT-4.1 vs GPT-4 Turbo for code generation.
- Problem: No infrastructure to split traffic and compare results.
- Solution: Canary route with weighted distribution; analyze in Canary Analytics dashboard.

**5. Team Collaboration with Role-Based Access**
- Scenario: 15-person team needs different access levels (founders, devs, contractors).
- Problem: Sharing API keys is insecure; everyone has full access or none.
- Solution: Role hierarchy — Owner (billing, full control), Admin (team, providers, keys), Developer (tasks, routes), Viewer (read-only).

**6. Security & Compliance Monitoring**
- Scenario: Fintech startup needs audit trails and unauthorized access detection.
- Problem: No visibility into who accessed what, from where.
- Solution: Login location map, suspicious activity detection, MFA enforcement, trusted devices, audit logging.

**7. Provider Health Monitoring**
- Scenario: Ops team wants proactive alerts before customers notice provider degradation.
- Problem: Providers don't always communicate outages quickly.
- Solution: Automated health checks, consecutive failure tracking with auto-disable, Slack/Discord webhooks, health dashboard.

### Industry Examples

| Industry | Use Case |
|----------|----------|
| Customer Support | Route tickets through Claude for empathy, GPT for technical answers |
| Developer Tools | Code generation with fallback between multiple models |
| Content Platforms | Cost-optimized summarization at scale |
| Fintech | Compliant AI usage with full audit trails |
| Healthcare Tech | Secure, monitored AI integrations with MFA |
| E-commerce | Product description generation with budget caps |

### Why Not Just Use Provider SDKs Directly?

| Challenge | StackSpine Solution |
|-----------|---------------------|
| Managing 5+ different SDKs | Single unified API |
| No cost visibility | Real-time spend dashboards |
| Provider outages = downtime | Automatic fallback routing |
| Can't A/B test models easily | Canary deployments with analytics |
| Sharing keys is insecure | Role-based team access |
| No audit trail | Full security event logging |

StackSpine is the open-source control plane and system of record for production AI — the governed layer between your application and every AI provider, enforcing policy, budgets, and compliance with a full audit trail.

---

## API Status Codes

| Code | Meaning |
|------|---------|
| 200 | Success |
| 400 | Bad Request |
| 401 | Unauthorized |
| 402 | Budget Exceeded |
| 429 | Rate Limited |
| 503 | Provider Unavailable |