Reference

API reference

The stable v1 HTTP surface — every endpoint your bot can call directly, with schemas, error codes, and copy-paste examples in cURL, Node.js, and Python.

Overview

All endpoints are JSON over HTTPS, relative to your deployment's base URL. Mutations return a small acknowledgement ({ accepted: true }); reads return the documented schema. Send an Idempotency-Key header on player creation to make retries safe.

conventions

# base URL
https://auralis.karenx.pro/api

# every call is authenticated with your credential
Authorization: Bearer auralis_…

Authentication

Pass your credential as a bearer token on every request. It is rate-limited per IP and per credential, and pins to the first Discord bot user id it sees.

Keep it server-side

The token grants full control of your players. Never ship it in a client app or commit it — store it as AURALIS_TOKEN and rotate it from the Credentials page if it leaks.

Errors

Errors return the matching HTTP status with a JSON body of { "error", "code" }. Branch on code — the strings below are stable.

Code	HTTP	Meaning
`UNAUTHORIZED`	401	Missing or invalid bearer token.
`IP_FORBIDDEN`	403	Request IP is not on the credential's allowlist.
`INVALID_BOT_USER_ID`	400	voice.user_id is not a valid Discord bot user id.
`BOT_USER_ID_MISMATCH`	403	Credential is locked to a different bot user id.
`BOT_USER_ID_TAKEN`	403	That bot is already bound to another credential.
`BOT_RUNNING_ELSEWHERE`	409	The bot is already running from another credential.
`LIMIT_REACHED`	429	Plan's concurrent-guild ceiling is reached.
`RATE_LIMITED`	429	Per-IP or per-credential request rate exceeded.
`NO_NODE_AVAILABLE`	503	No node had headroom for the request. Retry with backoff.

API reference

Overview

Authentication

Errors

Tracks

Players

Playback

Cluster