Internal & Service-to-Service
These surfaces are not for end‑user integrators — they connect Swayzio’s own services (Trigger.dev jobs, Vercel Cron, the worker, and the Modal media‑intelligence cluster). They are documented for operators and platform engineers. Every one authenticates with a fail‑closed bearer secret or a signed callback, and none accepts an owner from request input.
Internal HTTP endpoints
Base path /api/swayzio/v1/internal. All nodejs runtime, native‑only (never
proxied).
| Method | Path | Auth (Bearer secret) | Purpose |
|---|---|---|---|
| POST | /internal/catalog-drain/eligible | SWAYZIO_TRIGGER_CALLBACK_SECRET | Page drain‑eligible tracks by owner or plan ids ({ items, nextCursor }) |
| POST | /internal/catalog-drain/dispatch | SWAYZIO_TRIGGER_CALLBACK_SECRET | Re‑check eligibility, then dispatch stems+lyrics backfill for one track |
| GET / POST | /internal/audio-embeddings/drain | CRON_SECRET | Vercel Cron‑facing audio‑embedding backfill drain |
| POST | /internal/workflows/trigger-status | SWAYZIO_TRIGGER_CALLBACK_SECRET | Record a Trigger.dev workflow status into the outbox |
| POST | /observability/self-test | env‑flag gated (404 outside dev/preview) | Fire a controlled Sentry message + exception |
Each secret‑gated endpoint returns 401 when its secret env var is unset — it
fails closed rather than allowing the request through. Note the three distinct
secret namespaces (SWAYZIO_TRIGGER_CALLBACK_SECRET, CRON_SECRET,
MEDIA_INTELLIGENCE_CALLBACK_SECRET) — easy to misconfigure.
Media‑intelligence callback (Modal → Core)
POST /api/swayzio/v1/media-intelligence/callback
- Auth:
Authorization: Bearer <MEDIA_INTELLIGENCE_CALLBACK_SECRET>(timing‑safe compare; fails closed) plusx-swayzio-contract-versionmust equal the pinnedmediaIntelligenceContractVersion(400on mismatch). - Body:
mediaIntelligenceCallbackRequestSchema— applies the tags / stems / lyrics lanes computed by the Modal worker. - Persists: machine tags + bpm/key/duration, stem assets (with storage‑object verification), lyric sections/segments; updates
media_intelligence_dispatches+processing_jobs; queues an embedding refresh. A forged callback (valid secret, wrong owner/track) still can’t write — the dispatch lookup is keyed onowner_id + track_id + asset_id. - Response:
mediaIntelligenceCallbackResponseSchema{ status: "accepted", trackId, appliedLanes }202.
Modal media‑intelligence services (Python)
Two Modal apps expose internal HTTP endpoints (FastAPI inside Modal). Both
require Authorization: Bearer <api key> + x-swayzio-contract-version, accept
only signed‑URL audio sources, and fail closed when their key env var is unset.
Audio embedding (swayzio-audio-embedding) — MuQ + MuLan vectors, returned
in‑band (no DB writes):
| Path | Method | Computes |
|---|---|---|
/health | GET | liveness |
/v1/audio-embedding/jobs | POST | MuQ + MuLan embeddings over windowed audio |
/v1/audio-embedding/text-queries | POST | MuLan text embeddings (text→track search) |
Native essentia (swayzio-native-essentia) — tags / stems / lyrics lanes,
result pushed back via the callback above:
| Path | Method | Computes |
|---|---|---|
/health | GET | liveness + model manifest |
/v1/media-intelligence/jobs | POST | create a tags/stems/lyrics job |
/v1/media-intelligence/jobs/{remoteJobId} | GET | poll job result |
Worker (Cloud Run)
The worker (services/worker) is a Fastify HTTP server fed by GCS object‑finalize
push and internal drains. Its routes (/events/gcs/object-finalized,
/processing/run-queued, /processing/audio-embeddings/run,
/processing/metrics, /health) have no application‑layer auth and rely on
private Cloud Run ingress.
Operator note: the worker’s processing routes must be reachable only from inside
the private network / IAM. If exposed publicly, /processing/* would let a
caller trigger GPU spend. Confirm ingress is internal‑only.
Trigger.dev tasks (async, non‑HTTP)
Invoked via the Trigger.dev SDK (not a REST surface). Their only HTTP‑facing pieces are outbound callbacks into the internal endpoints above.
| Task | Trigger | Outbound callback |
|---|---|---|
upload-processing | event (upload workflow) | /internal/workflows/trigger-status |
catalog-drain-seeder | owner “Analyze my catalog” | /internal/catalog-drain/eligible → fan‑out |
catalog-drain-track | batch from seeder | /internal/catalog-drain/dispatch |
catalog-drain-diamond-trickle | cron 0 */6 * * * | (calls seeder) |