docs/API.md
Rama main · réplica de lectura del repositorio original.
# API Reference
The full OpenAPI schema is served at `http://localhost:8000/docs` while the backend is
running (disabled when `ENVIRONMENT=production`). Every non-public endpoint requires JWT
authentication and carries an explicit rate limit; request and response bodies are
validated with Pydantic v2.
## Endpoints
```
# Health
GET /health # liveness
GET /health/ready # Postgres / Mongo / Qdrant / Redis probes
# 200/503 public; per-service detail
# only with X-Health-Token
# Authentication
POST /api/v1/auth/register # always 202; never reveals if the address exists
POST /api/v1/auth/login # returns access_token; sets the refresh cookie
POST /api/v1/auth/login/totp # second step when 2FA is enabled
POST /api/v1/auth/refresh # cookie-only, no body; rotates (reuse detection)
POST /api/v1/auth/logout # cookie-only, no body; revokes the family
POST /api/v1/auth/verify-email
POST /api/v1/auth/verify-email/code # 6-digit code path (needs a session)
POST /api/v1/auth/change-email # confirm a new address by link
POST /api/v1/auth/change-email/code # ...or by code (needs a session)
POST /api/v1/auth/resend-verification
POST /api/v1/auth/forgot-password
POST /api/v1/auth/reset-password
# User account (profile, sessions, 2FA, GDPR)
GET /api/v1/users/me
PATCH /api/v1/users/me # profile + model preferences
POST /api/v1/users/me/password
POST /api/v1/users/me/email # request an address change (re-verifies)
GET /api/v1/users/me/sessions
DELETE /api/v1/users/me/sessions/{family_id}
POST /api/v1/users/me/sessions/revoke-others
POST /api/v1/users/me/2fa/setup
POST /api/v1/users/me/2fa/enable
POST /api/v1/users/me/2fa/disable
GET /api/v1/users/me/export # downloadable JSON data export (Art. 20)
DELETE /api/v1/users/me # request account deletion (30-day grace)
POST /api/v1/users/me/deletion/cancel # cancel a pending deletion
# BYOK API key management
GET /api/v1/api-keys
POST /api/v1/api-keys
DELETE /api/v1/api-keys/{id}
# Agent management
GET /api/v1/agents
GET /api/v1/agents/tools # assignable tool catalog
POST /api/v1/agents
GET /api/v1/agents/{id}
PUT /api/v1/agents/{id}
PATCH /api/v1/agents/{id}/system-prompt
DELETE /api/v1/agents/{id}
# Agent skills (reusable instruction bundles)
GET /api/v1/skills
POST /api/v1/skills
GET /api/v1/skills/{id}
PATCH /api/v1/skills/{id} # a content change bumps `version`
DELETE /api/v1/skills/{id}
# Remote MCP servers
GET /api/v1/mcp-servers
POST /api/v1/mcp-servers
GET /api/v1/mcp-servers/{id} # includes the cached tool catalog
PATCH /api/v1/mcp-servers/{id} # changing `url` clears that cache
DELETE /api/v1/mcp-servers/{id}
POST /api/v1/mcp-servers/{id}/discover # handshake + refresh; outbound-probe limit
# Plugins (bundles of skills + MCP servers + agents)
GET /api/v1/plugins # catalog; never the author or manifest
POST /api/v1/plugins # publish; the security scan is never skipped
GET /api/v1/plugins/{id} # with the manifest, for the confirmation
POST /api/v1/plugins/{id}/install
POST /api/v1/plugins/import # own switch; outbound-probe limit
GET /api/v1/plugins/installed
POST /api/v1/plugins/installed/{id}/upgrade # ?dry_run=true previews the merge
GET /api/v1/plugins/installed/{id}/uninstall-preview
DELETE /api/v1/plugins/installed/{id}
# Task management
POST /api/v1/tasks
GET /api/v1/tasks # task history
GET /api/v1/tasks/{id}
GET /api/v1/tasks/{id}/trace # span waterfall (when tracing is enabled)
GET /api/v1/tasks/{id}/trace/summary
POST /api/v1/tasks/{id}/cancel
POST /api/v1/tasks/{id}/answer # human-in-the-loop answer
DELETE /api/v1/tasks/{id}
WS /api/v1/tasks/{id}/stream # live task stream
# Billing & subscriptions
GET /api/v1/billing/plans # plan list with prices and quotas
GET /api/v1/billing/plans/public # anonymous pricing for marketing pages
GET /api/v1/billing/subscription # plan, status + live quota usage
GET /api/v1/billing/payment-method # brand + last4 + expiry only
POST /api/v1/billing/subscribe # take card, charge first period, activate
POST /api/v1/billing/cancel # stop renewal (usable until period end)
# Documents (RAG)
POST /api/v1/documents
GET /api/v1/documents
DELETE /api/v1/documents/{id}
# Dashboard & metrics
GET /api/v1/dashboard/metrics
GET /api/v1/dashboard/token-usage
GET /api/v1/dashboard/cost-summary
GET /api/v1/dashboard/costs # trace-derived costs by day / model / domain
# Marketplace
GET /api/v1/marketplace # includes ratings + install trends
GET /api/v1/marketplace/showcase # anonymous landing showcase
GET /api/v1/marketplace/{id}
POST /api/v1/marketplace
POST /api/v1/marketplace/{id}/install
GET /api/v1/marketplace/{id}/reviews
POST /api/v1/marketplace/{id}/reviews # one review per user (upsert)
POST /api/v1/marketplace/{id}/report
POST /api/v1/marketplace/reviews/{review_id}/report
# Admin & moderation (role-gated)
GET /api/v1/admin/overview
GET /api/v1/admin/users # + /{id}, /{id}/suspend, /{id}/unsuspend, /{id}/role
GET /api/v1/admin/marketplace/items # + /{id}/status, /{id}/reviews, review hide
DELETE /api/v1/admin/agents/{id} # custom-agent takedown
GET /api/v1/admin/plugins
POST /api/v1/admin/plugins/{id}/status # delist; installed copies keep working
GET /api/v1/admin/reports # + /{id}/resolve
GET /api/v1/admin/audit
# Architect (live view)
WS /api/v1/architect/live
```
## Agent contracts
Layers exchange structured JSON, never free text.
Subagent output:
```json
{
"status": "success | error | needs_review",
"data": {},
"metadata": { "tokens_used": 0, "execution_time_ms": 0, "model_used": "string" }
}
```
Reviewer feedback:
```json
{ "approved": false, "issues": ["..."], "retry_hints": ["..."] }
```
## Database schemas
- **PostgreSQL** — relational data: `users`, `api_keys` (encrypted), `refresh_tokens`
(session families), `email_tokens`, `recovery_codes` (2FA), `subscriptions`,
`payment_methods` (brand + last4 + expiry only — raw PAN is never stored), the
append-only `usage_records` quota ledger, and the durable task engine tables
`task_runs` / `task_checkpoints` / `task_questions`.
- **MongoDB** — dynamic data: `agent_logs`, `marketplace_items` plus reviews, moderation
reports and the admin audit log, `task_sessions`, `agent_configurations`, `agent_skills`,
`mcp_servers` (encrypted credential + sanitized tool cache), `plugins` /
`plugin_installs`, `trace_spans` (TTL-bound).
- **Qdrant** — vector data: `conversation_memories`, `document_chunks`.
Memory and vectors are partitioned per user; data never crosses accounts.
See [`CLAUDE.md`](https://github.com/Yigtwxx/Maestro/blob/main/CLAUDE.md) §6 for column-level detail.