> ## Documentation Index
> Fetch the complete documentation index at: https://docs.knoxcall.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Set Up KnoxCall with Your AI Agent

> A step-by-step runbook your coding agent (Claude Code, Cursor, etc.) can follow to create a KnoxCall account and integrate your codebase — end to end, no browser required.

This page is written to be executed by an AI coding agent. If you're a human: paste the prompt below into your agent and it can do everything else. If you're an agent: follow the runbook top to bottom.

## For humans — the one-liner

Paste this into Claude Code (or any coding agent with shell access) from inside your project:

```text theme={"dark"}
Set up KnoxCall for this project. Follow the runbook at
https://docs.knoxcall.com/getting-started/ai-agent-onboarding — create an
account with my email <you@company.com>, proxy this project's outbound API
calls through KnoxCall in Test mode, and show me the verification steps.
```

Your agent will create a provisional account, build the whole integration against the isolated Test sandbox, and hand you exactly two things to do yourself: click the verification email, and approve the switch to Live mode.

## For agents — the runbook

<Steps>
  <Step title="Create the account (one HTTP call, no browser)">
    `POST https://api.knoxcall.com/v1/signup` is unauthenticated — it exists to mint your first credential.

    ```bash theme={"dark"}
    curl -X POST https://api.knoxcall.com/v1/signup \
      -H "Content-Type: application/json" \
      -d '{
        "email": "owner@company.com",
        "tenant_name": "Company Name",
        "country": "US"
      }'
    ```

    Notes:

    * Omit `tenant_slug` — the server derives an available one and returns it. Don't iterate on slug collisions yourself.
    * Rate limit: 3 signups per hour per IP. Do not retry a 4xx.
    * The response's `data.starter.api_key.api_key` is a **one-time plaintext test key**. Store it immediately (e.g. in the user's secret manager or an untracked `.env.local`) — it is never shown again.
    * The account is **provisional**: free plan, email unverified. A magic-link email has already been sent to the owner. You do not need to wait for it — everything below works now, in Test mode.
  </Step>

  <Step title="Verify the starter route works">
    The signup response includes `data.starter.curl` — a ready-to-run request against a seeded demo route (`getting-started`, proxying httpbin.org). Run it verbatim. A JSON echo response proves the proxy, your key, and the tenant are all live.
  </Step>

  <Step title="Discover what to proxy">
    Scan the project for outbound API calls and their credentials: HTTP client calls (fetch/axios/httpx/requests/Guzzle), base URLs in config, and API keys in `.env` files. Each distinct upstream API becomes one KnoxCall **route**; each credential becomes one **secret**.
  </Step>

  <Step title="Build the integration against the sandbox Management API">
    Your test key authenticates `https://sandbox.knoxcall.com/v1` (the Test-mode Management API). Full reference: [API Reference](/api-reference/overview), OpenAPI spec at `/api-reference/openapi.yaml`.

    For each upstream API:

    ```bash theme={"dark"}
    # 1. Create a secret for the credential
    curl -X POST https://sandbox.knoxcall.com/v1/secrets \
      -H "Authorization: Bearer $KNOXCALL_TEST_KEY" \
      -H "Content-Type: application/json" \
      -d '{"name": "stripe-api-key", "value": "sk_test_..."}'

    # 2. Create a route to the upstream, injecting the secret
    curl -X POST https://sandbox.knoxcall.com/v1/routes \
      -H "Authorization: Bearer $KNOXCALL_TEST_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "name": "stripe",
        "target_base_url": "https://api.stripe.com",
        "inject_headers": {"Authorization": "Bearer {{secret:stripe-api-key}}"}
      }'
    ```

    Prefer `{{secret_id:UUID}}` over `{{secret:NAME}}` in anything you persist — names break on rename, UUIDs don't.
  </Step>

  <Step title="Rewrite the application code">
    Exactly three changes per integration — see the [AI Integration Guide](/advanced/ai-integration-guide) for worked before/after examples and the path-concatenation rules:

    1. Replace the API base URL with `https://sandbox-{tenant_slug}.knoxcall.com/api` (Test) — the path after the upstream's base URL stays as-is.
    2. Add headers `x-knoxcall-key: <key>` and `x-knoxcall-route: <route name>`.
    3. Remove the old credential from the code and env files — KnoxCall injects it server-side now.

    Routes are identified by the `x-knoxcall-route` header, **not** by path matching. Paths concatenate: `target_base_url.pathname + request.path`. Do not duplicate the base path.
  </Step>

  <Step title="Test end-to-end, then hand off to the human">
    Run the project's test suite or exercise the changed call sites; check requests appear in the audit trail via `GET https://sandbox.knoxcall.com/v1/audit-logs`.

    Then tell the user, explicitly:

    1. **Click the verification link** KnoxCall emailed to them (unlocks the dashboard and Live mode).
    2. **Log in at [https://knoxcall.com](https://knoxcall.com)**, switch to Live mode, recreate the secrets with production credentials, and mint a Live API key from API Keys.
    3. Swap `sandbox-{slug}` → `{slug}` in the proxy host and the test key for the Live key — via the environment config, not a code change.

    Do not attempt to mint Live keys or move production credentials yourself unless the user explicitly asks.
  </Step>
</Steps>

## Contract summary for tools

| What                  | Value                                                                                                             |
| --------------------- | ----------------------------------------------------------------------------------------------------------------- |
| Signup                | `POST https://api.knoxcall.com/v1/signup` — unauthenticated, JSON `{email, tenant_name}` minimum                  |
| Test Management API   | `https://sandbox.knoxcall.com/v1` — auth `Bearer <test key>`                                                      |
| Live Management API   | `https://api.knoxcall.com/v1` — auth `Bearer <standard key>` (post-verification)                                  |
| Test proxy host       | `https://sandbox-{tenant_slug}.knoxcall.com/api/...`                                                              |
| Live proxy host       | `https://{tenant_slug}.knoxcall.com/api/...`                                                                      |
| Proxy headers         | `x-knoxcall-key`, `x-knoxcall-route`, optional `x-knoxcall-environment`                                           |
| SDKs                  | `npm i @knoxcall/sdk` (exports `signup()`), `pip install knoxcall` (exports `signup()`)                           |
| Machine-readable docs | [https://docs.knoxcall.com/llms.txt](https://docs.knoxcall.com/llms.txt) · OpenAPI: `/api-reference/openapi.yaml` |