Discovery – ONCE Docs

ONCE publishes a set of machine-readable documents so your agent can find and authenticate against the service on its own — no hardcoded endpoints, no reading these docs first. Point it at https://beta.once.app and it can take it from there.

Start here

Two entry points, depending on what your agent already speaks.

Fetch the API catalog. It links to every ONCE API with its description, documentation, and status endpoint:

curl https://beta.once.app/.well-known/api-catalog

Or read the Link headers on any public page. The same pointers arrive with the response, so a HEAD request is enough:

curl -I https://beta.once.app/

Link: </.well-known/api-catalog>; rel="api-catalog",
      </v1/openapi.json>; rel="service-desc",
      <https://docs.once.app/rest-api>; rel="service-doc",
      </.well-known/agent-card.json>; rel="describedby",
      </.well-known/mcp/server-card.json>; rel="describedby"

Every document

URL	What you get
`/.well-known/api-catalog`	Every ONCE API, with OpenAPI, docs, and status links (RFC 9727)
`/.well-known/mcp/server-card.json`	MCP endpoint, protocol version, and capabilities
`/.well-known/agent-card.json`	A2A agent card for the endpoint at `/api/a2a`
`/.well-known/agent-skills/index.json`	Published skills, each with a SHA-256 digest
`/.well-known/oauth-protected-resource`	What to authenticate against, and where
`/.well-known/oauth-authorization-server`	OAuth endpoints, plus an `agent_auth` block
`/auth.md`	How to register and get a credential, in prose
`/.well-known/http-message-signatures-directory`	The public key ONCE signs its own outbound requests with
`/.well-known/ai-catalog.json`	ARD capability manifest — every agent-facing resource in one fetch
`/robots.txt`	Crawl rules and our Content Signals preference

Pages as markdown

Send Accept: text/markdown to any public page and you get clean prose instead of the app’s HTML:

curl -H 'Accept: text/markdown' https://beta.once.app/
curl -H 'Accept: text/markdown' https://beta.once.app/pricing

Appending .md works too — https://beta.once.app/pricing.md. The homepage’s alias is /index.md. Browsers keep getting HTML.

Available for /, /login, /signup, /pricing, and the /ai-music pages in all three languages. /login and /signup are included because that is where you land if you request / without credentials — their markdown points you straight at the authentication flow.

Getting a credential by email

If a person is reachable by email but not sitting at a browser, you can obtain a token without the OAuth browser round trip:

# 1. Ask for a code. The response is the same whether or not the account exists.
curl -X POST https://beta.once.app/v1/agent-auth/verified-email/challenge \
  -H 'Content-Type: application/json' \
  -d '{"email": "you@example.com", "client_name": "My Agent"}'
 
# 2. ONCE emails an 8-digit code. Exchange it.
curl -X POST https://beta.once.app/v1/agent-auth/verified-email/claim \
  -H 'Content-Type: application/json' \
  -d '{"email": "you@example.com", "code": "12345678"}'

You get back a scoped bearer token. It expires in 30 days, appears in the account owner’s dashboard under the client_name you passed, and they can revoke it at any time from Settings → Developer. Codes expire in 15 minutes and allow 5 attempts.

Skills

Three skills are published as SKILL.md artifacts:

once-agent-auth — registering and getting a credential.
once-release-submission — the full path from files to delivered release.
once-release-metadata — writing metadata that passes validation first time.

Each entry in the index carries a digest. Verify it against the bytes you fetch:

curl -s https://beta.once.app/.well-known/agent-skills/once-agent-auth/SKILL.md \
  | shasum -a 256

A2A

/api/a2a speaks A2A JSON-RPC for public reference data — pricing, the store catalog, and the metadata rules:

curl -X POST https://beta.once.app/api/a2a \
  -H 'Content-Type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"message/send",
       "params":{"message":{"role":"user",
       "parts":[{"kind":"text","text":"what does a 3-track EP cost?"}]}}}'

Submitting a release is not available over A2A. It spends credits and publishes music under your name, so it runs over the authenticated MCP server or REST API.

In-browser tools

When you open ONCE in a browser that supports WebMCP, the page registers tools an in-page agent can call directly: once_get_pricing, once_list_distribution_stores, once_get_metadata_rules, once_search_pages, and once_navigate. Nothing that spends credits is exposed this way.

Content usage

/robots.txt declares Content-Signal: search=yes, ai-input=yes, ai-train=no. You may index ONCE’s pages and cite them when answering a question. You may not use them to train or fine-tune a generative model.

Protocol & JSON-RPC

Agent Discovery