> ## 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.

# API Overview

> Base URLs, authentication, and conventions

# API Overview

The Kovrex API lets you call agents and manage your account programmatically.

## Base URL

```
https://gateway.kovrex.ai
```

All endpoints use HTTPS. HTTP requests are rejected.

## Authentication

### API key (for gateway)

Use API keys to call agents:

```bash theme={null}
Authorization: Bearer kvx_live_your_key_here
```

Create API keys in your [dashboard](https://kovrex.ai/dashboard/settings).

### Session token (for dashboard APIs)

Dashboard APIs use session tokens from Supabase Auth. These are automatically handled if you're using our frontend.

## Request format

All requests should:

* Use `Content-Type: application/json`
* Send JSON in the request body (for POST/PATCH)
* Include authentication headers

```bash theme={null}
curl -X POST https://gateway.kovrex.ai/v1/call/agent-name \
  -H "Authorization: Bearer kvx_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"param": "value"}'
```

## Response format

All responses are JSON:

```json theme={null}
{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123"
  }
}
```

Error responses:

```json theme={null}
{
  "error": "error_code",
  "message": "Human readable message",
  "details": { ... }
}
```

## HTTP status codes

| Code  | Meaning                             |
| ----- | ----------------------------------- |
| `200` | Success                             |
| `201` | Created                             |
| `400` | Bad request (validation error)      |
| `401` | Unauthorized (invalid/missing auth) |
| `403` | Forbidden (not allowed)             |
| `404` | Not found                           |
| `429` | Rate limited                        |
| `500` | Server error                        |
| `502` | Bad gateway (upstream error)        |
| `504` | Gateway timeout                     |

## Rate limiting

See [Rate Limits](/consumer/rate-limits) for details.

Rate limit info is returned in headers:

```
X-RateLimit-Daily-Limit: 1000
X-RateLimit-Daily-Remaining: 847
X-RateLimit-Daily-Reset: 1704153600
```

## Pagination

List endpoints support pagination:

```
GET /api/agents?limit=20&offset=40
```

| Parameter | Default | Max |
| --------- | ------- | --- |
| `limit`   | 20      | 100 |
| `offset`  | 0       | —   |

Paginated responses include:

```json theme={null}
{
  "data": [...],
  "meta": {
    "total": 150,
    "limit": 20,
    "offset": 40
  }
}
```

## Versioning

The gateway uses versioned paths:

```
/v1/call/{agent}
```

Dashboard APIs are unversioned and may change. Use the gateway for production integrations.

## Environments

| Environment | Base URL            | Purpose      |
| ----------- | ------------------- | ------------ |
| Production  | `gateway.kovrex.ai` | Live traffic |
| Sandbox     | `sandbox.kovrex.ai` | Testing      |

Use test API keys (`kvx_test_*`) for sandbox.

## SDKs

Official SDKs coming soon. For now, use HTTP directly or your language's HTTP library.

### Python example

```python theme={null}
import requests

class KovrexClient:
    def __init__(self, api_key: str):
        self.api_key = api_key
        self.base_url = "https://gateway.kovrex.ai"
    
    def call(self, agent: str, payload: dict) -> dict:
        response = requests.post(
            f"{self.base_url}/v1/call/{agent}",
            headers={
                "Authorization": f"Bearer {self.api_key}",
                "Content-Type": "application/json"
            },
            json=payload
        )
        response.raise_for_status()
        return response.json()

# Usage
client = KovrexClient("kvx_live_your_key")
result = client.call("leadership-change-authority", {"ticker": "MSFT"})
```

### Node.js example

```javascript theme={null}
class KovrexClient {
  constructor(apiKey) {
    this.apiKey = apiKey;
    this.baseUrl = "https://gateway.kovrex.ai";
  }

  async call(agent, payload) {
    const response = await fetch(`${this.baseUrl}/v1/call/${agent}`, {
      method: "POST",
      headers: {
        "Authorization": `Bearer ${this.apiKey}`,
        "Content-Type": "application/json"
      },
      body: JSON.stringify(payload)
    });

    if (!response.ok) {
      throw new Error(`Kovrex error: ${response.status}`);
    }

    return response.json();
  }
}

// Usage
const client = new KovrexClient("kvx_live_your_key");
const result = await client.call("leadership-change-authority", { ticker: "MSFT" });
```

## Support

Having issues?

* Check the [status page](https://status.kovrex.ai)
* Email [support@kovrex.ai](mailto:support@kovrex.ai) with your `request_id`