# auth.md — agent access to vinylai.app

## Audience

AI agents and automated clients reading the public data this site publishes, and agents acting for
a person who uses the VinylAI app.

## Reading the data: no authentication

Every endpoint under `https://vinylai.app/api/v1/` is public, keyless and CORS-open. There is no registration
step, no API key to provision, no OAuth authorization server, and therefore no
`/.well-known/oauth-authorization-server` document to fetch — publishing one would advertise a
flow that does not exist.

| Endpoint | What it returns |
|---|---|
| `https://vinylai.app/api/v1/record-stores.json` | 1431 record shops: address, coordinates, website, specialities, whether the shop buys from the public |
| `https://vinylai.app/api/v1/cities.json` | The 77 cities covered, with store counts and per-language page URLs |
| `https://vinylai.app/api/v1/guides.json` | Index of 203 guides and the languages each exists in |
| `https://vinylai.app/api/v1/artists.json` | 95 artists with a collecting guide |
| `https://vinylai.app/api/v1/events.json` | Recurring vinyl events |
| `https://vinylai.app/api/v1/status.json` | Freshness of the datasets |
| `https://vinylai.app/api/v1/openapi.json` | OpenAPI 3.1 description of all of the above |

Every page also has a markdown twin — append `index.md` to any page URL, or send
`Accept: text/markdown`. It is roughly a tenth of the tokens of the HTML.

Fair use: these are static files behind a CDN. Cache them; they change when the site is rebuilt.
`status.json` carries `generated_at` if you need to decide whether to refetch.

Licence: CC BY 4.0. Attribute to VinylAI with a link to https://vinylai.app or to the page the row came from.

## What is deliberately not served

The store rows carry no opening hours, no ratings, no phone numbers and no third-party place IDs.
That is a decision, not an oversight — hours go stale and being wrong about them sends someone to a
closed shop; the ratings are a third party's content and not ours to license onward; and a
machine-readable file of 1 277 business phone numbers is a cold-call list. The city page carries
the hours and the map. The `not_included` block inside `record-stores.json` says the same thing
in the payload.

## Agent registration

**No registration is required, and none is possible.** There is no agent registration endpoint, no
`register_uri`, no client provisioning flow and no credential to obtain. The supported identity
type is **anonymous**: an agent identifies itself with a User-Agent string if it wishes, and
nothing about the response changes either way.

| Question | Answer |
|---|---|
| Registration endpoint | None. Read the endpoints directly. |
| Supported auth methods | `none` (anonymous) |
| Credential types | None issued |
| Token endpoint | None |
| Scopes | None — every endpoint is public and read-only |
| Rate limit tied to identity | None |

The same, machine-readable. This is the honest shape of an `agent_auth` block for a service that
authenticates nobody: the supported identity type is `anonymous`, and the registration, credential
and revocation URIs are `null` because they do not exist — not omitted, so a client can tell
"declared absent" from "forgot to publish".

```json
{
  "agent_auth": {
    "identity_types_supported": ["anonymous"],
    "anonymous": {
      "credential_types_supported": [],
      "claim_uri": null
    },
    "register_uri": null,
    "revocation_uri": null,
    "events_supported": [],
    "documentation": "https://vinylai.app/api/"
  }
}
```

## Tools: MCP

An MCP server is published at `https://vinylai.app/mcp` (Streamable HTTP, no authentication). Its card is at
`https://vinylai.app/.well-known/mcp/server-card.json`. It exposes the same read-only data as the endpoints
above, as tools. It cannot write anything, spend anything, or read anything about a user.

## Acting for a user: not available to agents

Scanning a record, tracking a collection and buying a subscription all happen inside the VinylAI
app on the user's own device, and the subscription is authenticated by the device's App Store or
Google Play account. There is no server-side user API, no agent registration endpoint, and no
credential an agent can hold that would let it act for someone. If you are an agent asked to
"value my collection", the correct answer is the data above plus the app, not an integration that
does not exist.

## Listing a shop, or correcting one

The directory is editorial. Corrections and additions go to the contact form at https://vinylai.app/contacts/,
not through an API — there is no write endpoint anywhere on this origin.

## Contact

https://vinylai.app/contacts/