Enums & Vocabularies
The controlled values used across the API. All are defined in @swayzio/domain.
Visibility & access
| Enum | Values |
|---|---|
| Track visibility | private, library, pack_public |
| Pack visibility | private, link, public |
| Pack access level | private, public_view, public_collaborate |
| Pack access type | listener, collaborator, admin, revoked |
| Library share access | viewer, editor, admin, revoked |
| Invite status | pending, accepted, declined, expired, revoked |
Assets, uploads & jobs
| Enum | Values |
|---|---|
| Asset kind | original_audio, waveform_png, peaks_json, lyrics_json, stem, draft, cover_art, document |
| Upload intent | track_original, stem, draft, track_artwork, track_document |
| Job status | queued, running, deferred, succeeded, failed, cancelled |
| Processing stage type | upload, audio_probe, waveform_peaks, tagging, stem_separation, lyric_transcription, semantic_enrichment, embedding |
| Track readiness status | uploading, processing, playable, tagged, ready, ready_with_warnings, failed |
| Readiness check status | ready, processing, deferred, failed, missing, not_started, unchecked |
| Ingestion run status | queued, running, core_ready, succeeded, failed |
Tags & rights
| Enum | Values |
|---|---|
| Machine tag source | audio_worker, swayzio_tagger, tinymu, vertex_ai, user_import, legacy_migration |
| Tag curation status | accepted, rejected, hidden |
| Collaborator role | writer, publisher, master_owner |
| Collaborator entity type | person, company |
| Rights entry type | writer, publisher, sub_publisher, master_owner |
| Split‑sheet category | master, writer, publisher, sub_publisher |
| Split‑sheet PRO | BMI, ASCAP, SESAC, PRS, SOCAN, GEMA, None |
| Split‑sheet writer role | Songwriter, Producer, Engineer, Composer, Other |
| Split‑sheet territory | Worldwide + 19 named regions (US, Canada, UK, …, Rest of World) |
Analytics (Dub)
| Enum | Values |
|---|---|
| Event type | clicks, leads, sales, composite |
| Group by | count, timeseries, continents, countries, regions, cities, devices, browsers, os, triggers, referers, referer_urls, top_links, top_urls |
| Interval | 24h, 7d, 30d, 90d, mtd, qtd, ytd, 1y, all |
| Unavailable reason | dub_disabled, plan_gated, rate_limited, provider_error |
Billing
| Enum | Values |
|---|---|
| Entitlement status | active, canceled, free, incomplete, past_due, trialing, unpaid |
Plan IDs are not a fixed enum. They’re server‑driven string values; the
live set for an account is returned in billingStatusResponseSchema.availablePlanIds.
Events
The product event log (eventTypeSchema) spans 40+ values, grouped by entity:
- Track —
track.uploaded,.viewed,.played,.downloaded,.saved,.shared,.updated,.deleted - Pack —
pack.created,.viewed,.played,.downloaded,.saved,.unsaved,.shared,.updated,.deleted,.track_added,.track_removed,.track_reordered,.share_link.created,.tracking_link.opened,.invitation.sent/.accepted/.revoked - Library —
library.created,.updated,.deleted,.track_added,.track_removed,.shared,.invitation.* - External (Dub) —
external_link.clicked,external_link.lead,external_link.sale,external_tracking_link.opened - Other —
search.executed,agent.suggested/.approved/.rejected
Media intelligence & embeddings
| Enum | Values |
|---|---|
| Media‑intelligence lane | tags, stems, lyrics, search_context |
| Aggregate status | accepted, queued, running, succeeded, partial, failed, cancelled |
| Audio embedding model | muq (1024‑dim), mulan (512‑dim) |
Agent tools
| Enum | Values |
|---|---|
| Tool catalog (12) | queryAgentContext, searchTracks, getTrackContext, getRightsContext, createPackDraft, suggestTags, findMissingMetadata, suggestProcessingRetries, summarizeCatalog, explainTrackUsage, listPacks, addTrackToPack |
| Executable (7 live) | searchTracks, getTrackContext, getRightsContext, findMissingMetadata, suggestProcessingRetries, listPacks, addTrackToPack |
| Read/write class | read, write, mutating_suggestion, destructive, outbound, billing |
| Data access tier | static_api_contract, brokered_query_tool, internal_exploratory_agent, conversational_analytics, managed_mcp_tool, custom_hosted_mcp_tool |
Musical keys
musicalKey is a normalized string (not a strict enum). Canonical forms: 12
minor keys (Abm, Ebm, Bbm, Fm, Cm, Gm, Dm, Am, Em, Bm, F#m, C#m) and 12 major
keys (B, F#, Db, Ab, Eb, Bb, F, C, G, D, A, E). The normalizer accepts Camelot
notation (8A / 8B), "C major" / "A minor", shorthand (Am), and bare
(C); the display form is "C major" / "A minor".