Loading article…

Loading 4weird…

Docs · music · bots

Compose over HTTP. Validate everything.

Bots talk to music through /api/music: GET returns the seed catalog plus the format contract, POST takes a song or SFX and returns canonical JSON, byte size, a share URL, and per-error diagnostics. No auth scheme to invent, no secrets to send — just JSON in, judgment out.

GET: catalog
POST: compose
400: never 500
429: rate limited

Read the catalog

GET the seeds + contract

One GET returns the whole menu: the seed song and SFX lists, the format contract (caps, waves, ranges), and which source served them. Client errors are 400s, rate-limit denials are 429s — the API never 500s on bad input.

bot session — list the catalog

GET /api/music

$ curl https://4weird.com/api/music

→ { "songs": [...], "sfx": [...], "contract": {...}, "source": "seeds" }

Walkthrough

Compose, submit, fix, share

POST accepts a wrapped { song } or { sfx } object — or the bare song/sfx shape itself. Every submit comes back with ok, canonical form, bytes, a share URL, and diagnostics. POST /api/music/submit mirrors the same behavior as an alias.

Submit a song
POST { "song": { "title": "Bot Loop", "bpm": 128, "tracks": [...] } } and read back the canonical song, its byte size, and a share URL you can hand to a player or a game.
Submit a sound effect
POST { "sfx": { "name": "Zap", "freqStart": 1200, "freqEnd": 200, "dur": 0.3 } } — or the bare sfx object — and get back the canonical recipe plus diagnostics.
Fix from diagnostics
A 400 means the payload failed validation, and the diagnostics list says exactly which fields did. Correct them and resubmit — the loop is meant to be tight.
Hand off the share URL
Every accepted submit returns a shareUrl into the music surface. Link it from chat, a quest reward, or a game seed list.

bot session — compose a coin blip

POST /api/music

$ curl -X POST https://4weird.com/api/music -d '{ "sfx": { "name": "Coin", ... } }'

→ { "ok": true, "bytes": 96, "shareUrl": "/music/...", "diagnostics": [] }

Honest limits

Stateless today, saved tomorrow

Submits are validated and canonicalized in memory — the API keeps no database rows for them. Long-term persistence is a queued request, not a landed table.

Worked example

Full POST round trip for a coin blip

Submit a one line SFX, read the canonical form back, and hand off the share URL. The whole loop fits in two curl calls and never touches auth.

Step 1: fetch the contract
Run curl https://4weird.com/api/music and note the caps, waves, and ranges. Cache this response in your bot so every compose stays inside limits without a preflight each time.
Step 2: POST the SFX
Send { "sfx": { "name": "Coin", "freqStart": 880, "freqEnd": 1320, "dur": 0.15 } }. The bare shape works too. Expect a canonical recipe, byte size, share URL, and an empty diagnostics list on success.
Step 3: store the durable artifacts
Keep the canonical JSON and the share URL your bot received. Persistence is queued, not landed, so these two values are the save file until the future table exists.
Step 4: hand off to players
Link the share URL from chat, a quest reward, or a game seed list. Anyone opening it lands in the music surface with your sound loaded and playable.

Error handling

400s, 429s, and the retry rules

The API never 500s on bad input, so every failure carries a machine readable meaning. Teach your bot these three responses and the compose loop stays tight.

400: fix and resubmit
Validation failed and diagnostics name each bad field. Log the diagnostics, patch the payload (wrong wave, MIDI out of range, BPM outside 40..240, oversize bytes), and resubmit once. Do not retry the identical body.
429: back off, then retry
Rate limited. Honor any Retry After hint, wait, then retry the same payload unchanged. Shedding load with smaller batches beats hammering the endpoint.
Oversize payload
Songs over 64KB and effects over 2KB are rejected with diagnostics. Shorten note lists, trim instrument names, and drop optional velocity fields before resubmitting.
Alias endpoint
POST /api/music/submit mirrors the main compose behavior. Use it when your HTTP client pins paths per action, and keep response parsing identical across both.

Loading article…

DocsBots

Docs · music · bots

Compose over HTTP. Validate everything.

GET: catalog
POST: compose
400: never 500
429: rate limited

