3dc0654a52
Second batch of the Veza backend OpenAPI annotation campaign. Completes
the track/ handler subtree — 22 more handlers annotated across 5 files —
so the orval-generated frontend client now covers the full track API
surface (stream, download, like, repost, share, search, recommendations,
stats, history, play, waveform, version restore).
Handlers annotated:
- internal/core/track/track_social_handler.go (11):
LikeTrack, UnlikeTrack, GetTrackLikes, GetUserLikedTracks,
GetUserRepostedTracks, CreateShare, GetSharedTrack, RevokeShare,
RepostTrack, UnrepostTrack, GetRepostStatus
- internal/core/track/track_analytics_handler.go (4):
GetTrackStats, GetTrackHistory, RecordPlay, RestoreVersion
- internal/core/track/track_search_handler.go (3):
GetRecommendations, GetSuggestedTags, SearchTracks
- internal/core/track/track_hls_handler.go (3):
HandleStreamCallback (internal), DownloadTrack, StreamTrack
— both user-facing endpoints document the v1.0.8 P2 302-to-signed-URL
behavior for S3-backed tracks alongside the local-FS path.
- internal/core/track/track_waveform_handler.go (1): GetWaveform
All comment blocks converge on the established template:
Summary / Description / Tags / Accept/Produce / Security (BearerAuth
when required) / typed Param path|query|body / Success envelope
handlers.APIResponse{data=...} / Failure 400/401/403/404/500 / Router.
track_hls_handler.go + track_waveform_handler.go receive a blank
import of internal/handlers so swaggo's type resolver can locate
handlers.APIResponse without forcing the file to call that package
at runtime.
Spec coverage:
/tracks/* paths: 13 → 29
make openapi: ✅ valid (Swagger 2.0)
go build ./...: ✅
openapi.yaml: +780 lines describing 16 new track endpoints.
Leaves /internal/core/ subsystems still blank: admin, moderation,
analytics/*, auth/handler.go (duplicates routes handled elsewhere),
discover, feed. Batch 2b next will cover playlists + marketplace gap
so the 4 frontend services (auth/users/tracks/playlists) become
fully orval-migratable.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
5041 lines
137 KiB
YAML
5041 lines
137 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.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.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.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.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
|
|
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:
|
|
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.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
|
|
host: localhost:18080
|
|
info:
|
|
contact:
|
|
email: support@veza.app
|
|
name: API Support
|
|
url: http://www.veza.app/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/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
|
|
parameters:
|
|
- description: Verification Token
|
|
in: query
|
|
name: token
|
|
required: true
|
|
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
|
|
/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}/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
|
|
/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}/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}/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
|
|
/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"
|