Skip to main content

​
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

​
agent_slug
string
required
The URL-friendly identifier for the agent (e.g., leadership-change-authority)
POST /v1/call/{agent_slug}

​
Request

​
Authorization
string
required
Bearer token with your API key: Bearer kvx_live_...
​
Content-Type
string
required
Must be application/json
​
X-Idempotency-Key
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

HeaderDescription
X-Request-IdUnique identifier for this request
X-Latency-MsProcessing time in milliseconds
X-Agent-VersionVersion of the agent
X-RateLimit-Daily-RemainingCalls remaining today
X-RateLimit-Daily-ResetUnix timestamp when limit resets

​
Example

curl -X POST https://api.kovrex.ai/v1/call/leadership-change-authority \
  -H "Authorization: Bearer kvx_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "ticker": "MSFT",
    "lookback_days": 90
  }'

​
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:
  1. A test API key (kvx_test_...)
  2. 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://api.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.