Getting Started

Upivia is a governance layer between AI agents and the outside world. Instead of giving your agent ten different API keys, you give it one Upivia API key — and every action flows through policy, budget, approval, and audit.

What is Upivia?

Introduction

Upivia is a governance layer between AI agents and the outside world. Instead of giving your agent ten different API keys, you give it one Upivia API key. Every action — email, search, LLM, code, calendar — flows through a single pipeline that checks policy, enforces budgets, requires approval when needed, and logs everything to an immutable audit trail.

Tutorial1 / 4
1
Agent
→
2
Service Request
→
3
Policy Check
→
4
Budget Check
→
5
Approval Gate
→
6
Provider Execution
→
7
Audit Log

Agent Sends Request

Your AI agent calls POST /api/v1/service-requests with its API key. One endpoint, one key.

The Pipeline

text
AI Agent
  │  Bearer agent_key_live_...
  ▼
POST /api/v1/service-requests
  │
  ├─ 1. Policy Check      — Does the agent have permission?
  ├─ 2. Budget Check       — Monthly cap? Daily limit? Balance?
  ├─ 3. Approval Gate      — Cost > threshold? Queue for review.
  ├─ 4. Provider Execution — Call the real service.
  ├─ 5. Balance Debit      — Deduct cost from org wallet.
  └─ 6. Audit Log          — Record everything (hash chained).
Agents never call external providers directly. No stolen API keys, no runaway spend, no mysteries.

Key Numbers

Service families20 (catalog shows only services whose providers are live)
API endpoints161
CLI commands17
Local file tools11
OpenRouter models300+
IntegrationsSlack + GitHub (OAuth), Discord + Telegram bots, Upivia Terminal devices
5 minutes to your first agent

Quickstart

1. Sign Up

Create an account at /signup. Every account gets a dedicated workspace with its own balance.

2. Top Up

Go to Money and add funds via Stripe. New accounts start with a free trial balance.

3. Create Agent

Visit /agents, click New agent, name it, copy the API key. Use test-mode keys (agent_key_test_) during development — no real money spent.

4. Enable Services

In the agent's Services tab, toggle on what you need. Set monthly budgets and daily limits.

5. Dispatch

bash
curl -X POST https://www.upivia.com/api/v1/service-requests \
  -H "Authorization: Bearer agent_key_live_..." \
  -H "Content-Type: application/json" \
  -H "idempotency-key: $(uuidgen)" \
  -d '{"service":"web_search","operation":"search","payload":{"query":"AI governance"}}'

SDK Quickstart

Prefer a typed client instead of raw curl? The published SDKs handle idempotency keys, retries, pagination, typed errors, and streaming chat.

bash
npm install @upivia/sdk     # TypeScript / Node
pip install upivia          # Python sync + async SDK

Machine-Readable Agent Docs

Agents with curl access can self-discover the platform from the public JSON spec:

bash
curl https://www.upivia.com/api/v1/agent-docs

CLI Quickstart

bash
pip install upivia-tui      # or: uv tool install upivia-tui
upivia init                  # authenticate with a PAT
upivia                       # launch the TUI
upivia --dir ~/project       # launch in a project dir
upivia --background          # headless device for the web app
Tutorial1 / 5
1
Visit /signup
2
Choose email or OAuth
3
Create workspace
4
Get trial balance

Sign Up

Create account at /signup via email or OAuth. Every account gets a dedicated workspace with its own balance.

Next chapterCore Concepts — Organizations, teams, agents, services, budgets, and permissions