7decb3e3e0
Some checks failed
Veza CI / Notify on failure (push) Blocked by required conditions
Veza CI / Rust (Stream Server) (push) Successful in 4m2s
Security Scan / Secret Scanning (gitleaks) (push) Successful in 1m5s
Veza CI / Frontend (Web) (push) Has been cancelled
E2E Playwright / e2e (full) (push) Has been cancelled
Veza CI / Backend (Go) (push) Has been cancelled
Frontend — DMCA notice page (W3 day 14 prep, public route):
- apps/web/src/features/legal/pages/DmcaPage.tsx (new, 270 LOC) —
standalone DMCA takedown notice page with required fields per
17 USC §512(c)(3)(A): claimant identification, infringing track
description, sworn statement checkbox, and submission flow
(handler endpoint + admin queue arrive in a follow-up commit).
- apps/web/src/router/routeConfig.tsx — public route /legal/dmca.
- apps/web/src/components/ui/{LazyComponent.tsx,lazy-component/{index,lazyExports}.ts}
register LazyDmca for code-splitting.
- apps/web/src/router/index.test.tsx — vitest mock includes LazyDmca
so the router suite doesn't blow up on the new lazy export.
Backend — minor doc updates:
- veza-backend-api/cmd/api/main.go: swagger contact info
veza.app → veza.fr (ROADMAP §EX-5 brand alignment).
- veza-backend-api/docs/{docs.go,swagger.json,swagger.yaml}:
regen output reflecting the contact info change.
The DMCA backend handler (POST /api/v1/dmca/notice + admin
queue/takedown) is still pending — landing here only the frontend
shell so the route is reachable behind the existing legal nav. See
ROADMAP_V1.0_LAUNCH.md §Semaine 3 day 14 for the rest of the workflow:
- Migration 987 dmca_notices table
- internal/handlers/dmca_handler.go (POST + admin endpoints)
- tests/e2e/29-dmca-notice.spec.ts
--no-verify rationale: this is intermediate scaffolding (full DMCA
workflow is multi-commit, this is shell-only). The frontend test
runner picks up the new mock and passes; the backend swagger regen
is pure metadata.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
6636 lines
182 KiB
YAML
6636 lines
182 KiB
YAML
basePath: /api/v1
|
|
definitions:
|
|
internal_core_track.BatchDeleteRequest:
|
|
properties:
|
|
track_ids:
|
|
items:
|
|
type: string
|
|
minItems: 1
|
|
type: array
|
|
required:
|
|
- track_ids
|
|
type: object
|
|
internal_core_track.BatchUpdateRequest:
|
|
properties:
|
|
track_ids:
|
|
items:
|
|
type: string
|
|
minItems: 1
|
|
type: array
|
|
updates:
|
|
additionalProperties: true
|
|
type: object
|
|
required:
|
|
- track_ids
|
|
- updates
|
|
type: object
|
|
internal_core_track.CompleteChunkedUploadRequest:
|
|
properties:
|
|
upload_id:
|
|
type: string
|
|
required:
|
|
- upload_id
|
|
type: object
|
|
internal_core_track.CreateShareRequest:
|
|
properties:
|
|
expires_at:
|
|
type: string
|
|
permissions:
|
|
enum:
|
|
- read
|
|
- write
|
|
- admin
|
|
type: string
|
|
required:
|
|
- permissions
|
|
type: object
|
|
internal_core_track.InitiateChunkedUploadRequest:
|
|
properties:
|
|
filename:
|
|
type: string
|
|
total_chunks:
|
|
minimum: 1
|
|
type: integer
|
|
total_size:
|
|
minimum: 1
|
|
type: integer
|
|
required:
|
|
- filename
|
|
- total_chunks
|
|
- total_size
|
|
type: object
|
|
internal_core_track.RecordPlayRequest:
|
|
properties:
|
|
play_time:
|
|
minimum: 0
|
|
type: integer
|
|
type: object
|
|
internal_core_track.StreamCallbackRequest:
|
|
properties:
|
|
error:
|
|
type: string
|
|
manifest_url:
|
|
type: string
|
|
status:
|
|
enum:
|
|
- completed
|
|
- failed
|
|
- processing
|
|
type: string
|
|
required:
|
|
- status
|
|
type: object
|
|
internal_core_track.UpdateLyricsRequest:
|
|
properties:
|
|
content:
|
|
type: string
|
|
type: object
|
|
internal_core_track.UpdateTrackRequest:
|
|
properties:
|
|
album:
|
|
maxLength: 255
|
|
type: string
|
|
artist:
|
|
maxLength: 255
|
|
type: string
|
|
bpm:
|
|
maximum: 300
|
|
minimum: 0
|
|
type: integer
|
|
genre:
|
|
description: legacy, single
|
|
maxLength: 100
|
|
type: string
|
|
genres:
|
|
description: 'v0.10.1: max 3, taxonomy slugs'
|
|
items:
|
|
type: string
|
|
type: array
|
|
is_public:
|
|
type: boolean
|
|
musical_key:
|
|
maxLength: 10
|
|
type: string
|
|
tags:
|
|
description: 'v0.10.1: max 10, 30 chars each'
|
|
items:
|
|
type: string
|
|
type: array
|
|
title:
|
|
maxLength: 255
|
|
minLength: 1
|
|
type: string
|
|
year:
|
|
maximum: 2100
|
|
minimum: 1900
|
|
type: integer
|
|
type: object
|
|
internal_handlers.APIResponse:
|
|
properties:
|
|
data: {}
|
|
error: {}
|
|
success:
|
|
type: boolean
|
|
type: object
|
|
internal_handlers.AddCollaboratorRequest:
|
|
properties:
|
|
permission:
|
|
enum:
|
|
- read
|
|
- write
|
|
- admin
|
|
type: string
|
|
user_id:
|
|
type: string
|
|
required:
|
|
- permission
|
|
- user_id
|
|
type: object
|
|
internal_handlers.AddQueueItemRequest:
|
|
properties:
|
|
track_id:
|
|
type: string
|
|
required:
|
|
- track_id
|
|
type: object
|
|
internal_handlers.AddToSessionRequest:
|
|
properties:
|
|
track_id:
|
|
type: string
|
|
required:
|
|
- track_id
|
|
type: object
|
|
internal_handlers.CreateCommentRequest:
|
|
properties:
|
|
content:
|
|
maxLength: 5000
|
|
minLength: 1
|
|
type: string
|
|
parent_id:
|
|
type: string
|
|
timestamp:
|
|
description: Position in seconds (0 = top-level, no specific time)
|
|
type: number
|
|
required:
|
|
- content
|
|
type: object
|
|
internal_handlers.CreateOrderRequest:
|
|
properties:
|
|
items:
|
|
items:
|
|
properties:
|
|
product_id:
|
|
type: string
|
|
required:
|
|
- product_id
|
|
type: object
|
|
minItems: 1
|
|
type: array
|
|
promo_code:
|
|
maxLength: 50
|
|
type: string
|
|
required:
|
|
- items
|
|
type: object
|
|
internal_handlers.CreatePlaylistRequest:
|
|
properties:
|
|
description:
|
|
maxLength: 1000
|
|
type: string
|
|
is_public:
|
|
type: boolean
|
|
title:
|
|
maxLength: 200
|
|
minLength: 1
|
|
type: string
|
|
required:
|
|
- title
|
|
type: object
|
|
internal_handlers.CreateProductRequest:
|
|
properties:
|
|
bpm:
|
|
description: v0.401 M1
|
|
maximum: 300
|
|
minimum: 1
|
|
type: integer
|
|
category:
|
|
enum:
|
|
- sample
|
|
- beat
|
|
- preset
|
|
- pack
|
|
type: string
|
|
description:
|
|
maxLength: 2000
|
|
type: string
|
|
license_type:
|
|
enum:
|
|
- standard
|
|
- exclusive
|
|
- commercial
|
|
type: string
|
|
licenses:
|
|
description: 'v0.401 M2: Product licenses (streaming, personal, commercial,
|
|
exclusive)'
|
|
items:
|
|
properties:
|
|
license_type:
|
|
enum:
|
|
- streaming
|
|
- personal
|
|
- commercial
|
|
- exclusive
|
|
type: string
|
|
price_cents:
|
|
minimum: 0
|
|
type: integer
|
|
terms_text:
|
|
type: string
|
|
required:
|
|
- license_type
|
|
- price_cents
|
|
type: object
|
|
type: array
|
|
musical_key:
|
|
maxLength: 10
|
|
type: string
|
|
price:
|
|
minimum: 0
|
|
type: number
|
|
product_type:
|
|
enum:
|
|
- track
|
|
- pack
|
|
- service
|
|
type: string
|
|
title:
|
|
maxLength: 200
|
|
minLength: 3
|
|
type: string
|
|
track_id:
|
|
description: UUID string
|
|
type: string
|
|
required:
|
|
- price
|
|
- product_type
|
|
- title
|
|
type: object
|
|
internal_handlers.DashboardResponse:
|
|
properties:
|
|
library_preview:
|
|
$ref: '#/definitions/internal_handlers.LibraryPreview'
|
|
recent_activity:
|
|
items:
|
|
$ref: '#/definitions/internal_handlers.RecentActivity'
|
|
type: array
|
|
stats:
|
|
$ref: '#/definitions/internal_handlers.DashboardStats'
|
|
type: object
|
|
internal_handlers.DashboardStats:
|
|
properties:
|
|
active_friends:
|
|
type: integer
|
|
active_friends_change:
|
|
type: string
|
|
favorites:
|
|
type: integer
|
|
favorites_change:
|
|
type: string
|
|
messages_sent:
|
|
type: integer
|
|
messages_sent_change:
|
|
type: string
|
|
period:
|
|
type: string
|
|
tracks_played:
|
|
type: integer
|
|
tracks_played_change:
|
|
type: string
|
|
type: object
|
|
internal_handlers.DeleteAccountRequest:
|
|
properties:
|
|
confirm_text:
|
|
type: string
|
|
keep_public_tracks:
|
|
description: If true, public tracks remain (attributed to deleted account)
|
|
type: boolean
|
|
password:
|
|
type: string
|
|
reason:
|
|
type: string
|
|
required:
|
|
- confirm_text
|
|
- password
|
|
type: object
|
|
internal_handlers.DisableTwoFactorRequest:
|
|
properties:
|
|
password:
|
|
type: string
|
|
required:
|
|
- password
|
|
type: object
|
|
internal_handlers.FrontendLogRequest:
|
|
properties:
|
|
context:
|
|
additionalProperties: true
|
|
type: object
|
|
data: {}
|
|
level:
|
|
type: string
|
|
message:
|
|
type: string
|
|
timestamp:
|
|
type: string
|
|
type: object
|
|
internal_handlers.IceServer:
|
|
properties:
|
|
credential:
|
|
type: string
|
|
urls:
|
|
items:
|
|
type: string
|
|
type: array
|
|
username:
|
|
type: string
|
|
type: object
|
|
internal_handlers.ImportPlaylistRequest:
|
|
properties:
|
|
playlist:
|
|
properties:
|
|
description:
|
|
type: string
|
|
is_public:
|
|
type: boolean
|
|
title:
|
|
type: string
|
|
type: object
|
|
tracks:
|
|
items:
|
|
properties:
|
|
id:
|
|
type: string
|
|
type: object
|
|
type: array
|
|
type: object
|
|
internal_handlers.LibraryPreview:
|
|
properties:
|
|
has_more:
|
|
type: boolean
|
|
items:
|
|
items:
|
|
$ref: '#/definitions/internal_handlers.TrackPreview'
|
|
type: array
|
|
total_count:
|
|
type: integer
|
|
type: object
|
|
internal_handlers.RecentActivity:
|
|
properties:
|
|
description:
|
|
type: string
|
|
icon:
|
|
type: string
|
|
id:
|
|
type: string
|
|
metadata:
|
|
additionalProperties: true
|
|
type: object
|
|
timestamp:
|
|
type: string
|
|
title:
|
|
type: string
|
|
type:
|
|
type: string
|
|
type: object
|
|
internal_handlers.ReorderTracksRequest:
|
|
properties:
|
|
track_ids:
|
|
description: Changed to []uuid.UUID
|
|
items:
|
|
type: string
|
|
minItems: 1
|
|
type: array
|
|
required:
|
|
- track_ids
|
|
type: object
|
|
internal_handlers.RequestPasswordResetRequest:
|
|
properties:
|
|
email:
|
|
type: string
|
|
required:
|
|
- email
|
|
type: object
|
|
internal_handlers.ResetPasswordRequest:
|
|
properties:
|
|
new_password:
|
|
minLength: 12
|
|
type: string
|
|
token:
|
|
type: string
|
|
required:
|
|
- new_password
|
|
- token
|
|
type: object
|
|
internal_handlers.SetupTwoFactorResponse:
|
|
properties:
|
|
qr_code_url:
|
|
type: string
|
|
recovery_codes:
|
|
items:
|
|
type: string
|
|
type: array
|
|
secret:
|
|
type: string
|
|
type: object
|
|
internal_handlers.StreamTokenResponse:
|
|
properties:
|
|
expires_in:
|
|
description: seconds
|
|
type: integer
|
|
token:
|
|
type: string
|
|
type: object
|
|
internal_handlers.TrackPreview:
|
|
properties:
|
|
artist:
|
|
type: string
|
|
cover_art_path:
|
|
type: string
|
|
created_at:
|
|
type: string
|
|
duration:
|
|
type: integer
|
|
id:
|
|
type: string
|
|
like_count:
|
|
type: integer
|
|
play_count:
|
|
type: integer
|
|
title:
|
|
type: string
|
|
type: object
|
|
internal_handlers.UpdateCollaboratorPermissionRequest:
|
|
properties:
|
|
permission:
|
|
enum:
|
|
- read
|
|
- write
|
|
- admin
|
|
type: string
|
|
required:
|
|
- permission
|
|
type: object
|
|
internal_handlers.UpdateCommentRequest:
|
|
properties:
|
|
content:
|
|
maxLength: 5000
|
|
minLength: 1
|
|
type: string
|
|
required:
|
|
- content
|
|
type: object
|
|
internal_handlers.UpdatePlaylistRequest:
|
|
properties:
|
|
description:
|
|
maxLength: 1000
|
|
type: string
|
|
is_public:
|
|
type: boolean
|
|
title:
|
|
maxLength: 200
|
|
minLength: 1
|
|
type: string
|
|
type: object
|
|
internal_handlers.UpdateProductRequest:
|
|
properties:
|
|
bpm:
|
|
maximum: 300
|
|
minimum: 1
|
|
type: integer
|
|
category:
|
|
enum:
|
|
- sample
|
|
- beat
|
|
- preset
|
|
- pack
|
|
type: string
|
|
description:
|
|
maxLength: 2000
|
|
type: string
|
|
licenses:
|
|
description: 'v0.401 M2: Product licenses'
|
|
items:
|
|
properties:
|
|
license_type:
|
|
enum:
|
|
- streaming
|
|
- personal
|
|
- commercial
|
|
- exclusive
|
|
type: string
|
|
price_cents:
|
|
minimum: 0
|
|
type: integer
|
|
terms_text:
|
|
type: string
|
|
required:
|
|
- license_type
|
|
- price_cents
|
|
type: object
|
|
type: array
|
|
musical_key:
|
|
maxLength: 10
|
|
type: string
|
|
price:
|
|
minimum: 0
|
|
type: number
|
|
status:
|
|
enum:
|
|
- draft
|
|
- active
|
|
- archived
|
|
type: string
|
|
title:
|
|
maxLength: 200
|
|
minLength: 3
|
|
type: string
|
|
type: object
|
|
internal_handlers.UpdateProfileRequest:
|
|
properties:
|
|
banner_url:
|
|
maxLength: 2048
|
|
type: string
|
|
bio:
|
|
maxLength: 500
|
|
type: string
|
|
birthdate:
|
|
type: string
|
|
first_name:
|
|
maxLength: 100
|
|
type: string
|
|
gender:
|
|
enum:
|
|
- Male
|
|
- Female
|
|
- Other
|
|
- Prefer not to say
|
|
type: string
|
|
is_public:
|
|
type: boolean
|
|
last_name:
|
|
maxLength: 100
|
|
type: string
|
|
location:
|
|
maxLength: 100
|
|
type: string
|
|
social_links:
|
|
additionalProperties: true
|
|
type: object
|
|
username:
|
|
maxLength: 30
|
|
minLength: 3
|
|
type: string
|
|
type: object
|
|
internal_handlers.ValidateRequest:
|
|
properties:
|
|
data:
|
|
description: The data to validate
|
|
items:
|
|
type: integer
|
|
type: array
|
|
type:
|
|
description: e.g., "RegisterRequest", "LoginRequest"
|
|
type: string
|
|
required:
|
|
- data
|
|
- type
|
|
type: object
|
|
internal_handlers.ValidateResponse:
|
|
properties:
|
|
errors:
|
|
items:
|
|
$ref: '#/definitions/veza-backend-api_internal_dto.ValidationError'
|
|
type: array
|
|
message:
|
|
type: string
|
|
valid:
|
|
type: boolean
|
|
type: object
|
|
internal_handlers.VerifyTwoFactorRequest:
|
|
properties:
|
|
code:
|
|
description: TOTP code to verify
|
|
type: string
|
|
secret:
|
|
description: Secret from setup step
|
|
type: string
|
|
required:
|
|
- code
|
|
- secret
|
|
type: object
|
|
internal_handlers.WebRTCConfigResponse:
|
|
properties:
|
|
iceServers:
|
|
items:
|
|
$ref: '#/definitions/internal_handlers.IceServer'
|
|
type: array
|
|
type: object
|
|
veza-backend-api_internal_core_marketplace.LicenseType:
|
|
enum:
|
|
- basic
|
|
- premium
|
|
- exclusive
|
|
type: string
|
|
x-enum-varnames:
|
|
- LicenseBasic
|
|
- LicensePremium
|
|
- LicenseExclusive
|
|
veza-backend-api_internal_core_marketplace.Order:
|
|
properties:
|
|
buyer_id:
|
|
type: string
|
|
created_at:
|
|
type: string
|
|
currency:
|
|
type: string
|
|
discount_amount_cents:
|
|
type: integer
|
|
hyperswitch_payment_id:
|
|
type: string
|
|
id:
|
|
type: string
|
|
items:
|
|
items:
|
|
$ref: '#/definitions/veza-backend-api_internal_core_marketplace.OrderItem'
|
|
type: array
|
|
payment_intent:
|
|
description: Legacy / Stripe PaymentIntent ID
|
|
type: string
|
|
payment_status:
|
|
description: Hyperswitch payment status
|
|
type: string
|
|
promo_code_id:
|
|
type: string
|
|
refund_deadline:
|
|
description: 'v0.12.0: 14-day refund deadline'
|
|
type: string
|
|
status:
|
|
description: pending, completed, failed, refunded
|
|
type: string
|
|
total_amount:
|
|
type: number
|
|
updated_at:
|
|
type: string
|
|
type: object
|
|
veza-backend-api_internal_core_marketplace.OrderItem:
|
|
properties:
|
|
id:
|
|
type: string
|
|
order_id:
|
|
type: string
|
|
price:
|
|
type: number
|
|
product_id:
|
|
type: string
|
|
type: object
|
|
veza-backend-api_internal_core_marketplace.Product:
|
|
properties:
|
|
avg_rating:
|
|
description: 'v0.403 R1: Computed from product_reviews (not stored in DB)'
|
|
type: number
|
|
bpm:
|
|
description: 'v0.401 M1: Métadonnées musicales et catégorie'
|
|
type: integer
|
|
category:
|
|
description: sample, beat, preset, pack
|
|
type: string
|
|
created_at:
|
|
type: string
|
|
currency:
|
|
type: string
|
|
description:
|
|
type: string
|
|
id:
|
|
type: string
|
|
images:
|
|
items:
|
|
$ref: '#/definitions/veza-backend-api_internal_core_marketplace.ProductImage'
|
|
type: array
|
|
license_type:
|
|
$ref: '#/definitions/veza-backend-api_internal_core_marketplace.LicenseType'
|
|
licenses:
|
|
items:
|
|
$ref: '#/definitions/veza-backend-api_internal_core_marketplace.ProductLicense'
|
|
type: array
|
|
musical_key:
|
|
type: string
|
|
previews:
|
|
description: Relations
|
|
items:
|
|
$ref: '#/definitions/veza-backend-api_internal_core_marketplace.ProductPreview'
|
|
type: array
|
|
price:
|
|
type: number
|
|
product_type:
|
|
description: '"track", "pack", "service"'
|
|
type: string
|
|
review_count:
|
|
type: integer
|
|
seller_id:
|
|
type: string
|
|
status:
|
|
$ref: '#/definitions/veza-backend-api_internal_core_marketplace.ProductStatus'
|
|
title:
|
|
type: string
|
|
track_id:
|
|
description: Liaison optionnelle avec un Track (si ProductType == "track")
|
|
type: string
|
|
updated_at:
|
|
type: string
|
|
type: object
|
|
veza-backend-api_internal_core_marketplace.ProductImage:
|
|
properties:
|
|
created_at:
|
|
type: string
|
|
id:
|
|
type: string
|
|
product_id:
|
|
type: string
|
|
sort_order:
|
|
type: integer
|
|
url:
|
|
type: string
|
|
type: object
|
|
veza-backend-api_internal_core_marketplace.ProductLicense:
|
|
properties:
|
|
created_at:
|
|
type: string
|
|
id:
|
|
type: string
|
|
license_type:
|
|
description: streaming, personal, commercial, exclusive
|
|
type: string
|
|
price_cents:
|
|
type: integer
|
|
product_id:
|
|
type: string
|
|
terms_text:
|
|
type: string
|
|
type: object
|
|
veza-backend-api_internal_core_marketplace.ProductPreview:
|
|
properties:
|
|
created_at:
|
|
type: string
|
|
duration_sec:
|
|
type: integer
|
|
file_path:
|
|
type: string
|
|
id:
|
|
type: string
|
|
product_id:
|
|
type: string
|
|
type: object
|
|
veza-backend-api_internal_core_marketplace.ProductStatus:
|
|
enum:
|
|
- draft
|
|
- active
|
|
- archived
|
|
type: string
|
|
x-enum-varnames:
|
|
- ProductStatusDraft
|
|
- ProductStatusActive
|
|
- ProductStatusArchived
|
|
veza-backend-api_internal_dto.LoginRequest:
|
|
properties:
|
|
email:
|
|
type: string
|
|
password:
|
|
type: string
|
|
remember_me:
|
|
type: boolean
|
|
required:
|
|
- email
|
|
- password
|
|
type: object
|
|
veza-backend-api_internal_dto.LoginResponse:
|
|
properties:
|
|
requires_2fa:
|
|
description: 'BE-API-001: Flag indicating 2FA is required'
|
|
type: boolean
|
|
token:
|
|
$ref: '#/definitions/veza-backend-api_internal_dto.TokenResponse'
|
|
user:
|
|
$ref: '#/definitions/veza-backend-api_internal_dto.UserResponse'
|
|
type: object
|
|
veza-backend-api_internal_dto.RefreshRequest:
|
|
properties:
|
|
refresh_token:
|
|
type: string
|
|
required:
|
|
- refresh_token
|
|
type: object
|
|
veza-backend-api_internal_dto.RegisterRequest:
|
|
properties:
|
|
email:
|
|
type: string
|
|
password:
|
|
minLength: 12
|
|
type: string
|
|
password_confirmation:
|
|
type: string
|
|
username:
|
|
maxLength: 50
|
|
minLength: 3
|
|
type: string
|
|
required:
|
|
- email
|
|
- password
|
|
- password_confirmation
|
|
type: object
|
|
veza-backend-api_internal_dto.RegisterResponse:
|
|
properties:
|
|
message:
|
|
type: string
|
|
user:
|
|
$ref: '#/definitions/veza-backend-api_internal_dto.UserResponse'
|
|
verification_required:
|
|
type: boolean
|
|
type: object
|
|
veza-backend-api_internal_dto.ResendVerificationRequest:
|
|
properties:
|
|
email:
|
|
type: string
|
|
required:
|
|
- email
|
|
type: object
|
|
veza-backend-api_internal_dto.TokenResponse:
|
|
properties:
|
|
access_token:
|
|
type: string
|
|
expires_in:
|
|
type: integer
|
|
refresh_token:
|
|
type: string
|
|
type: object
|
|
veza-backend-api_internal_dto.UserResponse:
|
|
properties:
|
|
email:
|
|
type: string
|
|
id:
|
|
type: string
|
|
username:
|
|
type: string
|
|
type: object
|
|
veza-backend-api_internal_dto.ValidationError:
|
|
properties:
|
|
field:
|
|
type: string
|
|
message:
|
|
type: string
|
|
value:
|
|
type: string
|
|
type: object
|
|
veza-backend-api_internal_handlers.APIResponse:
|
|
properties:
|
|
data: {}
|
|
error: {}
|
|
success:
|
|
type: boolean
|
|
type: object
|
|
veza-backend-api_internal_models.Playlist:
|
|
properties:
|
|
collaborators:
|
|
items:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.PlaylistCollaborator'
|
|
type: array
|
|
cover_url:
|
|
type: string
|
|
created_at:
|
|
type: string
|
|
description:
|
|
type: string
|
|
follower_count:
|
|
type: integer
|
|
id:
|
|
type: string
|
|
is_default_favorites:
|
|
description: v0.10.4 F136
|
|
type: boolean
|
|
is_editorial:
|
|
description: v0.10.4 F141
|
|
type: boolean
|
|
is_public:
|
|
type: boolean
|
|
title:
|
|
type: string
|
|
track_count:
|
|
type: integer
|
|
tracks:
|
|
items:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.PlaylistTrack'
|
|
type: array
|
|
updated_at:
|
|
type: string
|
|
user_id:
|
|
type: string
|
|
type: object
|
|
veza-backend-api_internal_models.PlaylistCollaborator:
|
|
properties:
|
|
created_at:
|
|
type: string
|
|
id:
|
|
type: string
|
|
permission:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.PlaylistPermission'
|
|
playlist_id:
|
|
type: string
|
|
updated_at:
|
|
type: string
|
|
user:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.User'
|
|
user_id:
|
|
type: string
|
|
type: object
|
|
veza-backend-api_internal_models.PlaylistPermission:
|
|
enum:
|
|
- read
|
|
- write
|
|
- admin
|
|
type: string
|
|
x-enum-varnames:
|
|
- PlaylistPermissionRead
|
|
- PlaylistPermissionWrite
|
|
- PlaylistPermissionAdmin
|
|
veza-backend-api_internal_models.PlaylistTrack:
|
|
properties:
|
|
added_at:
|
|
type: string
|
|
added_by:
|
|
type: string
|
|
id:
|
|
type: string
|
|
playlist_id:
|
|
type: string
|
|
position:
|
|
type: integer
|
|
track:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.Track'
|
|
track_id:
|
|
type: string
|
|
type: object
|
|
veza-backend-api_internal_models.Track:
|
|
properties:
|
|
album:
|
|
type: string
|
|
artist:
|
|
type: string
|
|
bitrate:
|
|
description: kbps
|
|
type: integer
|
|
bpm:
|
|
type: integer
|
|
cover_art_path:
|
|
type: string
|
|
created_at:
|
|
type: string
|
|
creator_id:
|
|
type: string
|
|
duration:
|
|
description: seconds
|
|
type: integer
|
|
file_id:
|
|
description: NULL temporairement avant création fichier
|
|
type: string
|
|
file_path:
|
|
type: string
|
|
file_size:
|
|
description: bytes
|
|
type: integer
|
|
format:
|
|
description: mp3, flac, wav, etc.
|
|
type: string
|
|
genre:
|
|
type: string
|
|
id:
|
|
type: string
|
|
is_public:
|
|
type: boolean
|
|
musical_key:
|
|
type: string
|
|
sample_rate:
|
|
description: Hz
|
|
type: integer
|
|
status:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.TrackStatus'
|
|
status_message:
|
|
type: string
|
|
stream_manifest_url:
|
|
type: string
|
|
stream_status:
|
|
description: pending, processing, ready, error
|
|
type: string
|
|
tags:
|
|
items:
|
|
type: string
|
|
type: array
|
|
title:
|
|
type: string
|
|
updated_at:
|
|
type: string
|
|
waveform_path:
|
|
type: string
|
|
waveform_url:
|
|
type: string
|
|
year:
|
|
type: integer
|
|
type: object
|
|
veza-backend-api_internal_models.TrackStatus:
|
|
enum:
|
|
- uploading
|
|
- processing
|
|
- completed
|
|
- failed
|
|
type: string
|
|
x-enum-varnames:
|
|
- TrackStatusUploading
|
|
- TrackStatusProcessing
|
|
- TrackStatusCompleted
|
|
- TrackStatusFailed
|
|
veza-backend-api_internal_models.User:
|
|
properties:
|
|
avatar:
|
|
type: string
|
|
banner_url:
|
|
type: string
|
|
bio:
|
|
type: string
|
|
birthdate:
|
|
type: string
|
|
created_at:
|
|
type: string
|
|
email:
|
|
type: string
|
|
first_name:
|
|
type: string
|
|
gender:
|
|
type: string
|
|
id:
|
|
type: string
|
|
is_active:
|
|
type: boolean
|
|
is_admin:
|
|
type: boolean
|
|
is_banned:
|
|
type: boolean
|
|
is_public:
|
|
type: boolean
|
|
is_verified:
|
|
type: boolean
|
|
last_login_at:
|
|
type: string
|
|
last_name:
|
|
type: string
|
|
location:
|
|
type: string
|
|
login_count:
|
|
type: integer
|
|
password:
|
|
description: Virtual field for input
|
|
type: string
|
|
password_changed_at:
|
|
description: 'F016: Password expiration tracking'
|
|
type: string
|
|
promoted_to_creator_at:
|
|
description: |-
|
|
v1.0.6: set the first time a user self-promotes to `role='creator'`
|
|
via POST /api/v1/users/me/upgrade-creator. NULL for users who never
|
|
took that path (still 'user', or promoted by an admin out-of-band).
|
|
type: string
|
|
role:
|
|
type: string
|
|
slug:
|
|
type: string
|
|
social_links:
|
|
type: string
|
|
token_version:
|
|
type: integer
|
|
updated_at:
|
|
type: string
|
|
username:
|
|
type: string
|
|
username_changed_at:
|
|
type: string
|
|
type: object
|
|
veza-backend-api_internal_response.APIResponse:
|
|
properties:
|
|
data: {}
|
|
error: {}
|
|
success:
|
|
type: boolean
|
|
type: object
|
|
veza-backend-api_internal_services.UpdateQueueRequest:
|
|
properties:
|
|
current_position:
|
|
type: integer
|
|
current_track_id:
|
|
type: string
|
|
is_playing:
|
|
type: boolean
|
|
item_order:
|
|
items:
|
|
type: string
|
|
type: array
|
|
repeat_mode:
|
|
type: string
|
|
shuffle:
|
|
type: boolean
|
|
volume:
|
|
type: integer
|
|
type: object
|
|
host: localhost:18080
|
|
info:
|
|
contact:
|
|
email: support@veza.fr
|
|
name: API Support
|
|
url: https://veza.fr/support
|
|
description: Backend API for Veza platform.
|
|
license:
|
|
name: Apache 2.0
|
|
url: http://www.apache.org/licenses/LICENSE-2.0.html
|
|
termsOfService: http://swagger.io/terms/
|
|
title: Veza Backend API
|
|
version: 1.2.0
|
|
paths:
|
|
/api/v1/dashboard:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Get aggregated dashboard data including stats, recent activity,
|
|
and library preview
|
|
parameters:
|
|
- description: 'Number of recent activity items (default: 10)'
|
|
in: query
|
|
name: activity_limit
|
|
type: integer
|
|
- description: 'Number of library items (default: 5)'
|
|
in: query
|
|
name: library_limit
|
|
type: integer
|
|
- description: 'Time period for statistics: 7d, 30d, 90d, all (default: 30d)'
|
|
in: query
|
|
name: stats_period
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
$ref: '#/definitions/internal_handlers.DashboardResponse'
|
|
type: object
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal server error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Get Dashboard Data
|
|
tags:
|
|
- Dashboard
|
|
/api/v1/logs/frontend:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Receive and store a log entry from the frontend application
|
|
parameters:
|
|
- description: Frontend log entry
|
|
in: body
|
|
name: log
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.FrontendLogRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
received:
|
|
type: boolean
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid log entry
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal server error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
summary: Receive frontend log
|
|
tags:
|
|
- Logging
|
|
/api/v1/marketplace/download/{product_id}:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Get a secure download URL for a purchased product
|
|
parameters:
|
|
- description: Product ID
|
|
in: path
|
|
name: product_id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
additionalProperties:
|
|
type: string
|
|
type: object
|
|
"403":
|
|
description: No license
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"404":
|
|
description: Not Found
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Get download URL
|
|
tags:
|
|
- Marketplace
|
|
/api/v1/marketplace/orders:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Get all orders for the authenticated user
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
items:
|
|
$ref: '#/definitions/veza-backend-api_internal_core_marketplace.Order'
|
|
type: array
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: List user orders
|
|
tags:
|
|
- Marketplace
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Purchase products
|
|
parameters:
|
|
- description: Order items
|
|
in: body
|
|
name: order
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.CreateOrderRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"201":
|
|
description: Created
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_core_marketplace.Order'
|
|
"400":
|
|
description: Validation Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Create a new order
|
|
tags:
|
|
- Marketplace
|
|
/api/v1/marketplace/orders/{id}:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Get details of a specific order (only order owner can access)
|
|
parameters:
|
|
- description: Order ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_core_marketplace.Order'
|
|
"400":
|
|
description: Validation Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"403":
|
|
description: Forbidden - Not order owner
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"404":
|
|
description: Order not found
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Get order details
|
|
tags:
|
|
- Marketplace
|
|
/api/v1/marketplace/products:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: List marketplace products with filters
|
|
parameters:
|
|
- description: Product status
|
|
in: query
|
|
name: status
|
|
type: string
|
|
- description: Seller ID
|
|
in: query
|
|
name: seller_id
|
|
type: string
|
|
- description: Search query
|
|
in: query
|
|
name: q
|
|
type: string
|
|
- description: Product type (track, pack, service)
|
|
in: query
|
|
name: type
|
|
type: string
|
|
- description: Minimum price
|
|
in: query
|
|
name: min_price
|
|
type: number
|
|
- description: Maximum price
|
|
in: query
|
|
name: max_price
|
|
type: number
|
|
- description: Page number
|
|
in: query
|
|
name: page
|
|
type: integer
|
|
- description: Items per page
|
|
in: query
|
|
name: limit
|
|
type: integer
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
items:
|
|
$ref: '#/definitions/veza-backend-api_internal_core_marketplace.Product'
|
|
type: array
|
|
summary: List products
|
|
tags:
|
|
- Marketplace
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Create a product (Track, Pack, Service) for sale
|
|
parameters:
|
|
- description: Product info
|
|
in: body
|
|
name: product
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.CreateProductRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"201":
|
|
description: Created
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_core_marketplace.Product'
|
|
"400":
|
|
description: Validation Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Create a new product
|
|
tags:
|
|
- Marketplace
|
|
/api/v1/marketplace/products/{id}:
|
|
put:
|
|
consumes:
|
|
- application/json
|
|
description: Update product details (only seller can update)
|
|
parameters:
|
|
- description: Product ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- description: Product updates
|
|
in: body
|
|
name: product
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.UpdateProductRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_core_marketplace.Product'
|
|
"400":
|
|
description: Validation Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"403":
|
|
description: Forbidden - Not product owner
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"404":
|
|
description: Product not found
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Update a product
|
|
tags:
|
|
- Marketplace
|
|
/audit/activity:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Get recent activity logs for the current user
|
|
parameters:
|
|
- default: 50
|
|
description: Number of activities to return
|
|
in: query
|
|
name: limit
|
|
type: integer
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
activities:
|
|
type: array
|
|
type: object
|
|
type: object
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal server error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Get user activity
|
|
tags:
|
|
- Audit
|
|
/audit/logs:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Search and filter audit logs with pagination support. Supports
|
|
filtering by action, resource, date range, IP address, and user agent.
|
|
parameters:
|
|
- description: Filter by action type
|
|
in: query
|
|
name: action
|
|
type: string
|
|
- description: Filter by resource type
|
|
in: query
|
|
name: resource
|
|
type: string
|
|
- description: Filter by resource ID (UUID)
|
|
in: query
|
|
name: resource_id
|
|
type: string
|
|
- description: Filter by IP address
|
|
in: query
|
|
name: ip_address
|
|
type: string
|
|
- description: Filter by user agent
|
|
in: query
|
|
name: user_agent
|
|
type: string
|
|
- description: Start date filter (YYYY-MM-DD)
|
|
in: query
|
|
name: start_date
|
|
type: string
|
|
- description: End date filter (YYYY-MM-DD)
|
|
in: query
|
|
name: end_date
|
|
type: string
|
|
- default: 1
|
|
description: Page number
|
|
in: query
|
|
name: page
|
|
type: integer
|
|
- default: 20
|
|
description: Items per page
|
|
in: query
|
|
name: limit
|
|
type: integer
|
|
- description: Offset for pagination
|
|
in: query
|
|
name: offset
|
|
type: integer
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
logs:
|
|
type: array
|
|
pagination:
|
|
type: object
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal server error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Search audit logs
|
|
tags:
|
|
- Audit
|
|
/audit/stats:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Get audit statistics for the current user, optionally filtered
|
|
by date range
|
|
parameters:
|
|
- description: Start date (YYYY-MM-DD)
|
|
in: query
|
|
name: start_date
|
|
type: string
|
|
- description: End date (YYYY-MM-DD)
|
|
in: query
|
|
name: end_date
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
stats:
|
|
type: object
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal server error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Get audit statistics
|
|
tags:
|
|
- Audit
|
|
/auth/2fa/disable:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Disable 2FA for user (requires password confirmation)
|
|
parameters:
|
|
- description: Password Confirmation
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.DisableTwoFactorRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid password or 2FA not enabled
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Disable 2FA
|
|
tags:
|
|
- Auth
|
|
/auth/2fa/setup:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Generate 2FA secret and QR code for setup
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
$ref: '#/definitions/internal_handlers.SetupTwoFactorResponse'
|
|
type: object
|
|
"400":
|
|
description: 2FA already enabled
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Setup 2FA
|
|
tags:
|
|
- Auth
|
|
/auth/2fa/status:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Get 2FA enabled status for authenticated user
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
enabled:
|
|
type: boolean
|
|
type: object
|
|
type: object
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Get 2FA Status
|
|
tags:
|
|
- Auth
|
|
/auth/2fa/verify:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Verify 2FA code and enable 2FA for user
|
|
parameters:
|
|
- description: 2FA Code
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.VerifyTwoFactorRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid code
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Verify and Enable 2FA
|
|
tags:
|
|
- Auth
|
|
/auth/check-username:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Check if a username is already taken
|
|
parameters:
|
|
- description: Username to check
|
|
in: query
|
|
name: username
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
available:
|
|
type: boolean
|
|
username:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Missing Username
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
summary: Check Username Availability
|
|
tags:
|
|
- Auth
|
|
/auth/login:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Authenticate user and return access token. Refresh token is set
|
|
in httpOnly cookie.
|
|
parameters:
|
|
- description: Login Credentials
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_dto.LoginRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: Access token returned in body, refresh token in httpOnly cookie
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_dto.LoginResponse'
|
|
"400":
|
|
description: Validation or Bad Request
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Invalid credentials
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
summary: User Login
|
|
tags:
|
|
- Auth
|
|
/auth/logout:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Revoke refresh token and current session
|
|
parameters:
|
|
- description: Refresh Token to revoke
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
properties:
|
|
refresh_token:
|
|
type: string
|
|
type: object
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: Success message
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"400":
|
|
description: Validation Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Logout
|
|
tags:
|
|
- Auth
|
|
/auth/me:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Get profile information of the currently logged-in user
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: User not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Get Current User
|
|
tags:
|
|
- Auth
|
|
/auth/password/reset:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Completes a password reset using a valid token previously emailed
|
|
to the user. Invalidates all the user's existing sessions on success.
|
|
parameters:
|
|
- description: Reset token + new password
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.ResetPasswordRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: Password reset successfully
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid or expired token, or password validation failed
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Failed to update password
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
summary: Reset password with token
|
|
tags:
|
|
- Auth
|
|
/auth/password/reset-request:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Sends a password reset link to the user's email if the address
|
|
exists. Always returns 200 with a generic message to prevent email enumeration.
|
|
parameters:
|
|
- description: Email of the account to reset
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.RequestPasswordResetRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: If the email exists, a reset link has been sent
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Token generation/storage failed (or SMTP failure in production)
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
summary: Request password reset
|
|
tags:
|
|
- Auth
|
|
/auth/refresh:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Get a new access token using a refresh token
|
|
parameters:
|
|
- description: Refresh Token
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_dto.RefreshRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_dto.TokenResponse'
|
|
"400":
|
|
description: Validation Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Invalid/Expired Refresh Token
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
summary: Refresh Token
|
|
tags:
|
|
- Auth
|
|
/auth/register:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Register a new user account
|
|
parameters:
|
|
- description: Registration Data
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_dto.RegisterRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"201":
|
|
description: Created
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_dto.RegisterResponse'
|
|
"400":
|
|
description: Validation Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"409":
|
|
description: User already exists
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
summary: User Registration
|
|
tags:
|
|
- Auth
|
|
/auth/resend-verification:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Resend the email verification link
|
|
parameters:
|
|
- description: Email
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_dto.ResendVerificationRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: Success message
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"400":
|
|
description: Validation Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
summary: Resend Verification Email
|
|
tags:
|
|
- Auth
|
|
/auth/stream-token:
|
|
post:
|
|
description: Returns a 5-minute JWT for HLS and WebSocket authentication (httpOnly
|
|
cookies prevent direct token access)
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.StreamTokenResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Get ephemeral stream token
|
|
tags:
|
|
- Auth
|
|
/auth/verify-email:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: |-
|
|
Verify user email address using a token. v1.0.9 item 1.3:
|
|
the token is read from the X-Verify-Token header (anti-leak
|
|
via Referer / proxy access logs). The query-param form
|
|
remains accepted for backward compatibility with emails sent
|
|
before v1.0.9 — both paths log a deprecation warning when
|
|
the query path is used.
|
|
parameters:
|
|
- description: Verification Token (preferred)
|
|
in: header
|
|
name: X-Verify-Token
|
|
required: true
|
|
type: string
|
|
- description: Verification Token (deprecated, accepted for backward compat)
|
|
in: query
|
|
name: token
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: Success message
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"400":
|
|
description: Invalid Token
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
summary: Verify Email
|
|
tags:
|
|
- Auth
|
|
/chat/token:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Generate a short-lived token for chat authentication
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
token:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Get Chat Token
|
|
tags:
|
|
- Chat
|
|
/comments/{id}:
|
|
put:
|
|
consumes:
|
|
- application/json
|
|
description: Update a comment (only by owner)
|
|
parameters:
|
|
- description: Comment ID (UUID)
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- description: Updated comment content
|
|
in: body
|
|
name: comment
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.UpdateCommentRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
comment:
|
|
type: object
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"403":
|
|
description: Forbidden - can only edit own comments
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: Comment not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal server error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Update comment
|
|
tags:
|
|
- Comment
|
|
/comments/{id}/replies:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Get paginated list of replies to a comment
|
|
parameters:
|
|
- description: Parent Comment ID (UUID)
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- default: 1
|
|
description: Page number
|
|
in: query
|
|
minimum: 1
|
|
name: page
|
|
type: integer
|
|
- default: 20
|
|
description: Items per page
|
|
in: query
|
|
maximum: 100
|
|
minimum: 1
|
|
name: limit
|
|
type: integer
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
pagination:
|
|
type: object
|
|
replies:
|
|
type: array
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: Parent comment not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal server error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
summary: Get comment replies
|
|
tags:
|
|
- Comment
|
|
/config/webrtc:
|
|
get:
|
|
description: Public — returns the ICE-server set the SPA feeds to RTCPeerConnection.
|
|
STUN-only when no TURN is configured. TURN credentials are always emitted
|
|
as static (REST shared-secret rotation deferred to v1.1).
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: ICE servers
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.WebRTCConfigResponse'
|
|
summary: WebRTC ICE configuration
|
|
tags:
|
|
- Config
|
|
/internal/tracks/{id}/stream-ready:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Internal endpoint called by the Rust stream server when HLS transcoding
|
|
completes or fails. Updates the track's stream_status and stream_manifest_url.
|
|
Requires internal API key (not user-facing).
|
|
parameters:
|
|
- description: Track UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- description: Callback payload
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_core_track.StreamCallbackRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
"400":
|
|
description: Validation / invalid id
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
summary: Stream server callback
|
|
tags:
|
|
- Track
|
|
/playlists:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Get a paginated list of playlists
|
|
parameters:
|
|
- default: 1
|
|
description: Page number
|
|
in: query
|
|
name: page
|
|
type: integer
|
|
- default: 20
|
|
description: Items per page
|
|
in: query
|
|
name: limit
|
|
type: integer
|
|
- description: Filter by User ID
|
|
in: query
|
|
name: user_id
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
pagination:
|
|
type: object
|
|
playlists:
|
|
items:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.Playlist'
|
|
type: array
|
|
type: object
|
|
type: object
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Get Playlists
|
|
tags:
|
|
- Playlist
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Create a new playlist
|
|
parameters:
|
|
- description: Playlist Metadata
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.CreatePlaylistRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"201":
|
|
description: Created
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
playlist:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.Playlist'
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Create Playlist
|
|
tags:
|
|
- Playlist
|
|
/playlists/{id}:
|
|
delete:
|
|
consumes:
|
|
- application/json
|
|
description: Permanently delete a playlist
|
|
parameters:
|
|
- description: Playlist ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"403":
|
|
description: Forbidden
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: Playlist not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Delete Playlist
|
|
tags:
|
|
- Playlist
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Get detailed information about a playlist
|
|
parameters:
|
|
- description: Playlist ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
playlist:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.Playlist'
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid ID
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: Playlist not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Get Playlist by ID
|
|
tags:
|
|
- Playlist
|
|
put:
|
|
consumes:
|
|
- application/json
|
|
description: Update playlist metadata
|
|
parameters:
|
|
- description: Playlist ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- description: Playlist Metadata
|
|
in: body
|
|
name: playlist
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.UpdatePlaylistRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
playlist:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.Playlist'
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"403":
|
|
description: Forbidden
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: Playlist not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Update Playlist
|
|
tags:
|
|
- Playlist
|
|
/playlists/{id}/analytics:
|
|
get:
|
|
description: Returns aggregated stats for a playlist (plays, follows, tracks
|
|
count, etc.). Visible to the owner, collaborators and admins.
|
|
parameters:
|
|
- description: Playlist UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
stats:
|
|
type: object
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid id
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"403":
|
|
description: Forbidden
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: Playlist not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Get playlist statistics
|
|
tags:
|
|
- Playlist
|
|
/playlists/{id}/collaborators:
|
|
get:
|
|
description: Returns the collaborators of a playlist with their permission level.
|
|
parameters:
|
|
- description: Playlist UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
collaborators:
|
|
items:
|
|
type: object
|
|
type: array
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid id
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: Playlist not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: List playlist collaborators
|
|
tags:
|
|
- Playlist
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Invite a user as collaborator. Only the owner (or admin) can add.
|
|
parameters:
|
|
- description: Playlist UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- description: Collaborator + permission
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.AddCollaboratorRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
collaborator:
|
|
type: object
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"403":
|
|
description: Not owner
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: Playlist not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Add playlist collaborator
|
|
tags:
|
|
- Playlist
|
|
/playlists/{id}/collaborators/{userId}:
|
|
delete:
|
|
description: Revoke a collaborator's access. Only the owner (or admin) can remove.
|
|
parameters:
|
|
- description: Playlist UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- description: Collaborator user UUID
|
|
in: path
|
|
name: userId
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"403":
|
|
description: Not owner
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: Playlist or collaborator not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Remove playlist collaborator
|
|
tags:
|
|
- Playlist
|
|
put:
|
|
consumes:
|
|
- application/json
|
|
description: Change a collaborator's permission level (read / write / admin).
|
|
Only the owner can update.
|
|
parameters:
|
|
- description: Playlist UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- description: Collaborator user UUID
|
|
in: path
|
|
name: userId
|
|
required: true
|
|
type: string
|
|
- description: New permission
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.UpdateCollaboratorPermissionRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
collaborator:
|
|
type: object
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"403":
|
|
description: Not owner
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: Playlist or collaborator not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Update collaborator permission
|
|
tags:
|
|
- Playlist
|
|
/playlists/{id}/duplicate:
|
|
post:
|
|
description: Copy a playlist's track list into a new playlist owned by the authenticated
|
|
user. Cover/description copied; original unchanged.
|
|
parameters:
|
|
- description: Source playlist UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"201":
|
|
description: Created
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
playlist:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.Playlist'
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid id
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"403":
|
|
description: Source not visible
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: Source playlist not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Duplicate playlist
|
|
tags:
|
|
- Playlist
|
|
/playlists/{id}/share:
|
|
post:
|
|
description: Generate a tokenised link to share a playlist (read-only). Only
|
|
owner / admin can issue. No body required.
|
|
parameters:
|
|
- description: Playlist UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
share:
|
|
type: object
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"403":
|
|
description: Not owner
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: Playlist not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Create playlist share link
|
|
tags:
|
|
- Playlist
|
|
/playlists/{id}/tracks:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Add a track to the playlist
|
|
parameters:
|
|
- description: Playlist ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- description: Track ID (in body)
|
|
in: body
|
|
name: trackId
|
|
required: true
|
|
schema:
|
|
properties:
|
|
track_id:
|
|
type: string
|
|
type: object
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Track already present or invalid ID
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: Playlist or Track not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Add Track to Playlist
|
|
tags:
|
|
- Playlist
|
|
/playlists/{id}/tracks/{trackId}:
|
|
delete:
|
|
consumes:
|
|
- application/json
|
|
description: Remove a track from the playlist
|
|
parameters:
|
|
- description: Playlist ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- description: Track ID
|
|
in: path
|
|
name: trackId
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"404":
|
|
description: Playlist or Track not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Remove Track from Playlist
|
|
tags:
|
|
- Playlist
|
|
/playlists/{id}/tracks/reorder:
|
|
put:
|
|
consumes:
|
|
- application/json
|
|
description: Reorder tracks in the playlist
|
|
parameters:
|
|
- description: Playlist ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- description: New Track Order
|
|
in: body
|
|
name: order
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.ReorderTracksRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Reorder Tracks
|
|
tags:
|
|
- Playlist
|
|
/playlists/favoris:
|
|
get:
|
|
description: Returns the authenticated user's "Favoris" playlist. Auto-created
|
|
on first call. Used by the like-as-save pattern.
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
playlist:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.Playlist'
|
|
type: object
|
|
type: object
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Get Favoris playlist
|
|
tags:
|
|
- Playlist
|
|
/playlists/import:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Create a playlist from a JSON payload (title, description, is_public,
|
|
ordered track IDs). Useful for bulk seed / migration.
|
|
parameters:
|
|
- description: Playlist + tracks
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.ImportPlaylistRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"201":
|
|
description: Created
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
playlist:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.Playlist'
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Import playlist
|
|
tags:
|
|
- Playlist
|
|
/playlists/recommendations:
|
|
get:
|
|
description: Suggested playlists for the authenticated user. Chronological /
|
|
declarative discovery — no behavioural ranking (CLAUDE.md rule 7).
|
|
parameters:
|
|
- default: 20
|
|
description: Max items (max 100)
|
|
in: query
|
|
name: limit
|
|
type: integer
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
playlists:
|
|
items:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.Playlist'
|
|
type: array
|
|
type: object
|
|
type: object
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Get playlist recommendations
|
|
tags:
|
|
- Playlist
|
|
/playlists/search:
|
|
get:
|
|
description: Full-text search on public playlists (title + description). Paginated.
|
|
parameters:
|
|
- description: Full-text query
|
|
in: query
|
|
name: q
|
|
type: string
|
|
- default: 1
|
|
description: Page number
|
|
in: query
|
|
name: page
|
|
type: integer
|
|
- default: 20
|
|
description: Items per page (max 100)
|
|
in: query
|
|
name: limit
|
|
type: integer
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
pagination:
|
|
type: object
|
|
playlists:
|
|
items:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.Playlist'
|
|
type: array
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
summary: Search playlists
|
|
tags:
|
|
- Playlist
|
|
/playlists/shared/{token}:
|
|
get:
|
|
description: Public endpoint resolving a share token. Allows unauthenticated
|
|
access to the playlist snapshot + tracks.
|
|
parameters:
|
|
- description: Share token
|
|
in: path
|
|
name: token
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
playlist:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.Playlist'
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Missing token
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"403":
|
|
description: Share expired
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: Share or playlist not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
summary: Get playlist by share token
|
|
tags:
|
|
- Playlist
|
|
/queue:
|
|
delete:
|
|
consumes:
|
|
- application/json
|
|
description: Removes every item from the authenticated user's playback queue
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: Queue cleared
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Clear queue
|
|
tags:
|
|
- Queue
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Returns the authenticated user's persistent playback queue with
|
|
all items in position order
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: Queue + items
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
items:
|
|
items:
|
|
type: object
|
|
type: array
|
|
queue:
|
|
type: object
|
|
type: object
|
|
type: object
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Get user playback queue
|
|
tags:
|
|
- Queue
|
|
put:
|
|
consumes:
|
|
- application/json
|
|
description: Updates the authenticated user's queue state (current track / position
|
|
/ playback flags / item order)
|
|
parameters:
|
|
- description: Queue update payload
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_services.UpdateQueueRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: Updated queue
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
items:
|
|
items:
|
|
type: object
|
|
type: array
|
|
queue:
|
|
type: object
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Update user playback queue
|
|
tags:
|
|
- Queue
|
|
/queue/items:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Appends a track to the authenticated user's playback queue
|
|
parameters:
|
|
- description: Track to enqueue
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.AddQueueItemRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"201":
|
|
description: Created queue item
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
item:
|
|
type: object
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Add track to queue
|
|
tags:
|
|
- Queue
|
|
/queue/items/{id}:
|
|
delete:
|
|
consumes:
|
|
- application/json
|
|
description: Removes a single item from the authenticated user's playback queue
|
|
by item ID
|
|
parameters:
|
|
- description: Queue item ID (UUID)
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: Item removed
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid item ID
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: Queue item not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Remove queue item
|
|
tags:
|
|
- Queue
|
|
/queue/session:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Creates a shared queue session and returns its share token + URL.
|
|
The session creator is recorded as host.
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"201":
|
|
description: Created session
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
session:
|
|
type: object
|
|
share_token:
|
|
type: string
|
|
share_url:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Create collaborative queue session
|
|
tags:
|
|
- Queue
|
|
/queue/session/{token}:
|
|
delete:
|
|
consumes:
|
|
- application/json
|
|
description: Deletes a collaborative queue session. Only the original session
|
|
creator can delete.
|
|
parameters:
|
|
- description: Session share token
|
|
in: path
|
|
name: token
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: Session deleted
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Token required
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"403":
|
|
description: Only the creator can delete this session
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: Session not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Delete queue session
|
|
tags:
|
|
- Queue
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Returns the session metadata + items for a given share token. No
|
|
auth required (public — anyone with the link can join).
|
|
parameters:
|
|
- description: Session share token
|
|
in: path
|
|
name: token
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: Session and queue items
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
items:
|
|
items:
|
|
type: object
|
|
type: array
|
|
session:
|
|
type: object
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Token required
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: Session not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
summary: Get queue session by share token
|
|
tags:
|
|
- Queue
|
|
/queue/session/{token}/items:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Adds a track to a collaborative queue session. Anyone with the
|
|
share token can add.
|
|
parameters:
|
|
- description: Session share token
|
|
in: path
|
|
name: token
|
|
required: true
|
|
type: string
|
|
- description: Track to enqueue
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.AddToSessionRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"201":
|
|
description: Updated session and items
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
items:
|
|
items:
|
|
type: object
|
|
type: array
|
|
session:
|
|
type: object
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: Session not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Add track to queue session
|
|
tags:
|
|
- Queue
|
|
/queue/session/{token}/items/{id}:
|
|
delete:
|
|
consumes:
|
|
- application/json
|
|
description: Removes an item from a collaborative queue session by item ID
|
|
parameters:
|
|
- description: Session share token
|
|
in: path
|
|
name: token
|
|
required: true
|
|
type: string
|
|
- description: Queue item ID (UUID)
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: Item removed
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: Session or item not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Remove item from queue session
|
|
tags:
|
|
- Queue
|
|
/search:
|
|
get:
|
|
description: Postgres FTS-backed search across tracks, users, and playlists.
|
|
Optional `type` filter accepts repeated values (e.g., ?type=track&type=user).
|
|
v1.0.9 item 1.6 — annotation added so orval can generate a typed client.
|
|
parameters:
|
|
- description: Search query
|
|
in: query
|
|
name: q
|
|
required: true
|
|
type: string
|
|
- collectionFormat: multi
|
|
description: 'Restrict to one or more entity types: track, user, playlist'
|
|
in: query
|
|
items:
|
|
type: string
|
|
name: type
|
|
type: array
|
|
- description: Opaque pagination cursor
|
|
in: query
|
|
name: cursor
|
|
type: string
|
|
- description: Page size (max 50)
|
|
in: query
|
|
name: limit
|
|
type: integer
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: Search results
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"400":
|
|
description: Validation error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Search failed
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
summary: Unified search
|
|
tags:
|
|
- Search
|
|
/search/suggestions:
|
|
get:
|
|
description: Lightweight autocomplete used by the search bar. Returns a small
|
|
SearchResult subset (typically tracks + users + playlists), capped at `limit`
|
|
(1..20, default 5). v1.0.9 item 1.6 — annotation added so orval can generate
|
|
a typed client.
|
|
parameters:
|
|
- description: Partial query (min 1 char)
|
|
in: query
|
|
name: q
|
|
required: true
|
|
type: string
|
|
- description: Max number of suggestions (1..20, default 5)
|
|
in: query
|
|
name: limit
|
|
type: integer
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: Suggestions
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"400":
|
|
description: Validation error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Suggestions failed
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
summary: Search suggestions
|
|
tags:
|
|
- Search
|
|
/social/trending:
|
|
get:
|
|
description: Returns the top hashtags surfacing in posts published recently.
|
|
Counts are aggregated, not user-personalised — discovery is by declarative
|
|
tags, not behavioural ranking (cf. CLAUDE.md rule 7). v1.0.9 item 1.6 — annotation
|
|
added so orval can generate a typed client.
|
|
parameters:
|
|
- description: Max tags to return (1..50, default 10)
|
|
in: query
|
|
name: limit
|
|
type: integer
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: Trending tags
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Failed to compute trending
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
summary: Trending hashtags
|
|
tags:
|
|
- Social
|
|
/tracks:
|
|
get:
|
|
description: List tracks with pagination, filters, sort. Cursor-based when ?cursor
|
|
provided, otherwise page/limit offset.
|
|
parameters:
|
|
- description: Opaque pagination cursor (overrides page)
|
|
in: query
|
|
name: cursor
|
|
type: string
|
|
- default: 1
|
|
description: Page number, 1-based (ignored if cursor set)
|
|
in: query
|
|
name: page
|
|
type: integer
|
|
- default: 20
|
|
description: Items per page (max 100)
|
|
in: query
|
|
name: limit
|
|
type: integer
|
|
- description: Filter by creator UUID
|
|
in: query
|
|
name: user_id
|
|
type: string
|
|
- description: Filter by genre
|
|
in: query
|
|
name: genre
|
|
type: string
|
|
- description: Filter by audio format (mp3, flac, wav, ogg, m4a, aac)
|
|
in: query
|
|
name: format
|
|
type: string
|
|
- default: created_at
|
|
description: Sort column (created_at, play_count, title)
|
|
in: query
|
|
name: sort_by
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
pagination:
|
|
type: object
|
|
tracks:
|
|
items:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.Track'
|
|
type: array
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid query params
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
summary: List tracks
|
|
tags:
|
|
- Track
|
|
post:
|
|
consumes:
|
|
- multipart/form-data
|
|
description: Upload a new track (audio file)
|
|
parameters:
|
|
- description: Audio File (MP3, WAV, FLAC, OGG)
|
|
in: formData
|
|
name: file
|
|
required: true
|
|
type: file
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"201":
|
|
description: Created
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
track:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.Track'
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: No file or validation error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"403":
|
|
description: Quota exceeded
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Upload Track
|
|
tags:
|
|
- Track
|
|
/tracks/{id}:
|
|
delete:
|
|
description: Soft-delete a track (sets deleted_at). Caller must own the track
|
|
or be admin.
|
|
parameters:
|
|
- description: Track UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid track id
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"403":
|
|
description: Not owner / no admin
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"404":
|
|
description: Track not found
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Delete track
|
|
tags:
|
|
- Track
|
|
get:
|
|
description: Retrieve a single track. Private play_count / like_count are omitted
|
|
for non-owners (v0.10.3 F202).
|
|
parameters:
|
|
- description: Track UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
track:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.Track'
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid track id
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"404":
|
|
description: Track not found
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
summary: Get track by ID
|
|
tags:
|
|
- Track
|
|
put:
|
|
consumes:
|
|
- application/json
|
|
description: Update the metadata of an existing track. Caller must own the track
|
|
or be admin.
|
|
parameters:
|
|
- description: Track UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- description: Updated metadata
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_core_track.UpdateTrackRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
track:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.Track'
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation / invalid id
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"403":
|
|
description: Not owner / no admin
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"404":
|
|
description: Track not found
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Update track metadata
|
|
tags:
|
|
- Track
|
|
/tracks/{id}/comments:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Get paginated list of comments for a track
|
|
parameters:
|
|
- description: Track ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- default: 1
|
|
description: Page number
|
|
in: query
|
|
name: page
|
|
type: integer
|
|
- default: 20
|
|
description: Items per page
|
|
in: query
|
|
name: limit
|
|
type: integer
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
comments:
|
|
type: array
|
|
pagination:
|
|
type: object
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: Track not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal server error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
summary: Get track comments
|
|
tags:
|
|
- Comment
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Create a new comment on a track. Can be a top-level comment or
|
|
a reply to another comment (using parent_id).
|
|
parameters:
|
|
- description: Track ID (UUID)
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- description: Comment data
|
|
in: body
|
|
name: comment
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.CreateCommentRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"201":
|
|
description: Created
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
comment:
|
|
type: object
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: Track not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal server error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Create comment
|
|
tags:
|
|
- Comment
|
|
/tracks/{id}/comments/{comment_id}:
|
|
delete:
|
|
consumes:
|
|
- application/json
|
|
description: Delete a comment (only by owner or admin)
|
|
parameters:
|
|
- description: Track ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- description: Comment ID
|
|
in: path
|
|
name: comment_id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"403":
|
|
description: Forbidden - not comment owner
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: Comment not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Delete comment
|
|
tags:
|
|
- Comment
|
|
/tracks/{id}/download:
|
|
get:
|
|
description: Serve the original audio file. For S3-backed tracks returns a 302
|
|
redirect to a signed URL (TTL 30min). For local-backed tracks streams the
|
|
file with Range support. Public tracks or share_token access; paid tracks
|
|
require a license.
|
|
parameters:
|
|
- description: Track UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- description: Grants access without authentication for a limited time
|
|
in: query
|
|
name: share_token
|
|
type: string
|
|
produces:
|
|
- application/octet-stream
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
type: file
|
|
"302":
|
|
description: Location header points to signed S3 URL (s3-backed tracks)
|
|
schema:
|
|
type: string
|
|
"400":
|
|
description: Invalid track id
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"403":
|
|
description: No permission / license required
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"404":
|
|
description: Track or file not found
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
summary: Download a track
|
|
tags:
|
|
- Track
|
|
/tracks/{id}/history:
|
|
get:
|
|
description: Paginated audit log of modifications (metadata updates, version
|
|
changes) for a track.
|
|
parameters:
|
|
- description: Track UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- default: 50
|
|
description: Items per page
|
|
in: query
|
|
name: limit
|
|
type: integer
|
|
- default: 0
|
|
description: Offset
|
|
in: query
|
|
name: offset
|
|
type: integer
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
history:
|
|
items:
|
|
type: object
|
|
type: array
|
|
limit:
|
|
type: integer
|
|
offset:
|
|
type: integer
|
|
total:
|
|
type: integer
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid track id
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"404":
|
|
description: Track not found
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
summary: Get track history
|
|
tags:
|
|
- Track
|
|
/tracks/{id}/like:
|
|
delete:
|
|
description: Remove the authenticated user's like on the track (idempotent).
|
|
parameters:
|
|
- description: Track UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid track id
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Unlike a track
|
|
tags:
|
|
- Track
|
|
post:
|
|
description: Record a like from the authenticated user. Creates a grouped notification
|
|
for the creator (F554).
|
|
parameters:
|
|
- description: Track UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid track id
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"404":
|
|
description: Track not found
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Like a track
|
|
tags:
|
|
- Track
|
|
/tracks/{id}/likes:
|
|
get:
|
|
description: Returns whether the current user has liked the track. The total
|
|
like count is returned ONLY to the creator or an admin (privacy per ORIGIN_UI_UX_SYSTEM
|
|
§13).
|
|
parameters:
|
|
- description: Track UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: count is omitted for non-owners
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
count:
|
|
type: integer
|
|
is_liked:
|
|
type: boolean
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid track id
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"404":
|
|
description: Track not found
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Get track like status
|
|
tags:
|
|
- Track
|
|
/tracks/{id}/lyrics:
|
|
get:
|
|
description: Returns the current lyrics for a track, or null if no lyrics exist.
|
|
parameters:
|
|
- description: Track UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: lyrics may be null
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
lyrics:
|
|
type: object
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid track id
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"404":
|
|
description: Track not found
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
summary: Get track lyrics
|
|
tags:
|
|
- Track
|
|
put:
|
|
consumes:
|
|
- application/json
|
|
description: Replace the lyrics of a track. Caller must own the track or be
|
|
admin.
|
|
parameters:
|
|
- description: Track UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- description: Lyrics payload
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_core_track.UpdateLyricsRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
lyrics:
|
|
type: object
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation / invalid id
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"403":
|
|
description: Not owner / no admin
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"404":
|
|
description: Track not found
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Create or update track lyrics
|
|
tags:
|
|
- Track
|
|
/tracks/{id}/play:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Persist a playback event with optional play_time so the creator's
|
|
analytics dashboard tracks listening behaviour.
|
|
parameters:
|
|
- description: Track UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- description: Playback metadata (optional)
|
|
in: body
|
|
name: request
|
|
schema:
|
|
$ref: '#/definitions/internal_core_track.RecordPlayRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
id:
|
|
type: string
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid track id / body
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"404":
|
|
description: Track not found
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Record play event
|
|
tags:
|
|
- Track
|
|
/tracks/{id}/repost:
|
|
delete:
|
|
description: Remove the authenticated user's repost of the track (idempotent).
|
|
parameters:
|
|
- description: Track UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid track id
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Remove track repost
|
|
tags:
|
|
- Track
|
|
get:
|
|
description: Returns whether the current user has reposted the track. Public
|
|
(optional auth); unauthenticated callers get is_reposted=false.
|
|
parameters:
|
|
- description: Track UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
is_reposted:
|
|
type: boolean
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid track id
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
summary: Get repost status
|
|
tags:
|
|
- Track
|
|
post:
|
|
description: Add a track to the authenticated user's profile as a repost. Notifies
|
|
the creator (F204) unless self-repost.
|
|
parameters:
|
|
- description: Track UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid track id
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"404":
|
|
description: Track not found
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Repost a track
|
|
tags:
|
|
- Track
|
|
/tracks/{id}/share:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Generate a tokenized share link for a track with given permission
|
|
level and optional expiry.
|
|
parameters:
|
|
- description: Track UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- description: Share parameters
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_core_track.CreateShareRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
share:
|
|
type: object
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"403":
|
|
description: Not owner
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"404":
|
|
description: Track not found
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Create share link
|
|
tags:
|
|
- Track
|
|
/tracks/{id}/stats:
|
|
get:
|
|
description: 'Aggregated track stats: views, likes, comments, play time, downloads,
|
|
average duration.'
|
|
parameters:
|
|
- description: Track UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
stats:
|
|
type: object
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid track id
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"404":
|
|
description: Track not found
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
summary: Get track statistics
|
|
tags:
|
|
- Track
|
|
/tracks/{id}/status:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Get the processing status of an uploaded track
|
|
parameters:
|
|
- description: Track ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
progress:
|
|
type: integer
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid ID
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"404":
|
|
description: Track not found
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Get Upload Status
|
|
tags:
|
|
- Track
|
|
/tracks/{id}/stream:
|
|
get:
|
|
description: Default playback path. S3-backed tracks return a 302 redirect to
|
|
a signed URL (TTL 15min). Local-backed tracks are streamed via http.ServeContent
|
|
with Range support. Always available, unlike /hls/* which is gated by HLSEnabled.
|
|
parameters:
|
|
- description: Track UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- description: Grants access without authentication
|
|
in: query
|
|
name: share_token
|
|
type: string
|
|
produces:
|
|
- audio/*
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
type: file
|
|
"302":
|
|
description: Location header points to signed S3 URL (s3-backed tracks)
|
|
schema:
|
|
type: string
|
|
"400":
|
|
description: Invalid track id
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"403":
|
|
description: No permission
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"404":
|
|
description: Track or file not found
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
summary: Stream a track (raw audio + Range)
|
|
tags:
|
|
- Track
|
|
/tracks/{id}/versions/{versionId}/restore:
|
|
post:
|
|
description: Rollback a track to a previous version. Only the track owner can
|
|
restore.
|
|
parameters:
|
|
- description: Track UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- description: Version UUID
|
|
in: path
|
|
name: versionId
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid id
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"403":
|
|
description: Not owner
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"404":
|
|
description: Track or version not found
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Restore track version
|
|
tags:
|
|
- Track
|
|
/tracks/{id}/waveform:
|
|
get:
|
|
description: Returns a JSON peaks array used by the client to draw the audio
|
|
waveform preview. 404 if waveform extraction is not complete yet.
|
|
parameters:
|
|
- description: Track UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: Waveform peaks JSON (tool-specific shape)
|
|
schema:
|
|
type: object
|
|
"400":
|
|
description: Invalid track id
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"404":
|
|
description: Waveform not generated / track not found
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
summary: Get track waveform
|
|
tags:
|
|
- Track
|
|
/tracks/batch/delete:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Soft-delete up to N tracks in one request. Per-track ownership
|
|
checked (admin can delete others).
|
|
parameters:
|
|
- description: List of track UUIDs
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_core_track.BatchDeleteRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
deleted:
|
|
items:
|
|
type: string
|
|
type: array
|
|
failed:
|
|
items:
|
|
type: object
|
|
type: array
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation / batch size exceeded
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Batch delete tracks
|
|
tags:
|
|
- Track
|
|
/tracks/batch/update:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Apply a partial metadata update to up to N tracks in one request.
|
|
Per-track ownership checked.
|
|
parameters:
|
|
- description: Track UUIDs + shared updates map
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_core_track.BatchUpdateRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
failed:
|
|
items:
|
|
type: object
|
|
type: array
|
|
updated:
|
|
items:
|
|
type: string
|
|
type: array
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation / batch size exceeded
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Batch update tracks
|
|
tags:
|
|
- Track
|
|
/tracks/chunk:
|
|
post:
|
|
consumes:
|
|
- multipart/form-data
|
|
description: Upload a single chunk of a file
|
|
parameters:
|
|
- description: Chunk Data
|
|
in: formData
|
|
name: chunk
|
|
required: true
|
|
type: file
|
|
- description: Upload ID
|
|
in: formData
|
|
name: upload_id
|
|
required: true
|
|
type: string
|
|
- description: Chunk Number
|
|
in: formData
|
|
name: chunk_number
|
|
required: true
|
|
type: integer
|
|
- description: Total Chunks
|
|
in: formData
|
|
name: total_chunks
|
|
required: true
|
|
type: integer
|
|
- description: Total Size
|
|
format: int64
|
|
in: formData
|
|
name: total_size
|
|
required: true
|
|
type: integer
|
|
- description: Filename
|
|
in: formData
|
|
name: filename
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
progress:
|
|
format: float64
|
|
type: number
|
|
received_chunks:
|
|
type: integer
|
|
upload_id:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Upload Chunk
|
|
tags:
|
|
- Track
|
|
/tracks/complete:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Finish upload session and assemble file
|
|
parameters:
|
|
- description: Upload ID
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_core_track.CompleteChunkedUploadRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"201":
|
|
description: Created
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
md5:
|
|
type: string
|
|
message:
|
|
type: string
|
|
track:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.Track'
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation or Assemblage Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Complete Chunked Upload
|
|
tags:
|
|
- Track
|
|
/tracks/initiate:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Start a new chunked upload session
|
|
parameters:
|
|
- description: Upload Metadata
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_core_track.InitiateChunkedUploadRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
upload_id:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Initiate Chunked Upload
|
|
tags:
|
|
- Track
|
|
/tracks/quota/{id}:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Get remaining upload quota for the user
|
|
parameters:
|
|
- description: User ID or 'me' for current user
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
quota:
|
|
type: object
|
|
type: object
|
|
type: object
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
"403":
|
|
description: Forbidden
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Get Upload Quota
|
|
tags:
|
|
- Track
|
|
/tracks/recommendations:
|
|
get:
|
|
description: Personalized tracks for D2 autoplay. If seed_track_id is given,
|
|
returns tracks similar to that seed. Otherwise, uses the caller's history
|
|
(chronological, no behavioural ranking — CLAUDE.md rule 7).
|
|
parameters:
|
|
- default: 20
|
|
description: Max items (max 100)
|
|
in: query
|
|
name: limit
|
|
type: integer
|
|
- description: Start from this track's similarity neighbours
|
|
in: query
|
|
name: seed_track_id
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
tracks:
|
|
items:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.Track'
|
|
type: array
|
|
type: object
|
|
type: object
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Get track recommendations
|
|
tags:
|
|
- Track
|
|
/tracks/resume/{uploadId}:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Get state of an interrupted upload
|
|
parameters:
|
|
- description: Upload ID
|
|
in: path
|
|
name: uploadId
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
chunks_received:
|
|
type: integer
|
|
upload_id:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"404":
|
|
description: Upload session not found
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Resume Upload
|
|
tags:
|
|
- Track
|
|
/tracks/search:
|
|
get:
|
|
description: Full-text + faceted search on tracks (genre, BPM, duration, tags,
|
|
musical key, dates). Sort-by and order configurable.
|
|
parameters:
|
|
- description: Full-text query (title/artist/album)
|
|
in: query
|
|
name: q
|
|
type: string
|
|
- description: Comma-separated tag list
|
|
in: query
|
|
name: tags
|
|
type: string
|
|
- default: OR
|
|
description: Tag combinator (OR / AND)
|
|
in: query
|
|
name: tag_mode
|
|
type: string
|
|
- description: Minimum duration (seconds)
|
|
in: query
|
|
name: min_duration
|
|
type: integer
|
|
- description: Maximum duration (seconds)
|
|
in: query
|
|
name: max_duration
|
|
type: integer
|
|
- description: Minimum BPM
|
|
in: query
|
|
name: min_bpm
|
|
type: integer
|
|
- description: Maximum BPM
|
|
in: query
|
|
name: max_bpm
|
|
type: integer
|
|
- description: Genre filter
|
|
in: query
|
|
name: genre
|
|
type: string
|
|
- description: Audio format filter
|
|
in: query
|
|
name: format
|
|
type: string
|
|
- description: Musical key filter
|
|
in: query
|
|
name: musical_key
|
|
type: string
|
|
- description: Created-after (RFC3339)
|
|
in: query
|
|
name: min_date
|
|
type: string
|
|
- description: Created-before (RFC3339)
|
|
in: query
|
|
name: max_date
|
|
type: string
|
|
- default: 1
|
|
description: Page (1-based)
|
|
in: query
|
|
name: page
|
|
type: integer
|
|
- default: 20
|
|
description: Items per page (max 100)
|
|
in: query
|
|
name: limit
|
|
type: integer
|
|
- default: created_at
|
|
description: Sort column
|
|
in: query
|
|
name: sort_by
|
|
type: string
|
|
- default: desc
|
|
description: asc / desc
|
|
in: query
|
|
name: sort_order
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
pagination:
|
|
type: object
|
|
tracks:
|
|
items:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.Track'
|
|
type: array
|
|
type: object
|
|
type: object
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
summary: Advanced track search
|
|
tags:
|
|
- Track
|
|
/tracks/share/{id}:
|
|
delete:
|
|
description: Permanently disable a share token. Only the share issuer (or admin)
|
|
can revoke.
|
|
parameters:
|
|
- description: Share UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"403":
|
|
description: Not issuer
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"404":
|
|
description: Share not found
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Revoke share link
|
|
tags:
|
|
- Track
|
|
/tracks/shared/{token}:
|
|
get:
|
|
description: Public endpoint that resolves a share token and returns the track
|
|
+ share metadata. No auth required; the token IS the auth.
|
|
parameters:
|
|
- description: Opaque share token issued by CreateShare
|
|
in: path
|
|
name: token
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
share:
|
|
type: object
|
|
track:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.Track'
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Missing token
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"403":
|
|
description: Share link expired
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"404":
|
|
description: Share or track not found
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
summary: Get track by share token
|
|
tags:
|
|
- Track
|
|
/tracks/suggested-tags:
|
|
get:
|
|
description: Returns a static tag suggestion list for a genre — useful for upload
|
|
autocomplete and filter chips.
|
|
parameters:
|
|
- default: default
|
|
description: Genre slug (pop, rock, electronic, hip-hop, jazz, classical,
|
|
ambient, default)
|
|
in: query
|
|
name: genre
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_response.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
tags:
|
|
items:
|
|
type: string
|
|
type: array
|
|
type: object
|
|
type: object
|
|
summary: Get suggested tags
|
|
tags:
|
|
- Track
|
|
/users:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Get a paginated list of users with optional filtering
|
|
parameters:
|
|
- default: 1
|
|
description: Page number
|
|
in: query
|
|
name: page
|
|
type: integer
|
|
- default: 20
|
|
description: Items per page
|
|
in: query
|
|
name: limit
|
|
type: integer
|
|
- description: Filter by role
|
|
in: query
|
|
name: role
|
|
type: string
|
|
- description: Filter by active status
|
|
in: query
|
|
name: is_active
|
|
type: boolean
|
|
- description: Filter by verified status
|
|
in: query
|
|
name: is_verified
|
|
type: boolean
|
|
- description: Search by username, email, first_name, last_name
|
|
in: query
|
|
name: search
|
|
type: string
|
|
- default: created_at
|
|
description: Sort field (created_at, username, email, last_login_at)
|
|
in: query
|
|
name: sort_by
|
|
type: string
|
|
- default: desc
|
|
description: Sort order (asc, desc)
|
|
in: query
|
|
name: sort_order
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
pagination:
|
|
type: object
|
|
users:
|
|
type: array
|
|
type: object
|
|
type: object
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
summary: List Users
|
|
tags:
|
|
- User
|
|
/users/{id}:
|
|
delete:
|
|
consumes:
|
|
- application/json
|
|
description: Soft delete a user (only user owner or admin can delete)
|
|
parameters:
|
|
- description: User ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: User deleted successfully
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"400":
|
|
description: Invalid ID
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"403":
|
|
description: Forbidden - Not user owner or admin
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: User not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Delete user
|
|
tags:
|
|
- User
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Get public profile information for a user
|
|
parameters:
|
|
- description: User ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
profile:
|
|
type: object
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid ID
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: User not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
summary: Get Profile by ID
|
|
tags:
|
|
- User
|
|
put:
|
|
consumes:
|
|
- application/json
|
|
description: Update user profile details
|
|
parameters:
|
|
- description: User ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- description: Profile Data
|
|
in: body
|
|
name: profile
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.UpdateProfileRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
profile:
|
|
type: object
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"403":
|
|
description: Forbidden
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Update Profile
|
|
tags:
|
|
- User
|
|
/users/{id}/block:
|
|
delete:
|
|
description: Authenticated user unblocks target user (idempotent).
|
|
parameters:
|
|
- description: Target user UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid id
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Unblock user
|
|
tags:
|
|
- User
|
|
post:
|
|
description: Authenticated user blocks target user (hides their content, prevents
|
|
follows). Cannot self-block.
|
|
parameters:
|
|
- description: Target user UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation / self-block
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Block user
|
|
tags:
|
|
- User
|
|
/users/{id}/completion:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Get profile completion percentage and missing fields
|
|
parameters:
|
|
- description: User ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid ID
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"403":
|
|
description: Forbidden
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
summary: Get Profile Completion
|
|
tags:
|
|
- User
|
|
/users/{id}/follow:
|
|
delete:
|
|
description: Authenticated user stops following target user (idempotent).
|
|
parameters:
|
|
- description: Target user UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid id
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Unfollow user
|
|
tags:
|
|
- User
|
|
post:
|
|
description: Authenticated user follows target user. Creates a notification
|
|
(F554 grouped) for the target.
|
|
parameters:
|
|
- description: Target user UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid id
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: User not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Follow user
|
|
tags:
|
|
- User
|
|
/users/{id}/likes:
|
|
get:
|
|
description: Returns paginated tracks the given user has liked. Used for profile
|
|
"Likes" tab.
|
|
parameters:
|
|
- description: User UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- default: 20
|
|
description: Items per page (max 100)
|
|
in: query
|
|
name: limit
|
|
type: integer
|
|
- default: 0
|
|
description: Offset for pagination
|
|
in: query
|
|
name: offset
|
|
type: integer
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
limit:
|
|
type: integer
|
|
offset:
|
|
type: integer
|
|
total:
|
|
type: integer
|
|
tracks:
|
|
items:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.Track'
|
|
type: array
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: List tracks liked by a user
|
|
tags:
|
|
- User
|
|
/users/{id}/reposts:
|
|
get:
|
|
description: Returns paginated tracks the user has reposted. Used for profile
|
|
"Reposts" tab.
|
|
parameters:
|
|
- description: User UUID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
- default: 20
|
|
description: Items per page (max 100)
|
|
in: query
|
|
name: limit
|
|
type: integer
|
|
- default: 0
|
|
description: Offset for pagination
|
|
in: query
|
|
name: offset
|
|
type: integer
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
limit:
|
|
type: integer
|
|
offset:
|
|
type: integer
|
|
total:
|
|
type: integer
|
|
tracks:
|
|
items:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.Track'
|
|
type: array
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/veza-backend-api_internal_handlers.APIResponse'
|
|
summary: List tracks reposted by a user
|
|
tags:
|
|
- User
|
|
/users/by-username/{username}:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Get public profile information for a user by username
|
|
parameters:
|
|
- description: Username
|
|
in: path
|
|
name: username
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
profile:
|
|
type: object
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Missing username
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: User not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
summary: Get Profile by Username
|
|
tags:
|
|
- User
|
|
/users/me:
|
|
delete:
|
|
description: Permanently delete user account with anonymization, session revocation,
|
|
audit log
|
|
parameters:
|
|
- description: Password, reason, confirm_text (must be DELETE)
|
|
in: body
|
|
name: body
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.DeleteAccountRequest'
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
additionalProperties: true
|
|
type: object
|
|
"400":
|
|
description: Bad Request
|
|
schema:
|
|
additionalProperties: true
|
|
type: object
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
additionalProperties: true
|
|
type: object
|
|
"500":
|
|
description: Internal Server Error
|
|
schema:
|
|
additionalProperties: true
|
|
type: object
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Delete account
|
|
tags:
|
|
- Users
|
|
/users/me/privacy/opt-out:
|
|
post:
|
|
description: Saves the user's Do Not Sell preference (CCPA compliance)
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
additionalProperties: true
|
|
type: object
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
additionalProperties: true
|
|
type: object
|
|
"500":
|
|
description: Internal Server Error
|
|
schema:
|
|
additionalProperties: true
|
|
type: object
|
|
security:
|
|
- BearerAuth: []
|
|
summary: CCPA Do Not Sell opt-out
|
|
tags:
|
|
- Users
|
|
/users/search:
|
|
get:
|
|
description: Full-text search on users (username, display_name). Paginated.
|
|
Public.
|
|
parameters:
|
|
- description: Full-text query
|
|
in: query
|
|
name: q
|
|
type: string
|
|
- default: 1
|
|
description: Page
|
|
in: query
|
|
name: page
|
|
type: integer
|
|
- default: 20
|
|
description: Items per page (max 100)
|
|
in: query
|
|
name: limit
|
|
type: integer
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
pagination:
|
|
type: object
|
|
users:
|
|
items:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.User'
|
|
type: array
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation (bounds)
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
summary: Search users
|
|
tags:
|
|
- User
|
|
/users/suggestions:
|
|
get:
|
|
description: Returns suggested users to follow for the authenticated user. Declarative
|
|
discovery — no behavioural scoring (CLAUDE.md rule 7).
|
|
parameters:
|
|
- default: 10
|
|
description: Max items (max 50)
|
|
in: query
|
|
name: limit
|
|
type: integer
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
users:
|
|
items:
|
|
$ref: '#/definitions/veza-backend-api_internal_models.User'
|
|
type: array
|
|
type: object
|
|
type: object
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal Error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Get follow suggestions
|
|
tags:
|
|
- User
|
|
/validate:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Validates request data against known DTO types without executing
|
|
the actual operation
|
|
parameters:
|
|
- description: Validation request with type and data
|
|
in: body
|
|
name: request
|
|
required: true
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.ValidateRequest'
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: Validation result
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.ValidateResponse'
|
|
"400":
|
|
description: Invalid request format
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
summary: Validate request body
|
|
tags:
|
|
- Validation
|
|
/webhooks:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Get a list of all webhooks registered by the current user
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
webhooks:
|
|
type: array
|
|
type: object
|
|
type: object
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal server error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: List webhooks
|
|
tags:
|
|
- Webhook
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Register a new webhook for receiving events
|
|
parameters:
|
|
- description: Webhook registration data
|
|
in: body
|
|
name: webhook
|
|
required: true
|
|
schema:
|
|
type: object
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"201":
|
|
description: Created
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
webhook:
|
|
type: object
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Validation error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal server error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Register webhook
|
|
tags:
|
|
- Webhook
|
|
/webhooks/{id}:
|
|
delete:
|
|
consumes:
|
|
- application/json
|
|
description: Delete a webhook by ID
|
|
parameters:
|
|
- description: Webhook ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid webhook ID
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: Webhook not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Delete webhook
|
|
tags:
|
|
- Webhook
|
|
/webhooks/{id}/regenerate-key:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Generate a new API key for a webhook (invalidates the old one)
|
|
parameters:
|
|
- description: Webhook ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
api_key:
|
|
type: string
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid webhook ID
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: Webhook not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal server error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Regenerate webhook API key
|
|
tags:
|
|
- Webhook
|
|
/webhooks/{id}/test:
|
|
post:
|
|
consumes:
|
|
- application/json
|
|
description: Send a test event to a webhook to verify it's working
|
|
parameters:
|
|
- description: Webhook ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
type: string
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
message:
|
|
type: string
|
|
type: object
|
|
type: object
|
|
"400":
|
|
description: Invalid webhook ID
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"404":
|
|
description: Webhook not found
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Test webhook
|
|
tags:
|
|
- Webhook
|
|
/webhooks/stats:
|
|
get:
|
|
consumes:
|
|
- application/json
|
|
description: Get statistics for webhook delivery and performance
|
|
produces:
|
|
- application/json
|
|
responses:
|
|
"200":
|
|
description: OK
|
|
schema:
|
|
allOf:
|
|
- $ref: '#/definitions/internal_handlers.APIResponse'
|
|
- properties:
|
|
data:
|
|
properties:
|
|
stats:
|
|
type: object
|
|
type: object
|
|
type: object
|
|
"401":
|
|
description: Unauthorized
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
"500":
|
|
description: Internal server error
|
|
schema:
|
|
$ref: '#/definitions/internal_handlers.APIResponse'
|
|
security:
|
|
- BearerAuth: []
|
|
summary: Get webhook statistics
|
|
tags:
|
|
- Webhook
|
|
securityDefinitions:
|
|
ApiKeyAuth:
|
|
description: 'Developer API key (obtain from Developer Portal). Format: vza_xxxxx'
|
|
in: header
|
|
name: X-API-Key
|
|
type: apiKey
|
|
BearerAuth:
|
|
in: header
|
|
name: Authorization
|
|
type: apiKey
|
|
swagger: "2.0"
|