API Reference

360+ REST endpoints. All served on a single port. OpenAPI 3.1 spec included.

Overview

All endpoints are served on the same port as the proxy. Full OpenAPI 3.1 spec available at /api/openapi.json.

Authentication

All API endpoints (except /health) require an Authorization header:

curl http://localhost:4200/api/status \
  -H "Authorization: Bearer sy_admin_your_key"

Admin endpoints require an admin key (sy_admin_ prefix). User endpoints accept user keys (sy_ prefix). The proxy endpoint (/v1/chat/completions) accepts both.

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit exceeded. Retry after 2s.",
    "status": 429
  }
}

Common error codes:

Pagination

List endpoints support limit and offset query parameters:

curl "http://localhost:4200/api/observe/traces?limit=20&offset=40" \
  -H "Authorization: Bearer sy_admin_..."

Responses include total and has_more fields for cursor-based pagination.

OpenAPI Spec

The full OpenAPI 3.1 specification is available at /api/openapi.json. Use it with Swagger UI, Postman, or any OpenAPI-compatible tool:

curl http://localhost:4200/api/openapi.json \
  -H "Authorization: Bearer sy_admin_..." | python3 -m json.tool

System

Chute — Proxy (12 endpoints)

The proxy is the core request pipeline. All /v1/* routes are OpenAI-compatible and pass through the full middleware chain.

Auth (20 endpoints)

User management, API key lifecycle, and BYOK provider key storage. The /me routes use API key auth; /users routes require admin.

Lookout — Observe (17 endpoints)

Traces, cost tracking, alerting, anomaly detection, and live streaming. Engine hooks automatically populate traces for every proxy request.

Brand — Trust (12 endpoints)

Immutable audit ledger with hash-chain verification, trust policies, evidence collection, and feedback loops for compliance and SOC 2 readiness.

Tack Room — Studio (17 endpoints)

Prompt versioning, A/B experiments, benchmark suites, and snapshots. Templates support Mustache variables and version history.

Forge (18 endpoints)

DAG workflow engine, tool registry, multi-turn sessions, and batch processing. Workflows define steps as nodes with dependencies.

Trading Post — Exchange (13 endpoints)

Config pack marketplace with versioning, environment sync, and one-click install. Packs bundle module configs, provider settings, and routing rules.

Configuration (5 endpoints)

Runtime configuration management with export/import and diff support.

Playground (2 endpoints)

Webhooks (6 endpoints)

Push notifications to external URLs on events like cost thresholds, safety blocks, provider health changes, and guardrail violations. Deliveries are logged and retried automatically.

Supported event types: webhook.test, alert.fired, cost.threshold, spend.cap_exceeded, provider.health_changed, guardrail.violation, trust.violation, upgrade.drover_cap_reached, upgrade.drover_savings_*, upgrade.feral_bypass_detected, upgrade.pii_detected, upgrade.trace_milestone_*, upgrade.error_rate_high. Use * to receive all events.

Guardrails (8 endpoints)

Runtime-configurable content guardrail rules. Rules are regex-based, scoped per-project, and support block/redact/warn/log actions. Cached in memory with 60-second TTL.

User Spend (4 endpoints)

Per-user spend tracking and caps. The /api/users/{id}/spend endpoint reads from the fast in-memory counter; history reads from daily rollups in the database.

Lasso — Request Replay (10 endpoints)

Re-run any traced request against a different model. Compare cost, latency, and output. Batch replay against up to 5 models in a single call. Share comparisons as public URLs. Requires Individual tier ($29.99/mo). Learn more →

# Replay a trace against Claude
curl -X POST /api/replay \
  -H "X-Admin-Key: $KEY" \
  -d '{"trace_id":"tr_5213e8a4...","target_model":"claude-sonnet-4-6"}'

# Batch: same prompt → 3 models
curl -X POST /api/replay/batch \
  -d '{"trace_id":"tr_5213...","target_models":["gpt-5.4","claude-sonnet-4-6","gpt-5.4-mini"]}'

# Compare results
curl /api/replay/compare/rpl_0ae37547...

# Share the comparison — returns stockyard.dev/compare/{id}
curl -X POST /api/lasso/share \
  -d '{"replay_id":"rpl_0ae37547..."}'
# → {"id":"a1b2c3d4e5f6","url":"/compare/a1b2c3d4e5f6","full_url":"https://stockyard.dev/compare/a1b2c3d4e5f6"}
    

Drover — Autopilot Routing (7 endpoints)

Calibrate models on real traffic, set a quality threshold, and Drover routes every request to the cheapest qualifying model. Three modes: cost, speed, balanced. Three trigger keywords: model=autopilot, model=auto, or the reference model name for transparent downgrade. Requires Pro tier ($99.99/mo). Learn more →

# Calibrate 3 models against real traffic
curl -X POST /api/autopilot/calibrate -H "X-Admin-Key: $KEY"

# Send a request with autopilot routing
curl /v1/chat/completions \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -d '{"model":"auto","messages":[{"role":"user","content":"hello"}]}'

# Check free-tier cap status and savings
curl /api/drover/cap
# → {"used_today":47,"limit":100,"remaining":53,"savings_today":3.20,"capped":false}

# Check what Drover chose and how much you saved
curl /api/autopilot/decisions?limit=5
    

Feral — Red-Team Testing (1 free + 12 paid endpoints)

Adversarial security testing for your LLM stack. The quickscan is free on all tiers. Full campaign management requires Team.

# Free quickscan — 5 probes, instant report card
curl -X POST /api/feral/quickscan \
  -H "Content-Type: application/json" \
  -d '{"api_key":"$OPENAI_API_KEY"}'
# → {"probes_run":5,"blocked":3,"bypassed":2,"grade":"C","score":"3/5",...}

# Full hunt — 29 probes with evolutionary mutation (Pro tier)
curl -X POST /api/feral/campaigns \
  -d '{"name":"audit-q1","target_url":"http://localhost:4200/v1/chat/completions"}'
curl -X POST /api/feral/campaigns/{id}/hunt \
  -d '{"api_key":"$OPENAI_API_KEY","generations":3}'
    

Optimize — The Full Loop (2 endpoints)

One endpoint that chains the entire Stockyard optimization loop: observe your traces → score model quality → analyze for cost waste, PII, and errors → recommend actions → optionally apply them → explain everything. This is the "make my stack better" button.

# Check optimization readiness
curl /api/optimize

# Run the full loop (analyze only)
curl -X POST /api/optimize
# → stages: observe → score → analyze → recommend
# → actions: [{enable_drover, priority:1}, {fix_pii, priority:2}, ...]
# → summary: {grade:"B", projected_savings:"$12.40/mo", actions:4}

# Run and auto-apply safe recommendations
curl -X POST /api/optimize -d '{"apply": true}'
# → applied: ["Drover autopilot enabled", "SecretScan module enabled"]
    

System (13 endpoints)

Health checks, license info, spending, upgrade triggers, insights, and cache management.

Common Examples

Quick reference for the most frequently used endpoints:

# Send a chat completion through the proxy
curl -X POST http://localhost:4200/v1/chat/completions \
  -H "Authorization: Bearer sy_your_key" \
  -H "Content-Type: application/json" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'

# Toggle a module on/off
curl -X PUT http://localhost:4200/api/proxy/modules/cachelayer \
  -H "Authorization: Bearer sy_admin_..." \
  -H "Content-Type: application/json" \
  -d '{"enabled": true}'

# Get cost breakdown for the last 7 days
curl "http://localhost:4200/api/observe/costs?days=7" \
  -H "Authorization: Bearer sy_admin_..."

# Create a trust policy
curl -X POST http://localhost:4200/api/trust/policies \
  -H "Authorization: Bearer sy_admin_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"no-pii","action":"block","rules":[{"field":"response.content","pattern":"\\d{3}-\\d{2}-\\d{4}"}]}'

# Create and run a workflow
curl -X POST http://localhost:4200/api/forge/workflows \
  -H "Authorization: Bearer sy_admin_..." \
  -H "Content-Type: application/json" \
  -d '{"name":"test","steps":[{"id":"s1","type":"llm","model":"gpt-4o","prompt":"Say hi"}]}'

# Export your entire config
curl http://localhost:4200/api/config/export \
  -H "Authorization: Bearer sy_admin_..." -o config.json

For the full OpenAPI specification, visit /api/openapi.json on your running instance.

Every endpoint returns JSON with consistent error formatting. See the error responses section above for the standard error schema.

Rate Limits

API management endpoints are rate-limited to prevent abuse. The proxy endpoint (/v1/chat/completions) uses the rateshield module for configurable per-key rate limiting. Management endpoints allow 120 requests per minute per admin key.

Rate-limited responses include Retry-After and X-RateLimit-Remaining headers.