API Reference
161 endpoints across 25 resource groups. All prefixed with /api/v1/. The machine-readable spec for agent self-discovery is at GET /api/v1/agent-docs (no auth required).
Overview
All endpoints are prefixed with /api/v1/. The machine-readable spec at GET /api/v1/agent-docs contains the full catalog with request shapes, pricing, and examples — paste it into any LLM and the agent can bootstrap itself.
Authentication
| Credential | Prefix | Use For |
|---|---|---|
| Agent API key | agent_key_live_ / agent_key_test_ | Agent identity. Dispatching service requests. Shown once. |
| Personal Access Token | upivia_pat_live_ | Managing agents, checking balances, CLI, MCP. Mint at /settings/tokens. |
| Cookie session | (browser) | Web UI authentication. Automatic with NextAuth.js. |
| Webhook signatures | HMAC / Ed25519 | Inbound: Stripe, Discord, Twilio, generic reconcile. |
bash
# Agent dispatching: Authorization: Bearer agent_key_live_xxxxxxxxxxxxxxxxx # You managing via PAT: Authorization: Bearer upivia_pat_live_xxxxxxxxxxxxxxxx
Agents API
| Endpoint | Description |
|---|---|
| GET /v1/agents | List agents in current org (excludes chat-owned) |
| POST /v1/agents | Create agent — returns plaintext API key once |
| GET /v1/agents/:id | Get agent details |
| PATCH /v1/agents/:id | Update name, description, status, icon, category, personality, voiceConfig |
| DELETE /v1/agents/:id | Delete agent (YUPI and chat agents protected) |
| PATCH /v1/agents/:id/key | Rotate API key — returns new key once |
| POST /v1/agents/:id/services | Enable a service with budget/limits |
| GET /v1/agents/:id/skills | List agent's workflow + service skills |
| POST /v1/agents/:id/clone | Clone agent with all bindings, new key |
| PATCH /v1/agents/:id/budget | Set agent-level monthly budget cap |
| POST /v1/agents/:id/publish | Request publication (team/org scope) |
| GET /v1/agents/:id/activity | Activity ledger: audit, delegations, service calls, memories |
| POST /v1/agents/spawn | Parent spawns child with bounded budget/services (max depth 3) |
| GET/POST /v1/agents/:id/memories | List/create governed memories with vector search |
| PATCH/DELETE /v1/agents/:id/memories/:id | Update/delete memories |
| GET /v1/agents/:id/memories/graph | Nodes + edges for 3D memory visualization |
| GET/POST /v1/agents/:id/conversations | Persistent agent conversations |
| GET/POST /v1/agents/:id/delegated-tasks | Delegation management |
| GET/POST/PATCH /v1/agents/:id/skill-proposals | Self-adjusting skill proposals |
Chat API
| Endpoint | Description |
|---|---|
| POST /v1/chat/turn | SSE-streamed chat turn. Supports force-approval, resume, local tool delegation. |
| GET /v1/chat/sessions | List chat sessions (filterable by agent_id) |
| POST /v1/chat/sessions | Create chat session bound to an agent |
| DELETE /v1/chat/sessions?session_id= | Close (soft-delete) a session |
| GET /v1/chat/sessions/:id | Full session with message history |
| POST /v1/chat/approvals/:id | Approve/reject chat tool calls mid-stream |
| GET /v1/chat/artifacts/:id | Download chat artifact (e.g., code output) |
SSE Events: status, tool_planned, tool_executing, tool_done/tool_pending, thinking (reasoning), message_delta (live text), local_tools_pending (batch for CLI), done.
Workflows API
| Endpoint | Description |
|---|---|
| GET/POST /v1/workflows | List/create workflows |
| GET/PATCH/DELETE /v1/workflows/:id | CRUD a single workflow |
| POST /v1/workflows/:id/versions | Create version with steps + edges |
| POST /v1/workflows/:id/runs | Execute a workflow |
| POST /v1/workflows/:id/versions/:versionId/publish | Request governance review |
| POST /v1/workflows/:id/agents | Grant workflow to agent (callable as run_workflow) |
| DELETE /v1/workflows/:id/agents?agent_id= | Revoke workflow from agent |
| POST /v1/workflows/:id/share | Set team/org visibility |
Step types (10): service_call, delegation, approval, condition, delay, webhook, memory_read, memory_write, agent_request, run_workflow. Template: ${input.key}, ${steps.StepLabel.output}.
Teams & Workspaces API
| Endpoint | Description |
|---|---|
| GET /v1/teams | List teams |
| POST /v1/teams/switch | Set active team |
| GET /v1/teams/:id/members | Team members with roles+budgets |
| PATCH /v1/teams/:id/members/:id | Set team member role |
| GET/POST /v1/teams/:id/budget | Get/allocate team pool |
| POST /v1/teams/:id/workers/:uid/budget/allocate | Allocate to worker |
| GET/POST /v1/workspaces | List/create workspaces |
| POST /v1/workspaces/switch | Switch active workspace |
| GET/POST/DELETE /v1/orgs/:id/invites | Manage invitations |
| POST /v1/invites/:token/accept | Accept invite (public, token IS auth) |
Service Requests API
POST /v1/service-requests
The single endpoint your agent calls for every paid action.
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 '{"operation":"text_generation.generate","payload":{"model":"openai/gpt-4o-mini","messages":[{"role":"user","content":"Summarize"}]}}'Response Statuses
| Status | Meaning |
|---|---|
| executed | Passed all checks. cost_cents debited. |
| blocked | Blocked by policy, budget, or balance. See reason_code. |
| approval_required | Cost exceeds threshold. Returns approval_id. |
| failed | Provider error. See result.detail. |
Always send an Idempotency-Key. Retries with same key return cached response — no double charges.
Other Endpoint Groups
| Group | Count | Key Endpoints |
|---|---|---|
| Approvals | 3 | GET /v1/approvals, POST approve, POST reject |
| Audit & Usage | 2 | GET /v1/audit-logs, GET /v1/usage |
| Scheduler | 6 | CRUD /v1/scheduled-tasks, GET runs, PATCH status |
| Publishing | 4 | GET /v1/publications, POST revoke, GET/PATCH publish-requests |
| Storage | 6 | CRUD /v1/storage/objects, presigned upload/download, restore |
| Webhooks | 4 | POST stripe, discord, twilio/voice-status, :provider/reconcile |
| Triggers | 6 | CRUD /v1/triggers (webhook HMAC fire, cron) |
| Knowledge | 7 | CRUD collections, ingest documents, chunk+embed, semantic query |
| Devices | 6 | POST heartbeat, GET sessions, queue commands, mark done |
| Connected Apps | 4 | OAuth install, list, refresh, revoke |
| Models | 4 | GET /v1/models/openrouter (300+, 1h cache), CRUD favorites |
| TTS | 2 | GET /v1/tts (Kokoro voices), POST /v1/tts (synthesize WAV) |
| Budget Requests | 3 | POST create, GET list, PATCH approve/reject |
| Personal Tokens | 4 | CRUD PATs (mint, list, toggle, revoke/delete) |
| Marketplace | 1 | GET /v1/marketplace/listings (cross-org scaffold) |
| Promo | 4 | POST redeem, GET/POST/DELETE admin promo codes |
| Agent Requests | 2 | POST create (agent → human), GET list |
| Balance | 2 | GET balance (org/team), POST top-up |
| Billing | 1 | POST /v1/billing/checkout-sessions (Stripe) |
Error Codes
| Status | Code | Meaning |
|---|---|---|
| blocked | policy_violation | Agent has no binding for this operation |
| blocked | monthly_budget_exceeded | Per-op monthly cap hit |
| blocked | daily_limit_exceeded | Per-op daily request count hit |
| blocked | insufficient_balance | Org wallet empty |
| approval_required | approval_threshold | Cost exceeds threshold; awaiting approval |
| failed | adapter_error | Upstream provider rejected |
| failed | agent_disabled | Agent status is paused or disabled |
| 401 | unauthorized | Missing/expired/revoked credential |
| 403 | forbidden | Lacks required permission |
| 404 | not_found | Resource doesn't exist or belongs to another org |
| 400 | invalid_request | Malformed request body |