senke/veza
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
veza/docs/API_REFERENCE.md
senke 7692c4b8b9 feat(v0.802): frontend Cloud/Gear, MSW, docs, scope v0.803, archive 
- Cloud: CloudFileVersions, CloudShareModal, versions/share in CloudView
- Gear: GearDocumentsTab, GearRepairsTab, warranty badge, initialTab
- MSW: cloud versions/share, gear documents/repairs, tags suggest
- Stories: CloudFileVersions, CloudShareModal, GearDetailModal variants
- gearService: listDocuments, uploadDocument, deleteDocument, listRepairs, createRepair, deleteRepair
- cloudService: listVersions, restoreVersion, shareFile, getSharedFile
- gear_warranty_notifier: 24h ticker, notifications for expiring warranty
- tag_handler_test: unit tests
- docs: API_REFERENCE, CHANGELOG, PROJECT_STATE, FEATURE_STATUS v0.802
- SCOPE_CONTROL, .cursorrules: scope v0.803
- archive: V0_802_RELEASE_SCOPE, RETROSPECTIVE_V0802
2026-02-25 14:00:58 +01:00

12 KiB
Raw Blame History

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": "..." }.

Authentication

POST /auth/register

Register a new user.

Auth: None

Body:

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

Example:

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):

{
  "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:

{
  "email": "john@example.com",
  "password": "SecureP@ssw0rd"
}

Example:

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):

{
  "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:

{
  "refresh_token": "eyJ..."
}

Example:

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:

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:

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

Response (200):

{
  "success": true,
  "data": {
    "products": [...],
    "total": 42
  }
}

GET /marketplace/products/:id

Get a single product by ID.

Auth: None (public)

Example:

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:

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:

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

Response (200):

{
  "success": true,
  "data": {
    "connected": true,
    "available": 12500,
    "pending": 3200
  }
}

GET /sell/transfers

List seller transfers (payout history).

Auth: Bearer token (required)

Example:

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:

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

Response (200):

{
  "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:

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

Response (200):

{
  "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:

{
  "rating": 5,
  "comment": "Amazing track!"
}

Example:

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):

{
  "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:

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:

{
  "reason": "Not as described",
  "details": "optional details"
}

Example:

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):

{
  "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:

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

Response (200):

{
  "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:

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

Response (200):

{
  "success": true,
  "data": {
    "id": "uuid",
    "status": "completed",
    "retry_count": 2
  }
}

Health

GET /health

Simple health check (always returns OK).

Auth: None

Example:

curl http://localhost:8080/api/v1/health

Response (200):

{
  "success": true,
  "data": { "status": "ok" }
}

GET /health/deep

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

Auth: None

Example:

curl http://localhost:8080/api/v1/health/deep

Response (200 healthy/degraded, 503 unhealthy):

{
  "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:

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):

{
  "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):

{
  "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):

{
  "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)

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.