Assistiv Docs

Assistiv Gateway

A multi-tenant AI gateway that gives your platform unified access to LLM providers, tool integrations, billing, and end-user management — through a single API.

ℹIntegrating with an AI agent?

If you're using Claude Code or another AI agent to implement this integration, point it to assistiv.ai/llms-full.txt — a single file with every endpoint, schema, and working code example. No navigation required.

Architecture

The gateway consists of two services:

Gateway API

Manages platforms, end users, API keys, billing, agents, MCP tool connections, and LLM provider configuration. This is the management plane.

https://api.assistiv.ai/v1/

Inference API

OpenAI-compatible endpoints for chat completions, responses, and model listing. Routes requests to the right provider with billing and budget enforcement.

https://api.assistiv.ai/v1/

Key Concepts

Platform

A tenant on the gateway. Each platform has its own API keys, end users, wallet, LLM configs, and MCP integrations. Platforms are fully isolated from each other.

End User

A user of your platform. Each end user gets their own API key, budget, and MCP tool connections. Identified by an external_id that you define (e.g. your user's ID).

API Keys

Two types: sk-plat_* for platform management and sk-eu_* for end-user operations. Keys are shown once on creation and stored as SHA-256 hashes.

LLM Configuration

Connect your own provider API keys (OpenAI, Anthropic, Google, xAI). The gateway routes inference requests to the right provider based on model and priority.

Billing

Two-level billing: a platform wallet (USD balance) and per-end-user budgets (token allocations). Both are checked before every inference request. Deductions are atomic with row-level locking.

MCP (Tools)

Connect third-party apps (GitHub, Slack, Zoho, Zendesk) via OAuth. End users authorize access and your AI agents can use these tools via the Model Context Protocol.

Agents

Define AI agents with specific LangGraph configurations and MCP tool access. Agents are scoped to a platform and can be assigned specific apps they're allowed to use.

Base URLs

bash
# All API endpoints (management + inference)
https://api.assistiv.ai/v1/

# MCP tool execution + OAuth flows
https://mcp.assistiv.ai/

Response Format

All Gateway API responses follow a consistent format:

Success

json
{
  "data": { ... }
}

Paginated

json
{
  "data": [ ... ],
  "total": 42,
  "page": 1,
  "limit": 20
}

Error

json
{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired API key"}
}

ℹError Codes

Standard error codes: bad_request (400), unauthorized (401), payment_required (402), forbidden (403), not_found (404), conflict (409), internal_error (500).

Next Steps