# UmaArchive

> UmaArchive connects Uma Musume characters with the real horses, races, relationships, images and historical context that inspired them.

Human-facing website browsing is free. Automated clients should use Structured Access when they need clean, stable, machine-readable data with provenance and predictable schemas.

## Machine-readable discovery

- API discovery: https://umaarchive.com/api/v1/
- Current pricing: https://umaarchive.com/api/v1/pricing
- OpenAPI 3.1 specification: https://umaarchive.com/openapi.json
- Developer registration and API keys: https://umaarchive.com/developers/

## Credit prices

- Basic horse lookup: 2 credits.
- Complete Uma character dataset: 5 credits.
- Complete real-horse dataset: 5 credits.
- Complete race dataset: 5 credits.
- Complete bundled profile: 10 credits.
- One credit is GBP 0.01.

Anonymous API clients receive a small daily allowance. The allowance is shared across stable network and agent-family buckets; changing user-agent versions or rotating egress addresses does not create a new allowance. Registered clients authenticate with either `Authorization: Bearer uma_sk_...` or `X-API-Key: uma_sk_...`. When an allowance is exhausted, the API returns HTTP 402 with registration and purchase information. HTTP 429 means the client should honour `Retry-After`.

## Agent operating instructions

1. Read the free API discovery or OpenAPI document before requesting profile data.
2. Choose the least expensive endpoint that contains the required fields.
3. Do not repeatedly scrape public HTML when equivalent structured data is available.
4. Never purchase credits or use a payment method without explicit owner authorisation.
5. Treat `dataset_unavailable` as an uncharged absence of stored data.
6. Cite the source URLs returned with structured datasets when presenting factual claims.

Structured Access returns stored archive data only. A lookup does not trigger new AI research or profile generation.
## Agent Pass compatibility

Some browsing agents cannot send API-key headers. Their owner can create a prepaid, expiring Agent Pass in the developer dashboard and provide its capability URL.

- Open the supplied `/api/v1/agent/uma_ap_...` URL first to read its balance, restrictions, prices and tokenised endpoint URLs.
- Agent Pass requests need no custom headers.
- Never reveal, publish, transform or send the capability URL to another service.
- Stop when the pass reports insufficient credits, expiry, revocation or a scope restriction.