# Portalz Cloud — Full API Guide for LLMs

> Version: 1.0 | Last Updated: 2026-03-13
> Base URL: https://cloud.portalz.ai/api/cloud

## Authentication
All /api/ endpoints require authentication via one of:
- Bearer token: `Authorization: Bearer <jwt>`
- API key: validated through Portalz Brain

## Domain Endpoints

### Memory — AI Agent Memory Store
- POST /api/cloud/memory — Store a memory entry
- GET /api/cloud/memory — List memories (paginated)
- GET /api/cloud/memory/:id — Get memory by ID
- PUT /api/cloud/memory/:id — Update memory
- DELETE /api/cloud/memory/:id — Delete memory
- POST /api/cloud/memory/search — Semantic memory search
- POST /api/cloud/memory/sync — Sync memories across devices

### Costs — LLM Usage Tracking
- GET /api/cloud/costs — Get cost summary
- GET /api/cloud/costs/breakdown — Cost breakdown by model/provider
- POST /api/cloud/costs/budget — Set cost budget
- GET /api/cloud/costs/alerts — Get cost alerts
- POST /api/cloud/costs/routing — Configure model routing rules

### Vitality — Service Health
- GET /api/cloud/vitality — Service health overview
- GET /api/cloud/vitality/services — Individual service status
- POST /api/cloud/vitality/alerts — Configure health alerts
- GET /api/cloud/vitality/history — Health history timeline

### Test Results — Quality Metrics
- POST /api/cloud/test-results — Record test run results
- GET /api/cloud/test-results — List test runs (paginated)
- GET /api/cloud/test-results/coverage — Coverage reports
- GET /api/cloud/test-results/trends — Quality trend data

### Retention — Data Lifecycle
- GET /api/cloud/retention — Get retention policies
- PUT /api/cloud/retention — Update retention policies
- GET /api/cloud/retention/audit — GDPR audit log
- POST /api/cloud/retention/purge — Manual data purge

### Events — System Events
- GET /api/cloud/events — List system events (paginated)
- GET /api/cloud/events/stream — SSE event stream

## Response Format
All responses are JSON. Errors include `{ error: string, message?: string }`.

## Rate Limits
Default: 500 requests/minute per API key.
Memory sync: 10 requests/minute.
Headers: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.