# Assistiv Gateway

> Multi-tenant AI gateway. Gives your platform unified access to LLM providers, MCP tool integrations, agent-fetchable skills, paid real-world Capabilities, billing, end-user management, and real-time outbound webhooks through a single OpenAI-compatible API.

Assistiv provisions your platform and hands you a `sk-plat_*` key. You connect your own LLM provider keys (OpenAI, Anthropic, Google, xAI), create end users, top up your wallet, and call inference — your end users get their own `sk-eu_*` keys for runtime operations. MCP tool connections (GitHub, Slack, Zoho, Zendesk) let your AI agents call real tools with per-user OAuth authorization. **Skills (private beta)** let agents discover, fetch, and run code packages on demand — exposed as five MCP tools (`find_skill`, `fetch_skill`, `create_skill`, `delete_skill`, `submit_skill_review`) auto-registered when `platform.skills_enabled = true`. Budget operations (`/budget/topup`, `/budget/debit`, `PATCH /budget`) are strictly idempotent via `Idempotency-Key`, every state change lands in a full transaction ledger (`/budget/transactions`), and a user can be paused via `is_suspended` without losing state. Outbound webhooks push real-time events (`budget.topped_up`, `budget.low_balance`, `budget.suspended`, `budget.unsuspended`, `budget.debited`) via Svix — no polling required.

## Integration Guide (step-by-step)

Follow these in order. Each is a self-contained file with full API details.

1. [Setup & Hello World](https://www.assistiv.ai/docs/integration/step-1-setup-and-hello-world.txt) — Dashboard config, server-side setup, verify connection
2. [Provision End Users](https://www.assistiv.ai/docs/integration/step-2-provision-end-users.txt) — Create users, manage API keys, idempotent create, scope enforcement
3. [Budgets & Rate Limits](https://www.assistiv.ai/docs/integration/step-3-budgets-and-rate-limits.txt) — Per-user USD budgets, idempotent topup/debit, suspension, full ledger via /budget/transactions, wallet, rate-limit overrides. **Dual-ledger:** opt-in product-billing display ledger with per-call / per-tool / per-USD rules layered on top of the USD ledger (`/v1/platforms/{pid}/end-users/{euid}/wallet`)
4. [Inference](https://www.assistiv.ai/docs/integration/step-4-inference.txt) — Chat Completions, Responses API, Models, streaming, tool calling, 402 code branching (budget_suspended vs budget_exhausted vs wallet_insufficient)
5. [MCP Tools (Optional)](https://www.assistiv.ai/docs/integration/step-5-mcp-tools.txt) — OAuth flow, hosted execution, free tier
6. [Monitor & Operate](https://www.assistiv.ai/docs/integration/step-6-monitor-and-operate.txt) — Outbound webhooks via Svix, self-service, logs, ledger-based cost reconciliation
7. [Skills (Optional, private beta)](https://www.assistiv.ai/docs/integration/step-7-skills.txt) — Agent-fetchable code packages: REST endpoints, MCP tool auto-registration, two MCP URLs (`/mcp/skills` vs `/mcp`), 4-dim review system, free tier (5k calls/month)

## Full Reference

- [Integration Index + Examples](https://www.assistiv.ai/llms-full.txt) — Complete TS/Python examples, troubleshooting, key constraints

## API Reference (website docs)

- [End Users](https://www.assistiv.ai/docs/api-reference/end-users): Create users with external_id, auto-generated API keys, optional metadata, opening ledger row on auto-create
- [LLM Configurations](https://www.assistiv.ai/docs/api-reference/llm-configs): Connect OpenAI, Anthropic, Google, xAI provider keys (AES-256-GCM encrypted at rest)
- [Wallet](https://www.assistiv.ai/docs/api-reference/wallet): Platform USD balance, topup, transaction log, atomic debit on each inference call
- [Budgets](https://www.assistiv.ai/docs/api-reference/budgets): Per-user USD budgets, one_time/daily/monthly periods, auto-replenish, is_suspended flag, idempotent topup/debit, full transaction ledger
- [End-user wallet (display ledger)](https://www.assistiv.ai/docs/api-reference/end-user-wallet): Opt-in product-billing surface decoupled from USD. Platform admin configures rules engine on `platforms.settings.end_user_wallet` (per-call, per-tool, per-USD triggers, additive) + sets `max_display` per end user. Five admin endpoints (`GET/POST/topup/adjust/DELETE wallet`) with Idempotency-Key + audit ledger in `end_user_display_transactions`. End users read translated balance via `GET /v1/me/budget` (display-unit shape: `{unit, max, used, remaining}` — no USD leak). 402 fires on `display_exhausted` independently of `budget_exhausted`
- [Outbound Webhooks](https://www.assistiv.ai/docs/api-reference/webhook-endpoints): Register endpoints for budget events, event-type filters, Svix-backed delivery + replay portal
- [Chat Completions](https://www.assistiv.ai/docs/api-reference/chat-completions): OpenAI-compatible inference with streaming, tool calling, structured output
- [Models](https://www.assistiv.ai/docs/api-reference/models): List available models filtered by your platform's enabled provider configs
- [API Keys](https://www.assistiv.ai/docs/api-reference/api-keys): Create/revoke platform and end-user keys, key prefix visibility, immediate Redis invalidation
- [MCP / Tools](https://www.assistiv.ai/docs/api-reference/mcp): OAuth connect flow, list apps/connections, execute tools via JSON-RPC 2.0
- [Skills (private beta)](https://www.assistiv.ai/docs/api-reference/skills): Discover, fetch, and run agent-fetchable code packages. Five endpoints: search / fetch (returns full folder) / create (private upload) / delete / submit_skill_review (4-dim agent rating). Auto-registers five MCP tools (`find_skill`, `fetch_skill`, `create_skill`, `delete_skill`, `submit_skill_review`) when `platform.skills_enabled = true`. Two MCP URLs: `mcp.assistiv.ai/mcp/skills` returns only the five skill tools (clean tool list for skills-focused agents); `mcp.assistiv.ai/mcp` returns skills alongside any connected apps. See [Skills overview](https://www.assistiv.ai/docs/skills) for concepts (public catalog from admin-vetted GitHub repos, private uploads encrypted in GCS, content-sha dedupe, review-driven ranking) and [Skills MCP](https://www.assistiv.ai/docs/skills/mcp) for the agent-side curl quickstart and tool reference.
- [Capabilities](https://www.assistiv.ai/docs/api-reference/capabilities): Paid real-world API actions your end users' agents discover and run on demand (image generation, geolocation, scraping, data enrichment). Two levels — a Capability (category) and a Capability Provider (concrete endpoint, cheapest-first). Browse with any key (`GET /v1/capabilities`, `GET /v1/capabilities/{slug}`); discover + run with an `sk-eu_*` key (`POST /v1/capabilities/search` — no spend; `POST /v1/capabilities/run` — billed to the end-user budget, fresh-quoted, capped by policy `max_cost_per_call_usd` and optional `max_pay`). Enabled per-platform by Assistiv. See [Capabilities overview](https://www.assistiv.ai/docs/capabilities) for the model, enablement, billing, and policy/availability badges.
- [Platforms](https://www.assistiv.ai/docs/api-reference/platforms): Platform settings, team management, default budget config
- [Agents](https://www.assistiv.ai/docs/api-reference/agents): Agent execution via chat completions with tools (CRUD management coming soon)