# lotsofsounds — Complete API Reference for LLMs and AI Agents

> If you are an LLM, AI agent, or automated system reading this, this document contains everything you need to integrate lotsofsounds as a tool. It includes full endpoint specs, example requests/responses, tool schemas, and best practices for agent workflows.

## Overview

lotsofsounds is a REST API for searching, streaming, and downloading royalty-free sound effects and music tracks. It is designed for programmatic use by developers, AI agents, and LLM tool-calling systems.

**Base URL:** https://api.lotsofsounds.com
**Auth:** API key via `x-api-key` header (keys prefixed with `los_`)
**Format:** All responses are JSON. All requests are GET.

---

## Tool Definitions

If you are an LLM framework (LangChain, CrewAI, OpenAI function calling, Claude tool use, etc.), here are the tool definitions you should register:

### Tool: search_sounds

Search for sound effects by natural language query, tags, or duration.

**Parameters:**
- `query` (string, optional): Natural language search. Examples: "thunder storm", "gentle notification chime", "footsteps on gravel"
- `tags` (string, optional): Comma-separated tags for filtering. Uses AND logic. Example: "nature,rain"
- `min_duration` (number, optional): Minimum duration in seconds
- `max_duration` (number, optional): Maximum duration in seconds
- `sort` (string, optional): One of: duration, name. Default: name
- `order` (string, optional): "asc" or "desc". Default: desc
- `page` (integer, optional): Page number. Default: 1
- `limit` (integer, optional): Results per page, 1-100. Default: 20

**Maps to:** `GET /api/v1/sounds?q={query}&tags={tags}&min_duration={min_duration}&max_duration={max_duration}&sort={sort}&order={order}&page={page}&limit={limit}`

**Returns:** Array of sound objects with pagination.

### Tool: get_sound

Get full metadata for a specific sound by ID.

**Parameters:**
- `id` (string, required): The sound ID (UUID format)

**Maps to:** `GET /api/v1/sounds/{id}`

**Returns:** Single sound object with full metadata.

### Tool: download_sound

Get a time-limited signed URL to download a sound file.

**Parameters:**
- `id` (string, required): The sound ID (UUID format)

**Maps to:** `GET /api/v1/sounds/{id}/download`

**Returns:** Object with `download_url` (expires in 1 hour) and `expires_in` (seconds).

### Tool: browse_samples

Get free sample sounds without authentication. Useful for demos and testing.

**Parameters:** None

**Maps to:** `GET /api/v1/sounds/sample`

**Returns:** Array of 6 sample sound objects.

---

## Endpoint Reference

### GET /api/v1/sounds/sample

Returns 6 curated sample sounds. **No authentication required.**

```bash
curl https://api.lotsofsounds.com/api/v1/sounds/sample
```

Response:
```json
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Thunder Rumble",
      "description": "Deep rolling thunder with rain",
      "tags": ["nature", "weather", "thunder"],
      "duration": 12.5,
      "avgRating": 4.5,
      "createdAt": "2025-01-15T10:30:00Z",
      "previewUrl": "https://cdn.lotsofsounds.com/previews/..."
    }
  ],
  "total": 6,
  "message": "These are sample sounds. Sign up for full catalog access.",
  "upgrade_url": "https://lotsofsounds.com/pricing"
}
```

### GET /api/v1/sounds/sample/{id}/stream

Returns a signed streaming URL for a sample sound. **No authentication required.**

```bash
curl https://api.lotsofsounds.com/api/v1/sounds/sample/SOUND_ID/stream
```

Response:
```json
{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Thunder Rumble",
    "stream_url": "https://..."
  }
}
```

### GET /api/v1/sounds

Search and filter the full sound catalog. **Requires API key.**

Query parameters:
- `q` (string): Natural language search across name and description
- `tags` (string): Comma-separated tags, AND logic
- `min_duration` (number): Minimum duration in seconds
- `max_duration` (number): Maximum duration in seconds
- `sort` (string): duration or name (default: name)
- `order` (string): asc or desc (default: desc)
- `page` (integer): Page number (default: 1)
- `limit` (integer): Results per page, 1-100 (default: 20)

```bash
curl "https://api.lotsofsounds.com/api/v1/sounds?q=thunder&tags=nature&limit=5" \
  -H "x-api-key: los_your_key"
```

Response:
```json
{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Thunder Rumble",
      "description": "Deep rolling thunder with rain",
      "tags": ["nature", "weather", "thunder"],
      "duration": 12.5,
      "license": "CC0",
      "username": "sounddesigner42",
      "avgRating": 4.5,
      "numDownloads": 1240,
      "createdAt": "2025-01-15T10:30:00Z",
      "previewUrl": "https://..."
    }
  ],
  "pagination": {
    "page": 1,
    "limit": 5,
    "total": 342,
    "totalPages": 69
  }
}
```

### GET /api/v1/sounds/{id}

Returns full metadata for a single sound. **Requires API key.**

```bash
curl https://api.lotsofsounds.com/api/v1/sounds/SOUND_ID \
  -H "x-api-key: los_your_key"
```

Response:
```json
{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Thunder Rumble",
    "description": "Deep rolling thunder with rain",
    "tags": ["nature", "weather", "thunder"],
    "duration": 12.5,
    "license": "CC0",
    "username": "sounddesigner42",
    "avgRating": 4.5,
    "numDownloads": 1240,
    "createdAt": "2025-01-15T10:30:00Z",
    "previewUrl": "https://..."
  }
}
```

### GET /api/v1/sounds/{id}/download

Returns a signed download URL. URL expires after 1 hour. **Requires API key.**