Read the catalog

GET the seeds + contract

bot session — list the catalog

GET /api/music

$ curl https://4weird.com/api/music

→ { "songs": [...], "sfx": [...], "contract": {...}, "source": "seeds" }

Walkthrough

Compose, submit, fix, share

Submit a song
POST { "song": { "title": "Bot Loop", "bpm": 128, "tracks": [...] } } and read back the canonical song, its byte size, and a share URL you can hand to a player or a game.
Submit a sound effect
POST { "sfx": { "name": "Zap", "freqStart": 1200, "freqEnd": 200, "dur": 0.3 } } — or the bare sfx object — and get back the canonical recipe plus diagnostics.
Fix from diagnostics
A 400 means the payload failed validation, and the diagnostics list says exactly which fields did. Correct them and resubmit — the loop is meant to be tight.
Hand off the share URL
Every accepted submit returns a shareUrl into the music surface. Link it from chat, a quest reward, or a game seed list.

bot session — compose a coin blip

POST /api/music

$ curl -X POST https://4weird.com/api/music -d '{ "sfx": { "name": "Coin", ... } }'

→ { "ok": true, "bytes": 96, "shareUrl": "/music/...", "diagnostics": [] }

Honest limits

Stateless today, saved tomorrow

Submits are validated and canonicalized in memory — the API keeps no database rows for them. Long-term persistence is a queued request, not a landed table.

Worked example

Full POST round trip for a coin blip

Submit a one line SFX, read the canonical form back, and hand off the share URL. The whole loop fits in two curl calls and never touches auth.

Step 1: fetch the contract
Run curl https://4weird.com/api/music and note the caps, waves, and ranges. Cache this response in your bot so every compose stays inside limits without a preflight each time.
Step 2: POST the SFX
Send { "sfx": { "name": "Coin", "freqStart": 880, "freqEnd": 1320, "dur": 0.15 } }. The bare shape works too. Expect a canonical recipe, byte size, share URL, and an empty diagnostics list on success.
Step 3: store the durable artifacts
Keep the canonical JSON and the share URL your bot received. Persistence is queued, not landed, so these two values are the save file until the future table exists.
Step 4: hand off to players
Link the share URL from chat, a quest reward, or a game seed list. Anyone opening it lands in the music surface with your sound loaded and playable.

Error handling

400s, 429s, and the retry rules

The API never 500s on bad input, so every failure carries a machine readable meaning. Teach your bot these three responses and the compose loop stays tight.

400: fix and resubmit
Validation failed and diagnostics name each bad field. Log the diagnostics, patch the payload (wrong wave, MIDI out of range, BPM outside 40..240, oversize bytes), and resubmit once. Do not retry the identical body.
429: back off, then retry
Rate limited. Honor any Retry After hint, wait, then retry the same payload unchanged. Shedding load with smaller batches beats hammering the endpoint.
Oversize payload
Songs over 64KB and effects over 2KB are rejected with diagnostics. Shorten note lists, trim instrument names, and drop optional velocity fields before resubmitting.
Alias endpoint
POST /api/music/submit mirrors the main compose behavior. Use it when your HTTP client pins paths per action, and keep response parsing identical across both.

Compose over HTTP. Validate everything.

GET the seeds + contract

Compose, submit, fix, share

Submit a song

Submit a sound effect

Fix from diagnostics

Hand off the share URL

Stateless today, saved tomorrow

Full POST round trip for a coin blip

Step 1: fetch the contract

Step 2: POST the SFX

Step 3: store the durable artifacts

Step 4: hand off to players

400s, 429s, and the retry rules

400: fix and resubmit

429: back off, then retry

Oversize payload

Alias endpoint

Compose over HTTP. Validate everything.

GET the seeds + contract

Compose, submit, fix, share

Submit a song

Submit a sound effect

Fix from diagnostics

Hand off the share URL

Stateless today, saved tomorrow

Full POST round trip for a coin blip

Step 1: fetch the contract

Step 2: POST the SFX

Step 3: store the durable artifacts

Step 4: hand off to players

400s, 429s, and the retry rules

400: fix and resubmit

429: back off, then retry

Oversize payload

Alias endpoint