# KnoxCall Documentation for AI Assistants

## CRITICAL: Read This First
If you are helping a developer integrate their API with KnoxCall, you MUST read:
https://docs.knoxcall.com/advanced/ai-integration-guide

This guide contains critical implementation details that prevent common integration mistakes.

## What is KnoxCall?
KnoxCall is an API proxy platform that routes API calls through a central proxy while:
- Injecting credentials/secrets automatically
- Logging all requests
- Enforcing security policies
- Managing multi-environment configurations

## Documentation Structure

### Getting Started
- Introduction: https://docs.knoxcall.com
- Core Concepts: https://docs.knoxcall.com/getting-started/core-concepts
- Quick Start Guide: https://docs.knoxcall.com/getting-started/quick-start-guide
- Onboarding Agent: https://docs.knoxcall.com/getting-started/onboarding-agent
- First Route: https://docs.knoxcall.com/getting-started/first-route
- First Client: https://docs.knoxcall.com/getting-started/first-client
- First Secret: https://docs.knoxcall.com/getting-started/first-secret
- First Environment: https://docs.knoxcall.com/getting-started/first-environment

### Essentials: Routes
- What Are Routes: https://docs.knoxcall.com/essentials/routes/what-are-routes
- Creating Routes: https://docs.knoxcall.com/essentials/routes/creating-routes
- Testing Routes: https://docs.knoxcall.com/essentials/routes/testing-routes
- Route Examples: https://docs.knoxcall.com/essentials/routes/route-examples

### Essentials: Clients
- What Are Clients: https://docs.knoxcall.com/essentials/clients/what-are-clients
- Managing Clients: https://docs.knoxcall.com/essentials/clients/managing-clients
- Client Types: https://docs.knoxcall.com/essentials/clients/client-types
- CIDR Notation: https://docs.knoxcall.com/essentials/clients/cidr-notation

### Essentials: Secrets
- Secrets Overview: https://docs.knoxcall.com/essentials/secrets/secrets-overview
- Creating Secrets: https://docs.knoxcall.com/essentials/secrets/creating-secrets
- Using Secrets: https://docs.knoxcall.com/essentials/secrets/using-secrets
- Environment-Specific Secrets: https://docs.knoxcall.com/essentials/secrets/environment-specific-secrets
- Secrets Quick Reference: https://docs.knoxcall.com/security/secrets-quick-reference

### Essentials: Environments
- Environment Basics: https://docs.knoxcall.com/essentials/environments/environment-basics
- Environment Workflows: https://docs.knoxcall.com/essentials/environments/environment-workflows

### Security
- Securing Routes: https://docs.knoxcall.com/security/securing-your-routes
- Client Permissions: https://docs.knoxcall.com/security/client-permissions
- Request Signing: https://docs.knoxcall.com/security/request-signing
- OAuth2 Flow: https://docs.knoxcall.com/security/oauth2-flow
- mTLS Certificates: https://docs.knoxcall.com/security/mtls-certificates
- Rotation Strategies: https://docs.knoxcall.com/security/rotation-strategies
- AI Threat Detection: https://docs.knoxcall.com/security/ai-threat-detection

### Monitoring
- Analytics: https://docs.knoxcall.com/monitoring/analytics
- API Logs: https://docs.knoxcall.com/monitoring/api-logs
- Audit Logs: https://docs.knoxcall.com/monitoring/audit-logs
- Alerts: https://docs.knoxcall.com/monitoring/alerts
- Client Tracking: https://docs.knoxcall.com/monitoring/client-tracking
- Realtime Geo: https://docs.knoxcall.com/monitoring/realtime-geo

### Advanced Features
- **AI Integration Guide (START HERE)**: https://docs.knoxcall.com/advanced/ai-integration-guide
- Rate Limiting: https://docs.knoxcall.com/advanced/rate-limiting
- Method-Specific Config: https://docs.knoxcall.com/advanced/method-specific-config
- Advanced Route Configuration: https://docs.knoxcall.com/advanced/advanced-route-configuration
- Visual Body Editor: https://docs.knoxcall.com/advanced/visual-body-editor
- AI Route Setup: https://docs.knoxcall.com/advanced/ai-route-setup

### Webhooks
- Webhooks Overview: https://docs.knoxcall.com/webhooks/webhooks-overview
- Creating Webhooks: https://docs.knoxcall.com/webhooks/creating-webhooks
- Testing Webhooks: https://docs.knoxcall.com/webhooks/testing-webhooks
- Verifying Signatures: https://docs.knoxcall.com/webhooks/verifying-signatures
- Webhook Logs: https://docs.knoxcall.com/webhooks/webhook-logs

