> ## Documentation Index
> Fetch the complete documentation index at: https://docs.openvinyl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Base URL, conventions and errors.

## Base URL

```
https://api.openvinyl.dev
```

All endpoints are under `/v1`. The MCP server for agents is at `/mcp` ([Connect an agent](https://docs.openvinyl.dev/guides/agents.md)).

## Authentication

None needed. Every endpoint, including the MCP server, works without a key or sign-up:

```bash theme={null}
curl "https://api.openvinyl.dev/v1/albums?q=radiohead%20amnesiac"
```

Apps that need a higher limit can be given a key; send it as `Authorization: Bearer ov_live_...`. Keys go in headers only, never in the URL.

## Rate limits

The API is free. Limits are only there to keep it fair:

| Caller | Per minute | Per day |
| - | - | - |
| No key (per IP address) | 30 | 5,000 |
| With a key | 60 or more | no cap |

The per-minute limit refills evenly, so short bursts are fine; the daily limit resets at 00:00 UTC. Every response tells you where you stand:

| Header | Meaning |
| - | - |
| `X-RateLimit-Limit` | Requests per minute |
| `X-RateLimit-Remaining` | Requests you can make right now |
| `X-RateLimit-Reset` | Unix time when you're back to the full limit |
| `X-RateLimit-Daily-Limit`, `X-RateLimit-Daily-Remaining` | Today, when there's a daily limit |
| `Retry-After` | On a `429`: seconds to wait before retrying |

`GET /v1/me` returns your current limits.

## Conventions

* **IDs.** Albums are `m…`, `g…` or `r…` (see [Albums and pressings](https://docs.openvinyl.dev/concepts/albums-and-pressings.md)). Pressings use the Discogs release ID.
* **Codes as printed.** Barcodes, catalog numbers and runouts can be sent exactly as they appear on the record. Spaces, dashes and case are ignored.
* **Album first.** Lookups return albums. Pressings are included where they matched, and can be ignored.
* **Provenance.** Values carry their source. Derived values carry their rule and confidence.

## Errors

| Status | Meaning |
| - | - |
| `400` | A required input is missing, e.g. neither `q` nor `barcode` |
| `401` | A key was sent but is invalid or revoked |
| `404` | The album, pressing or submission doesn't exist |
| `422` | An input is malformed, e.g. a barcode without 8–14 digits |
| `429` | Rate limit reached; wait `Retry-After` seconds |

Errors return a JSON body with `detail`:

```json theme={null}
{ "detail": "a barcode has 8 to 14 digits (UPC-A has 12, EAN-13 has 13)" }
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.