# Songtradr

> Songtradr is a Santa Monica, California B2B music company building licensing, rights and music-data infrastructure for brands, agencies, digital platforms, artists and rightsholders. Its public developer surface is the Songtradr API: a JWT-authenticated REST API, described by a live OpenAPI 3.1 document, that returns deep music metadata (musical features, genre predictions, tags, taggrams, tag strengths, contributors, similarity vectors) and drives auto-tagging — rightsholders upload audio through a presigned S3 link, Songtradr's models classify it against a taxonomy of 350+ descriptive tags across 30+ categories, and the results become semantically searchable.

Generated by the API Evangelist enrichment pipeline on 2026-08-02. Songtradr does not publish an llms.txt of its own; this file is generated from the harvested OpenAPI and the artifacts in this repository.

## API

- [Songtradr API — Swagger UI](https://api.songtradr.com/swagger-ui.html): Interactive reference and the getting-started guidance for authentication, auto-tagging and search.
- [Songtradr API — OpenAPI 3.1 (live)](https://api.songtradr.com/v3/api-docs): The machine-readable contract. 17 paths, 19 operations, 40 schemas.
- Base URL: `https://api.songtradr.com`, all operations under `/api/v1`.

## Authentication

- Bearer JWT. `POST /api/v1/user/login` returns a `jwtToken`; send it as `Authorization: Bearer <jwtToken>` on every subsequent call.
- Accounts: sign up at https://www.songtradr.com/signup/personal, or email support@songtradr.com for a free API account.
- Rate limit: 120 requests per minute per account. Exceeding it returns HTTP 429.

## Capabilities

- **Auto-tagging** — `POST /api/v1/user/file/{name}/initUpload` returns a presigned S3 URL; upload the audio, poll `GET /api/v1/user/filesStatus`, then read results from `GET /api/v1/user/files`.
- **Semantic search over your own catalog** — `GET /api/v1/user/files` with ISRC and musical-feature filters, Spring `page`/`size`/`sort` pagination.
- **Recording metadata** — `GET /api/v1/user/recording/{ids}` (medium detail), `/{ids}/tagstrengths` (per-tag confidence), `/{ids}/taggrams` (time-localised tags), `/folder/{folderName}/tagstrengths`.
- **Similarity** — `GET /api/v1/similarityVectors/{isrcOrTrackId}` returns the similarity vector for a recording by ISRC or Songtradr track id.
- **Reference data** — `GET /api/v1/allowedValues/musicalFeatures` enumerates the allowed values for every musical-feature filter.
- **Account** — `GET/POST /api/v1/user/me`, `POST /api/v1/user/sign-up`, `/forgot-password`, `/update-password`, `/token`.

## Client libraries

- [Python — songtradr-api-client-python 3.0.0](https://pypi.org/project/songtradr-api-client-python/) (`pip install songtradr-api-client-python`)
- [JavaScript — songtradr-api-client 3.0.1](https://www.npmjs.com/package/songtradr-api-client) (`npm install songtradr-api-client`)
- [Ruby — songtradr_api_client_ruby 2.1.0](https://rubygems.org/gems/songtradr_api_client_ruby) (`gem install songtradr_api_client_ruby`)
- [Python client docs](https://github.com/songtradr/songtradr-python-api-client-docs) · [Ruby client docs](https://github.com/songtradr/songtradr-ruby-api-client-docs)

## Conventions and error handling

- Pagination: Spring Data `page` (0-based), `size` (default 100), `sort` (`property,asc|desc`).
- Errors are the Spring Boot envelope — `{timestamp, status, error, message, path}` as `application/json`. Not RFC 9457.
- Status codes in use: 200, 204, 400, 401, 403, 409, 429, 500.
- No idempotency key, no rate-limit response headers, no webhooks, no event stream, no GraphQL, no MCP server.

## Company

- [Songtradr](https://www.songtradr.com/) — parent of Bandcamp, 7digital, MassiveMusic, Big Sync Music and Musicube.
- [Blog](https://www.songtradr.com/blog) · [Support](https://support.songtradr.com/hc/en-us) · [GitHub](https://github.com/songtradr)
- [Pricing (Songtradr Pro)](https://www.songtradr.com/pro) · [Terms of use](https://www.songtradr.com/legals/termsofuse) · [Privacy policy](https://www.songtradr.com/legals/privacypolicy)

## API Evangelist artifacts

- `openapi/songtradr-api-openapi.yml` — harvested OpenAPI 3.1 (original JSON in `openapi/_original/`)
- `authentication/songtradr-authentication.yml` · `conventions/songtradr-conventions.yml`
- `errors/songtradr-problem-types.yml` · `rate-limits/songtradr-rate-limits.yml`
- `data-model/songtradr-data-model.yml` · `conformance/songtradr-conformance.yml`
- `lifecycle/songtradr-lifecycle.yml` · `packages/songtradr-packages.yml`
- `security/songtradr-domain-security.yml` · `well-known/songtradr-well-known.yml`
- `agentic-access/songtradr-agentic-access.yml` · `mcp/songtradr-mcp.yml` (candidate) · `skills/`