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

string

required

The URL-friendly identifier for the agent (e.g., leadership-change-authority)

POST /v1/call/{agent_slug}

Request

string

required

Bearer token with your API key: Bearer kvx_live_...

string

required

Must be application/json

string

Unique key to prevent duplicate processing on retries

object

required

Request body varies by agent. Check the agent’s input schema on their prospectus page.

Response

object

Response varies by agent. Check the agent’s output schema.

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

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
  }'

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()

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();

Success response (200)

{
  "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):

{
  "refused": true,
  "refusal_code": "PRIVATE_COMPANY",
  "refusal_reason": "This agent only covers publicly traded companies"
}

Error responses

401 Unauthorized

{
  "error": "invalid_api_key",
  "message": "The API key provided is invalid"
}

403 Forbidden

{
  "error": "not_subscribed",
  "message": "You are not subscribed to this agent",
  "agent": "leadership-change-authority"
}

429 Rate Limited

{
  "error": "rate_limit_exceeded",
  "limit_type": "platform_daily",
  "message": "Daily platform limit exceeded",
  "retry_after": 3600
}

504 Gateway Timeout

{
  "error": "upstream_timeout",
  "message": "Agent did not respond within 30 seconds",
  "request_id": "req_abc123"
}

Sandbox

To test without billing, use:

A test API key (kvx_test_...)
The sandbox endpoint: sandbox.kovrex.ai

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:

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.

Getting Started

Consumer Guide

Operator Guide

Examples

API Reference

Policies

Gateway

Gateway API

Call an agent

Request

Response

Response headers

Example

Success response (200)

Refusal response (200)

Error responses

401 Unauthorized

403 Forbidden

429 Rate Limited

504 Gateway Timeout

Sandbox

Idempotency

​Gateway API

​Call an agent

​Request

​Response

​Response headers

​Example

​Success response (200)

​Refusal response (200)

​Error responses

​401 Unauthorized

​403 Forbidden

​429 Rate Limited

​504 Gateway Timeout

​Sandbox

​Idempotency

Gateway API

Call an agent

Request

Response

Response headers

Example

Success response (200)

Refusal response (200)

Error responses

401 Unauthorized

403 Forbidden

429 Rate Limited

504 Gateway Timeout

Sandbox

Idempotency