veza/docs/API_REFERENCE.md

# API Reference — Veza Backend

Base URL: `http://localhost:8080/api/v1` (or your `APP_DOMAIN`)

All responses use the format: `{ "success": true|false, "data": {...} }` or `{ "success": false, "error": "..." }`.

**Quick index:** [Auth](#authentication) | [Tracks](#tracks) | [Chat](#chat) | [Social](#social) | [Conversations](#conversations) | [Sessions](#sessions) | [Marketplace](#marketplace) | [Health](#health)

---

## Authentication

### POST /auth/register

Register a new user.

**Auth:** None

**Body:**
```json
{
  "username": "johndoe",
  "email": "john@example.com",
  "password": "SecureP@ssw0rd"
}
```

**Example:**
```bash
curl -X POST http://localhost:8080/api/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"username":"johndoe","email":"john@example.com","password":"SecureP@ssw0rd"}'
```

**Response (201):**
```json
{
  "success": true,
  "data": {
    "user": { "id": "uuid", "username": "johndoe", "email": "john@example.com" },
    "access_token": "eyJ...",
    "refresh_token": "eyJ...",
    "expires_in": 3600
  }
}
```

---

### POST /auth/login

Login with email and password.

**Auth:** None

**Body:**
```json
{
  "email": "john@example.com",
  "password": "SecureP@ssw0rd"
}
```

**Example:**
```bash
curl -X POST http://localhost:8080/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"john@example.com","password":"SecureP@ssw0rd"}'
```

**Response (200):**
```json
{
  "success": true,
  "data": {
    "access_token": "eyJ...",
    "refresh_token": "eyJ...",
    "expires_in": 3600,
    "user": { "id": "uuid", "username": "johndoe", "email": "john@example.com" }
  }
}
```

---

### POST /auth/refresh

Refresh access token using refresh token.

**Auth:** None (refresh token in body or cookie)

**Body:**
```json
{
  "refresh_token": "eyJ..."
}
```

**Example:**
```bash
curl -X POST http://localhost:8080/api/v1/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token":"eyJ..."}'
```

---

### POST /auth/logout

Logout and invalidate refresh token.

**Auth:** Bearer token (optional)

**Example:**
```bash
curl -X POST http://localhost:8080/api/v1/auth/logout \
  -H "Authorization: Bearer eyJ..."
```

---

## Marketplace

### GET /marketplace/products

List marketplace products (paginated).

**Auth:** None (public)

**Query params:** `limit`, `offset`, `search`, `sort`

**Example:**
```bash
curl "http://localhost:8080/api/v1/marketplace/products?limit=20&offset=0"
```

**Response (200):**
```json
{
  "success": true,
  "data": {
    "products": [...],
    "total": 42
  }
}
```

---

### GET /marketplace/products/:id

Get a single product by ID.

**Auth:** None (public)

**Example:**
```bash
curl http://localhost:8080/api/v1/marketplace/products/uuid-here
```

---

### POST /marketplace/orders

Create an order (checkout).

**Auth:** Bearer token (required)

**Body:** Cart items, payment method, etc.

**Example:**
```bash
curl -X POST http://localhost:8080/api/v1/marketplace/orders \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"items":[{"product_id":"uuid","quantity":1}],"payment_method":"card"}'
```

---

## Seller

### GET /sell/balance

Get seller balance (Stripe Connect).

**Auth:** Bearer token (required)

**Example:**
```bash
curl http://localhost:8080/api/v1/sell/balance \
  -H "Authorization: Bearer eyJ..."
```

**Response (200):**
```json
{
  "success": true,
  "data": {
    "connected": true,
    "available": 12500,
    "pending": 3200
  }
}
```

---

### GET /sell/transfers

List seller transfers (payout history).

**Auth:** Bearer token (required)

**Example:**
```bash
curl http://localhost:8080/api/v1/sell/transfers \
  -H "Authorization: Bearer eyJ..."
```

---

### POST /sell/connect/onboard

Get Stripe Connect onboarding URL.

**Auth:** Bearer token (required)

**Example:**
```bash
curl -X POST http://localhost:8080/api/v1/sell/connect/onboard \
  -H "Authorization: Bearer eyJ..."
```

**Response (200):**
```json
{
  "success": true,
  "data": {
    "onboarding_url": "https://connect.stripe.com/..."
  }
}
```

---

## Reviews

### GET /marketplace/products/:id/reviews

List reviews for a product (public).

**Auth:** None

**Query params:** `limit` (default 20), `offset` (default 0)

**Example:**
```bash
curl "http://localhost:8080/api/v1/marketplace/products/uuid/reviews?limit=10"
```

**Response (200):**
```json
{
  "success": true,
  "data": {
    "reviews": [
      {
        "id": "uuid",
        "product_id": "uuid",
        "buyer_id": "uuid",
        "order_id": "uuid",
        "rating": 5,
        "comment": "Great!",
        "created_at": "2026-02-23T12:00:00Z"
      }
    ]
  }
}
```

---

### POST /marketplace/products/:id/reviews

Create a review (buyer only, requires purchase).

**Auth:** Bearer token (required)

**Body:**
```json
{
  "rating": 5,
  "comment": "Amazing track!"
}
```

**Example:**
```bash
curl -X POST http://localhost:8080/api/v1/marketplace/products/uuid/reviews \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"rating":5,"comment":"Amazing track!"}'
```

**Response (201):**
```json
{
  "success": true,
  "data": {
    "id": "uuid",
    "product_id": "uuid",
    "buyer_id": "uuid",
    "order_id": "uuid",
    "rating": 5,
    "comment": "Amazing track!",
    "created_at": "2026-02-23T12:00:00Z"
  }
}
```

---

## Invoices

### GET /marketplace/orders/:id/invoice

Download invoice PDF for an order (buyer only).

**Auth:** Bearer token (required)

**Example:**
```bash
curl -o invoice.pdf http://localhost:8080/api/v1/marketplace/orders/uuid/invoice \
  -H "Authorization: Bearer eyJ..."
```

**Response:** PDF binary (`Content-Type: application/pdf`)

---

## Refunds

### POST /marketplace/orders/:id/refund

Request a refund (buyer or seller of products in order).

**Auth:** Bearer token (required)

**Body:**
```json
{
  "reason": "Not as described",
  "details": "optional details"
}
```

**Example:**
```bash
curl -X POST http://localhost:8080/api/v1/marketplace/orders/uuid/refund \
  -H "Authorization: Bearer eyJ..." \
  -H "Content-Type: application/json" \
  -d '{"reason":"Not as described"}'
```

**Response (200):**
```json
{
  "success": true,
  "data": {
    "message": "Refund initiated"
  }
}
```

---

## Admin

### GET /admin/transfers

List all platform transfers (admin only, paginated).

**Auth:** Bearer token (admin role required)

**Query params:** `status`, `seller_id`, `from`, `to`, `limit`, `offset`

**Example:**
```bash
curl "http://localhost:8080/api/v1/admin/transfers?status=failed&limit=50&offset=0" \
  -H "Authorization: Bearer eyJ..."
```

**Response (200):**
```json
{
  "success": true,
  "data": {
    "transfers": [
      {
        "id": "uuid",
        "seller_id": "uuid",
        "order_id": "uuid",
        "amount_cents": 2699,
        "platform_fee_cents": 300,
        "currency": "EUR",
        "status": "failed",
        "retry_count": 1,
        "next_retry_at": "2026-02-24T10:00:00Z",
        "created_at": "2026-02-23T12:00:00Z"
      }
    ],
    "total": 5
  }
}
```

---

### POST /admin/transfers/:id/retry

Manually retry a failed transfer (admin only).

**Auth:** Bearer token (admin role required)

**Example:**
```bash
curl -X POST http://localhost:8080/api/v1/admin/transfers/uuid-here/retry \
  -H "Authorization: Bearer eyJ..."
```

**Response (200):**
```json
{
  "success": true,
  "data": {
    "id": "uuid",
    "status": "completed",
    "retry_count": 2
  }
}
```

---

## Health

### GET /health

Simple health check (always returns OK).

**Auth:** None

**Example:**
```bash
curl http://localhost:8080/api/v1/health
```

**Response (200):**
```json
{
  "success": true,
  "data": { "status": "ok" }
}
```

---

### GET /health/deep

Deep health check (DB, Redis, S3, disk, config summary). v0.701

**Auth:** None

**Example:**
```bash
curl http://localhost:8080/api/v1/health/deep
```

**Response (200 healthy/degraded, 503 unhealthy):**
```json
{
  "success": true,
  "data": {
    "status": "healthy",
    "timestamp": "2026-02-23T12:00:00Z",
    "checks": {
      "database": { "status": "ok" },
      "redis": { "status": "ok" },
      "disk": { "status": "ok", "details": { "free_gb": 42.5 } }
    },
    "config": {
      "jwt_secret_set": true,
      "stripe_connect_enabled": true,
      "platform_fee_rate": 0.10,
      "transfer_retry_enabled": true
    }
  }
}
```

---

### GET /healthz

Liveness probe (Kubernetes).

**Auth:** None

---

### GET /readyz

Readiness probe (Kubernetes). Returns `ready`, `degraded`, or `not_ready`.

**Auth:** None

---

## Webhooks

### POST /webhooks/hyperswitch

Hyperswitch payment webhook (signature verification required).

**Auth:** Webhook secret (signature header)

**Example:**
```bash
curl -X POST http://localhost:8080/api/v1/webhooks/hyperswitch \
  -H "Content-Type: application/json" \
  -H "X-Hyperswitch-Signature: ..." \
  -d '{"event":"payment.succeeded",...}'
```

---

## Live Streaming

### GET /live/streams

List live streams (public). Optional `?is_live=true` filter.

**Auth:** None

### GET /live/streams/:id

Get stream details.

**Auth:** None

### POST /live/streams

Create a new stream (auth required). Body: `{ "title": "...", "description": "...", "category": "...", "tags": [] }`.

**Auth:** Bearer token

### GET /live/streams/me

List authenticated user's streams (includes stream_key). Auth required.

**Auth:** Bearer token

### GET /live/streams/me/key

Get user's stream key + RTMP URL. Creates draft stream if none exist. Auth required.

**Auth:** Bearer token

### POST /live/streams/me/key/regenerate

Regenerate stream key. Auth required.

**Auth:** Bearer token

### PUT /live/streams/:id

Update stream metadata (ownership check). Auth required.

**Auth:** Bearer token

---

## Cloud Storage (v0.802)

### GET /cloud/files/:id/versions

List version history for a file.

**Auth:** Bearer token (required)

**Response (200):**
```json
{
  "versions": [
    {
      "id": "uuid",
      "file_id": "uuid",
      "version": 2,
      "storage_key": "...",
      "size_bytes": 4500000,
      "created_at": "2026-02-10T08:00:00Z"
    }
  ]
}
```

### POST /cloud/files/:id/versions

Create a version snapshot of the current file.

**Auth:** Bearer token (required)

### POST /cloud/files/:id/restore/:version

Restore file to a previous version.

**Auth:** Bearer token (required)

### POST /cloud/files/:id/share

Create a share link. Body: `{ "permissions": "read", "expires_in_hours": 24 }`.

**Auth:** Bearer token (required)

**Response (200):**
```json
{
  "share_url": "https://.../api/v1/cloud/shared/TOKEN",
  "token": "TOKEN",
  "expires_at": "2026-02-26T12:00:00Z"
}
```

### GET /cloud/shared/:token

Get shared file metadata (public, no auth).

**Auth:** None

---

## Tags (v0.802)

### GET /tags/suggest

Tag autocomplete suggestions. Query: `?q=hip&limit=10`.

**Auth:** Bearer token (required)

**Response (200):**
```json
{
  "suggestions": ["hip-hop", "hiphop", "hipster"]
}
```

---

## Gear / Inventory (v0.802)

### POST /inventory/gear/:id/documents

Upload a document (invoice, manual, etc.). Multipart form: `file`, `type`.

**Auth:** Bearer token (required)

### GET /inventory/gear/:id/documents

List documents for a gear item.

**Auth:** Bearer token (required)

### DELETE /inventory/gear/:id/documents/:docId

Delete a document.

**Auth:** Bearer token (required)

### POST /inventory/gear/:id/repairs

Create a repair record. Body: `{ "repair_date": "2026-02-15", "description": "...", "cost_cents": 8500, "currency": "EUR", "provider": "..." }`.

**Auth:** Bearer token (required)

### GET /inventory/gear/:id/repairs

List repair history for a gear item.

**Auth:** Bearer token (required)

### DELETE /inventory/gear/:id/repairs/:repairId

Delete a repair record.

**Auth:** Bearer token (required)

---

## Users (v0.802)

### POST /users/me/export

Request GDPR data export. Returns 202 Accepted; export runs asynchronously. User receives a notification when ready with a presigned download URL.

**Auth:** Bearer token (required)

---

## Security & Compliance (v0.803)

### Audit Middleware

All POST, PUT, DELETE requests are automatically logged to the audit service (user, action, resource, IP). Skipped paths: `/health`, `/metrics`, `/swagger`, `/api/v1/admin`.

### CCPA / Sec-GPC

When the client sends `Sec-GPC: 1` (Global Privacy Control), the server sets `do_not_sell=true` in context and responds with `GPC: 1`.

### POST /users/me/privacy/opt-out

Set Do Not Sell preference (CCPA compliance).

**Auth:** Bearer token (required)

**Body:** `{ "do_not_sell": true }`

---

## Moderation (v0.803)

### GET /admin/reports

List reports (admin only). Query: `status` (pending|resolved|dismissed|all), `limit`, `offset`.

**Auth:** Bearer token + admin role

### POST /admin/reports/:id/resolve

Resolve a report. Body: `{ "action": "resolve"|"dismiss"|"ban"|"warn" }`.

**Auth:** Bearer token + admin role

### POST /reports

Create a report (authenticated user). Body: `{ "content_type": "user"|"track"|"comment", "content_id": "uuid", "reason": "..." }`.

**Auth:** Bearer token (required)

---

## Announcements (v0.803)

### GET /announcements/active

List active announcements (public). Used by AnnouncementBanner.

**Auth:** None

### GET /admin/announcements

List all announcements (admin).

**Auth:** Bearer token + admin role

### POST /admin/announcements

Create announcement. Body: `{ "title": "...", "content": "...", "type": "info"|"warning"|"error" }`.

**Auth:** Bearer token + admin role

### DELETE /admin/announcements/:id

Delete an announcement.

**Auth:** Bearer token + admin role

---

## Feature Flags (v0.803)

### GET /admin/feature-flags

List all feature flags (admin).

**Auth:** Bearer token + admin role

### PUT /admin/feature-flags/:name

Toggle a feature flag. Body: `{ "enabled": true|false }`.

**Auth:** Bearer token + admin role

---

## Maintenance Mode (v0.803)

### GET /admin/maintenance

Get current maintenance mode status.

**Auth:** Bearer token + admin role

### PUT /admin/maintenance

Enable or disable maintenance mode. Body: `{ "enabled": true|false }`. When enabled, non-admin routes return 503 except `/health`, `/api/v1/admin/*`.

**Auth:** Bearer token + admin role

---

## Legacy routes (deprecated)

The following routes are also available at the root (without `/api/v1` prefix) but are deprecated:

- `GET /health`, `GET /health/deep`, `GET /healthz`, `GET /readyz`
- `GET /metrics`

Use `/api/v1/...` for new integrations.

---

## Tracks (v0.931 cursor)

### GET /tracks

List tracks (paginated). Supports cursor-based pagination (v0.931).

**Auth:** None (public)

**Query params:** `limit`, `page` (legacy OFFSET), `cursor` (opaque base64, keyset on `created_at`+`id`), `genre`, `format`, `sort_by`, `sort_order`

**Example:**
```bash
curl "http://localhost:8080/api/v1/tracks?limit=20"
curl "http://localhost:8080/api/v1/tracks?cursor=eyJjcmVhdGVkX2F0Ijo...&limit=20"
```

**Response (200):** `{ "success": true, "data": { "tracks": [...], "next_cursor": "...", "has_more": true } }`

---

### GET /tracks/:id

Get a single track by ID.

**Auth:** None (public)

---

### GET /tracks/search

Search tracks. Query: `?q=...&limit=20`.

**Auth:** None

---

### POST /tracks (protected)

Upload a track. Requires Bearer token + content creator role.

---

### POST /tracks/:id/like, DELETE /tracks/:id/like

Like/unlike a track.

**Auth:** Bearer token (required)

---

### GET /tracks/:id/comments

List comments on a track.

**Auth:** None

---

### POST /tracks/:id/comments (protected)

Add a comment.

**Auth:** Bearer token (required)

---

## Chat

### GET /chat/token

Generate a short-lived JWT for WebSocket authentication. Used by the chat client to connect to the WebSocket endpoint.

**Auth:** Bearer token (required)

**Example:**
```bash
curl "http://localhost:8080/api/v1/chat/token" -H "Authorization: Bearer eyJ..."
```

**Response (200):** `{ "success": true, "data": { "token": "eyJ...", "expires_in": 300 } }`

---

## Social (v0.931 cursor)

### GET /social/feed

Global feed (cursor-based pagination). Auth optional (personalized when authenticated).

**Query params:** `limit`, `cursor` (base64: `created_at_unix_nano|uuid`)

**Auth:** None or Bearer (optional for personalization)

---

### GET /social/explore, GET /social/trending

Explore and trending posts.

**Auth:** None

---

### POST /social/posts, POST /social/like, POST /social/comments

Create post, toggle like, add comment.

**Auth:** Bearer token (required)

---

## Conversations (v0.931 cursor)

### GET /conversations

List user's rooms (conversations).

**Auth:** Bearer token (required)

---

### GET /conversations/:id/history

Message history for a room. Supports cursor-based pagination.

**Query params:** `limit`, `cursor`

**Auth:** Bearer token (required)

---

### POST /conversations, PUT /conversations/:id, DELETE /conversations/:id

Create, update, delete room.

**Auth:** Bearer token (required)

---

## Sessions

### GET /sessions

List active sessions for the current user.

**Auth:** Bearer token (required)

---

### POST /sessions/logout, POST /sessions/logout-all, POST /sessions/refresh

Logout (single, all), refresh session.

**Auth:** Bearer token (required)

---

## Status & System

### GET /status

Platform status (DB, Redis, Chat, Stream server connectivity).

**Auth:** None

---

### POST /validate

Validation endpoint (A01 rate limited). Body varies by validation type.

**Auth:** None

---

### GET /upload/limits, GET /upload/validate-type

Upload configuration and file type validation (public).

**Auth:** None

---

### GET /csrf-token

Get CSRF token for protected requests (optional auth).

**Auth:** None or Bearer (optional)