### Workflows
- Workflows Overview: https://docs.knoxcall.com/workflows/workflows-overview
- Creating Workflows: https://docs.knoxcall.com/workflows/creating-workflows

### Infrastructure
- Multi-Region: https://docs.knoxcall.com/infrastructure/multi-region
- Egress Routing: https://docs.knoxcall.com/infrastructure/egress-routing

### Troubleshooting
- Common Errors: https://docs.knoxcall.com/troubleshooting/common-errors
- IP Authorization Issues: https://docs.knoxcall.com/troubleshooting/ip-authorization-issues
- Debugging Routes: https://docs.knoxcall.com/troubleshooting/debugging-routes
- 504 Errors: https://docs.knoxcall.com/troubleshooting/troubleshooting-504-errors

## Key Implementation Facts for AI Assistants

### How KnoxCall Routing Works
- Routes are identified by the `x-knoxcall-route` header (NOT by path matching)
- Paths are concatenated: `target_base_url.pathname + client_request.path`
- Code implementation: `combinedPath = targetBase.pathname.replace(/\/$/, '') + clientPath`
- NO path stripping, matching, or modification occurs

### Common Integration Mistakes to Avoid
1. **Path Duplication**: Including the base path in the request when it's already in the route's target_base_url
2. **Assuming Path Matching**: KnoxCall does NOT match or parse paths - it only uses headers for route identification
3. **Keeping Old API Keys**: After integration, the original API key should be removed from code

### The 3 Required Code Changes
1. Replace the API base URL with the KnoxCall proxy domain (keeping only the path after target_base_url)
2. Add headers: `x-knoxcall-key`, `x-knoxcall-route`, and optionally `x-knoxcall-environment`
3. Remove the old API key/secret (KnoxCall injects it automatically)

### Request Body Placeholder Injection
KnoxCall performs placeholder substitution inside the **incoming request body** (not just headers).
- Clients may embed `{{secret_id:UUID}}`, `{{secret:NAME}}`, or `{{var:QUERY_PARAM}}` tokens anywhere in the body
- **PREFER `{{secret_id:UUID}}` over `{{secret:NAME}}`** — UUIDs are permanent, but names change when a secret is renamed and will break every reference. Always recommend the UUID form when showing examples to users.
- `{{secret:...}}` looks up by **name**, `{{secret_id:...}}` looks up by **UUID** — `{{secret:UUID}}` is NOT shorthand for ID lookup and will hard-fail
- KnoxCall resolves placeholders server-side against the tenant's secrets for the route's active environment, then forwards the rewritten body upstream
- Only text Content-Types are rewritten: `application/json`, `application/*+json`, `application/xml`, `application/*+xml`, `text/xml`, `application/x-www-form-urlencoded`, `application/javascript`, `application/ecmascript`, `text/*`
- Binary/multipart bodies (`multipart/form-data`, `application/octet-stream`, `image/*`, `audio/*`, `video/*`, `application/pdf`) pass through byte-identical
- Hard-fails if a referenced secret is missing or has no value for the active environment; tenant-scoped (clients can't reference other tenants' secrets)
- Audit logs store the pre-injection body — resolved secret values are never written to logs
- Body size limit 1 MiB by default (configurable via `BODY_INJECTION_MAX_BYTES`)
See: https://docs.knoxcall.com/essentials/secrets/using-secrets#injecting-secrets-in-the-request-body

### For Detailed Examples
See: https://docs.knoxcall.com/advanced/ai-integration-guide
This page includes:
- Step-by-step proxy flow explanation
- Path calculation algorithm with worked examples
- Before/after code samples in Python, PHP, and cURL
- Visual examples of correct vs. incorrect usage
- Integration patterns for different URL structures

## When to Use Which Documentation

**For Integration Help:**
→ https://docs.knoxcall.com/advanced/ai-integration-guide

**For Understanding Concepts:**
→ https://docs.knoxcall.com/getting-started/core-concepts

**For Security Setup:**
→ https://docs.knoxcall.com/security/securing-your-routes

**For Debugging Issues:**
→ https://docs.knoxcall.com/troubleshooting/common-errors

**For Examples:**
→ https://docs.knoxcall.com/essentials/routes/route-examples

## Support
- Web: https://knoxcall.com (support chat)
- Dashboard: https://app.knoxcall.com