```bash
curl https://api.lotsofsounds.com/api/v1/sounds/SOUND_ID/download \
  -H "x-api-key: los_your_key"
```

Response:
```json
{
  "data": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "name": "Thunder Rumble",
    "download_url": "https://cdn.lotsofsounds.com/...",
    "expires_in": 3600
  }
}
```

---

## Authentication

All endpoints except `/api/v1/sounds/sample` and `/api/v1/sounds/sample/{id}/stream` require an API key.

Pass the key in the `x-api-key` header:
```
x-api-key: los_your_api_key_here
```

Keys are generated at https://lotsofsounds.com/dashboard/api-keys and are prefixed with `los_`.

API access requires a **Pro** ($15/mo, 2,500 req/day, unlimited downloads) or **Enterprise** ($49/mo, 50,000 req/day, unlimited downloads) subscription.

---

## Rate Limits

Every authenticated response includes these headers:
- `X-RateLimit-Limit`: Your daily request quota
- `X-RateLimit-Remaining`: Requests remaining today
- `X-RateLimit-Reset`: Unix timestamp when the limit resets (midnight UTC)

| Plan | Requests/day | Downloads | API Keys |
|------|-------------|-----------|----------|
| Pro | 2,500 | Unlimited | 2 |
| Enterprise | 50,000 | Unlimited | 20 |

---

## Error Handling

All errors return JSON with an `error` field:

```json
{ "error": "Missing x-api-key header" }
```

| Status | Meaning | What to do |
|--------|---------|------------|
| 401 | Missing or invalid API key | Check the `x-api-key` header is set correctly |
| 403 | Free plan, no API access | User needs to upgrade at https://lotsofsounds.com/pricing |
| 404 | Sound not found | The ID doesn't exist, verify it came from a search result |
| 429 | Rate limit exceeded | Wait until `reset` timestamp, or upgrade plan |
| 500 | Internal server error | Retry after a brief delay |

Rate limit errors include extra fields:
```json
{ "error": "Rate limit exceeded", "limit": 2500, "reset": 1711411200 }
```

---

## Sound Object Schema

### SoundSummary (returned by sample endpoints)
```
id          string    UUID
name        string    Human-readable name
description string?   Description of the sound
tags        string[]  Category tags
duration    number    Duration in seconds
stream_url  string    URL to stream this sound
avgRating   number    Average user rating
createdAt   string    ISO 8601 timestamp
previewUrl  string    Preview/streaming URL
```

### Sound (returned by authenticated endpoints)
Extends SoundSummary with:
```
license       string?   License type (e.g. "CC0")
username      string    Uploader username
numDownloads  integer   Total download count
```

### Pagination
```
page        integer   Current page
limit       integer   Results per page
total       integer   Total matching sounds
totalPages  integer   Total pages available
```

---

## Available Tags

Use these with the `tags` query parameter (comma-separated, AND logic):

**Nature:** nature, weather, thunder, rain, wind, ocean, forest, birds, water
**UI/Interface:** ui, click, notification, transition
**Foley:** foley, footsteps, door, keyboard, glass, camera, cork
**Music:** music, piano, guitar, drums, synth, vinyl
**Cinematic:** cinematic, boom, drone, laser
**Ambient/Other:** ambient, crowd, helicopter, subway, fireplace, cat, bell, chime, buzz, whoosh, swoosh

---

## Agent Best Practices

### Searching effectively
- Use natural language in the `q` parameter — it searches both name and description fields. "Gentle rain on a tin roof" works better than just "rain".
- Combine `q` with `tags` for precision: `q=gentle&tags=rain,nature` narrows results.
- Use duration filters when the user needs sounds of a specific length (e.g. `max_duration=3` for short UI sounds).
- Default `limit` is 20. Use `limit=5` for quick suggestions, `limit=50` for broader browsing.

### Presenting results to users
- Show the sound name, description, duration, and tags.
- If the user wants to hear a sound, provide the `previewUrl` or `stream_url`.
- If the user wants to download, call the download endpoint and provide the `download_url`.
- Mention that download URLs expire in 1 hour.

### Handling errors gracefully
- If you get a 403, tell the user they need a Pro or Enterprise plan and link to https://lotsofsounds.com/pricing.
- If you get a 429, tell the user their daily limit is reached and when it resets.
- If search returns no results, try broadening the query or removing tag filters.

### When you don't have an API key
- Use the `/api/v1/sounds/sample` endpoint to show what's available without authentication.
- Direct the user to https://lotsofsounds.com/sign-up to get started.

---

## Example Agent Workflow

User: "Find me a short thunder sound effect for my game"

1. Call `search_sounds(query="thunder", tags="nature", max_duration=5)`
2. Present top 3 results with name, description, and duration
3. User picks one
4. Call `download_sound(id="selected-id")`
5. Return the download URL to the user

User: "What sounds do you have?"

1. Call `browse_samples()` (no auth needed)
2. Present the 6 sample sounds
3. Mention full catalog requires a subscription

---

## OpenAPI Specification

The full OpenAPI 3.1 spec is available at: https://lotsofsounds.com/openapi.yaml

Use this for automated tool generation in frameworks like LangChain, AutoGPT, or any OpenAPI-compatible agent toolkit.

---

## Links

- Website: https://lotsofsounds.com
- Human documentation: https://lotsofsounds.com/docs
- Interactive API reference: https://lotsofsounds.com/docs/endpoints
- Pricing: https://lotsofsounds.com/pricing
- Blog: https://lotsofsounds.com/blog
- Sign up: https://lotsofsounds.com/sign-up
- OpenAPI spec: https://lotsofsounds.com/openapi.yaml
- Short LLM reference: https://lotsofsounds.com/llms.txt