Docs

Getting started

Three steps to give your agent its first budget:

Get an API key — self-service: POST /v1/keys with your email issues a free-tier key (cndt_…, 100 calls/day, shown once). Keys are scoped to one owner account and can be revoked from the owner dashboard at any time.
Point your agent at the MCP endpoint — any MCP-compatible client works. The public server card lists the connector's capabilities and tool schemas in machine-readable form.
Set a spending policy — define quotas, per-call caps, and tool allowlists. Every call is checked against your key's policy before it runs.

Router trial — free models, your key

The conduit-router trial gives you 7 days of free model routing. No signup, no credit card. You bring your own free provider key; we provide the routing, policy checks, provenance, and audit.

1. Get a trial key

curl -X POST https://router.pipavia.com/v1/trial

Returns a key (your bearer token), valid 7 days, limited to free-tier models. Rate-limited to 5 keys per IP per day — abuse prevention, not a paywall.

2. Bring your provider key

Get a free key from Google AI Studio (takes 2 minutes, $0). Pass it per-request — we never store it on the trial tier:

curl -X POST https://router.pipavia.com/v1/route \
  -H "Authorization: Bearer YOUR_TRIAL_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [{"role": "user", "content": "Hello"}],
    "provider_keys": {"google": "YOUR_GOOGLE_AI_STUDIO_KEY"},
    "config": { ... signed config ... }
  }'

3. Free models

GET /v1/models lists the catalog. Trial keys route to free: true models only. Current free models: google:gemini-2.5-flash-lite, openai:gpt-5-mini.

Disclosure: Google's free tier may use prompts for training and human review. Don't send sensitive data through free-tier Google models.

What you get

Policy checks — quotas, tool allowlists, kill switch
Provenance — every response tells you what was requested vs. served; fallbacks are declared, never silent
Audit — HMAC-signed audit trail, viewable in the owner dashboard
Privacy — your provider key travels per-request over TLS, is never logged, never stored, never in audit records

Limits

Trial keys: free-tier models only, 7-day expiry
BYOK-only: we never pay for your inference and never resell provider access
Request/response only in v0.2.0 — streaming normalization is on the roadmap

Authentication

All API and MCP calls authenticate with a bearer API key (cndt_…) in the Authorization header. Keys are never placed in prompts or tool arguments — they travel in headers only, and every key carries an owner identity the policy engine checks.

Authorization: Bearer cndt_…

Spending-policy engine

The policy engine is Pipavia's core: it turns "my agent can spend" into a controlled, auditable act. Before any call runs, the engine checks your key's rules:

Quotas — daily limits on free keys, monthly limits on paid tiers.
Per-call caps — optional ceilings on what any single call may consume.
Tool allowlists — a key may only call the tools you approve.

If any rule fails, the call is denied and the agent receives a machine-readable reason (e.g. quota exceeded, tool not permitted for the key) so it can adapt instead of failing silently. Every decision — allowed or denied — lands in the audit trail, viewable in the owner dashboard.

Tool reference — Filings & Fundamentals

Our first connector exposes SEC EDGAR filings and normalized fundamentals — 24 tools as of v0.6.0. Representative tools (the full schema ships with the connector):

Tool	What it does
`search_filings`	Full-text search across 10-K / 10-Q / 8-K filings
`get_financial_statement`	Normalized income statement, balance sheet, cash flow
`get_financial_ratios`	Margins, returns, leverage, and liquidity ratios
`get_segment_data`	Segment-level revenue parsed from the 10-K XBRL instance
`get_peer_comparison`	Rank a company against all SEC filers on a metric
`compare_companies`	Side-by-side fundamentals for up to 5 tickers

Data freshness SLA

Contractual SLA: data is never more than 48 hours behind publication at the source (SEC EDGAR). The connector meets this with a two-tier cache:

Ticker maps — cached 7 days (they change rarely).
Submissions, company facts, XBRL concepts, frames — cached 24 hours.
Stale-while-revalidate — an expired entry is served immediately while a background refresh runs, so an SEC outage never fails your call; the response flags _meta.freshness.stale: true when this happens.

Every tool result carries _meta.freshness — cache (memory / r2 / miss / bypass), cached_at, and stale — so agents can see exactly how fresh their data is. Every tools/call counts as one call against your key's quota; paid tiers raise the quota — Pro $58/mo (100,000 calls/month), Team $198/mo (1,000,000 calls/month).

Settlement & receipts

Paid tiers are sold by 2351485 ALBERTA INC. (AIMLDS), the seller of record. Stripe processes payments and hosts the checkout; we never see or store your card. We never take custody of customer funds and operate no proprietary settlement.

Every settled purchase is recorded for your branded receipt: plan, amount, billing date, and subscription ID. Receipts appear after your first billed transaction is processed; for invoices and tax documents, see Stripe's receipt email.

Support

Free plan: community support. Pro and Team: email support with priority queueing for Team. Enterprise: dedicated support with custom SLAs. Contact [email protected].

Security scans are published, the changelog is public, and connector source is open-core (Apache-2.0).