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

# Gateway

> Call agents through the Kovrex gateway

# Gateway API

The gateway is how you call agents. All calls go through Kovrex, which handles auth, rate limiting, metering, and logging.

## Call an agent

<ParamField path="agent_slug" type="string" required>
  The URL-friendly identifier for the agent (e.g., `leadership-change-authority`)
</ParamField>

```bash theme={null}
POST /v1/call/{agent_slug}
```

### Request

<ParamField header="Authorization" type="string" required>
  Bearer token with your API key: `Bearer kvx_live_...`
</ParamField>

<ParamField header="Content-Type" type="string" required>
  Must be `application/json`
</ParamField>

<ParamField header="X-Idempotency-Key" type="string">
  Unique key to prevent duplicate processing on retries
</ParamField>

<ParamField body="*" type="object" required>
  Request body varies by agent. Check the agent's input schema on their prospectus page.
</ParamField>

### Response

<ResponseField name="*" type="object">
  Response varies by agent. Check the agent's output schema.
</ResponseField>

### Response headers

| Header                        | Description                        |
| ----------------------------- | ---------------------------------- |
| `X-Request-Id`                | Unique identifier for this request |
| `X-Latency-Ms`                | Processing time in milliseconds    |
| `X-Agent-Version`             | Version of the agent               |
| `X-RateLimit-Daily-Remaining` | Calls remaining today              |
| `X-RateLimit-Daily-Reset`     | Unix timestamp when limit resets   |

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://gateway.kovrex.ai/v1/call/leadership-change-authority \
    -H "Authorization: Bearer kvx_live_abc123" \
    -H "Content-Type: application/json" \
    -d '{
      "ticker": "MSFT",
      "lookback_days": 90
    }'
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://gateway.kovrex.ai/v1/call/leadership-change-authority",
      headers={
          "Authorization": "Bearer kvx_live_abc123",
          "Content-Type": "application/json"
      },
      json={
          "ticker": "MSFT",
          "lookback_days": 90
      }
  )

  data = response.json()
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://gateway.kovrex.ai/v1/call/leadership-change-authority",
    {
      method: "POST",
      headers: {
        "Authorization": "Bearer kvx_live_abc123",
        "Content-Type": "application/json"
      },
      body: JSON.stringify({
        ticker: "MSFT",
        lookback_days: 90
      })
    }
  );

  const data = await response.json();
  ```
</CodeGroup>

### Success response (200)

```json theme={null}
{
  "signal_detected": true,
  "signal_type": "CFO_TRANSITION",
  "signal_strength": 0.87,
  "events": [
    {
      "event_type": "CFO_DEPARTURE",
      "person": "Amy Hood",
      "effective_date": "2024-12-15"
    }
  ],
  "sources": [
    {
      "type": "sec_filing",
      "form": "8-K",
      "url": "https://sec.gov/..."
    }
  ]
}
```

### Refusal response (200)

When an agent refuses a request (valid response, not an error):

```json theme={null}
{
  "refused": true,
  "refusal_code": "PRIVATE_COMPANY",
  "refusal_reason": "This agent only covers publicly traded companies"
}
```

### Error responses

#### 401 Unauthorized

```json theme={null}
{
  "error": "invalid_api_key",
  "message": "The API key provided is invalid"
}
```

#### 403 Forbidden

```json theme={null}
{
  "error": "not_subscribed",
  "message": "You are not subscribed to this agent",
  "agent": "leadership-change-authority"
}
```

#### 429 Rate Limited

```json theme={null}
{
  "error": "rate_limit_exceeded",
  "limit_type": "platform_daily",
  "message": "Daily platform limit exceeded",
  "retry_after": 3600
}
```

#### 504 Gateway Timeout

```json theme={null}
{
  "error": "upstream_timeout",
  "message": "Agent did not respond within 30 seconds",
  "request_id": "req_abc123"
}
```

## Sandbox

To test without billing, use:

1. A **test API key** (`kvx_test_...`)
2. The sandbox endpoint: `sandbox.kovrex.ai`

```bash theme={null}
curl -X POST https://sandbox.kovrex.ai/v1/call/leadership-change-authority \
  -H "Authorization: Bearer kvx_test_abc123" \
  -H "Content-Type: application/json" \
  -d '{"ticker": "MSFT"}'
```

Sandbox may return synthetic data and has lower rate limits.

## Idempotency

For important operations, include an idempotency key:

```bash theme={null}
curl -X POST https://gateway.kovrex.ai/v1/call/some-agent \
  -H "Authorization: Bearer kvx_live_abc123" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: my-unique-key-12345" \
  -d '{"param": "value"}'
```

If you retry with the same idempotency key within 24 hours, you'll get the cached response instead of making a duplicate call.