API Reference

The AudioLib API allows you to fetch random audio tracks from curated libraries. It follows REST conventions and returns JSON responses.

API base URL

https://api.audiolib.ai

Quick Start

Get a playable audio URL in one request.

cURL

bash

curl -X POST https://api.audiolib.ai/v1/audio \
  -H "Authorization: Bearer alp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"library":"audio.focus"}'

JavaScript

javascript

const res = await fetch('https://api.audiolib.ai/v1/audio', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer alp_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ library: 'audio.focus' }),
})

const json = await res.json()
const url = json.data?.url
if (url) new Audio(url).play()

Authentication

All API requests require a Bearer token in the Authorization header. Generate API keys from your dashboard.

http

Authorization: Bearer alp_your_api_key_here

Key format: API keys begin with alp_ followed by 32 random characters. Keys are shown only once upon creation. Store them securely.

Endpoints

Method	Endpoint	Description
POST	/v1/audio	Fetch a random audio track from a library

Request Format

Send a JSON body with the library field set to a library's standard name.

Field	Type	Required	Description
library	string	Yes	The standard name of the library (e.g. "audio.ambient")

json

{
  "library": "audio.ambient"
}

Response Format

Success responses use a standard envelope. Audio fields are in data.

json

{
  "code": 0,
  "msg": "ok",
  "data": {
    "title": "Deep Space Drift",
    "url": "https://cdn.example.com/audio/track.mp3",
    "duration_sec": 240
  }
}

Error Codes

HTTP Status	Error Code	Description
401	MISSING_AUTH	Authorization header is missing or malformed
401	INVALID_KEY_FORMAT	API key does not match expected format (alp_...)
401	INVALID_KEY	API key is invalid, inactive, or revoked
400	INVALID_JSON	Request body is not valid JSON
400	MISSING_LIBRARY	The library field is missing from the request body
404	LIBRARY_NOT_FOUND	No library found with the given name
404	NO_AUDIO_ITEMS	The library has no active audio items
429	QUOTA_EXCEEDED	Free plan enforced monthly limit of successful audio API calls reached; response includes limit (resets each UTC calendar month)
503	PRESIGN_FAILED	Temporary URL could not be generated (storage/signing error)
500	INTERNAL_ERROR	An unexpected server error occurred

json

{
  "error": "Library 'audio.unknown' not found",
  "code": "LIBRARY_NOT_FOUND"
}

Examples

cURL

bash

curl -X POST https://api.audiolib.ai/v1/audio \
  -H "Authorization: Bearer alp_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"library":"audio.sleep"}'

JavaScript (fetch)

javascript

const response = await fetch('https://api.audiolib.ai/v1/audio', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer alp_your_api_key',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ library: 'audio.focus' }),
})

const json = await response.json()
console.log(json.data.url) // Play this URL

Python (requests)

python

import requests

response = requests.post(
    'https://api.audiolib.ai/v1/audio',
    headers={'Authorization': 'Bearer alp_your_api_key'},
    json={'library': 'audio.ambient'}
)

data = response.json()
print(data['data']['url'])