canonical: https://jentic.com/apis/once.app/once

# Once App ONCE REST API

The ONCE REST API distributes music releases to streaming stores and tracks their delivery. It uploads audio and artwork as base64, from a public URL, or through chunked upload sessions, checks a file with an AI song detector and a Pex registry match, and generates or edits AI album art. Releases are drafted, priced with a quote against the live credit balance, submitted with release and track metadata, and then followed through store delivery status, redistribution to more stores, takedowns, and UGC monetization policies for YouTube Content ID, Facebook Rights Manager, and TikTok. Webhooks report release status changes and approvals, and credit routes cover balance, checkout, and auto-reload.

## For AI agents

Upload tracks and artwork, quote and submit a music release to streaming stores, follow per-store delivery status, redistribute or take down a release, and set UGC monetization policies.

## Scope

Does not stream music to listeners, master audio, or pay out royalties to artists. Use for uploading, checking, distributing, and taking down music releases on streaming stores only.

## Capabilities

- Upload audio and cover art as base64, import it from a public URL, or open a chunked upload session
- Check an uploaded file with the AI Song Detector and a Pex Search registry-match check before release
- Save a work-in-progress release draft and reuse its releaseId on follow-up calls
- Price a release's tracks with a quote that uses the same code that debits on submit, without charging anything
- Submit a release with title, primary artist, genre, label, release_date, and distribution_store_ids, plus per-track isrc and writers
- Follow per-store delivery status, deliver a live release to more stores by store_ids, or request a takedown
- Set UGC policies such as monetize or track for YouTube Content ID and subscribe a webhook to release.status_changed and release.approved

## Use cases

### Release assistant agent

An independent artist's agent takes finished tracks from upload to stores. Through Jentic it searches for 'submit a music release for distribution', loads the ONCE submit operation, and first reads the required fields from the release schema and the store ids from the distribution store list, with the bearer token attached at call time. It prices the tracks with a quote, submits the release, and then follows store delivery status until each store reports live.

Example prompt: Call GET /release-schema and GET /distribution-stores, POST `/releases/quote` with the tracks, then POST /releases with release title, primary_artist_name, genre, release_date, distribution_store_ids, and the tracks, and poll GET `/releases/{id}/status`

### Pre-release content checks

Before paying to distribute, a label tool screens each upload. POST `/audio/ai-detection` returns the AI Song Detector result for an uploaded file, and POST `/audio/acr-check` runs a Pex Search registry match so a track that matches existing recordings is caught early. GET /metadata-rules publishes the metadata policy hitlist the release must satisfy.

Example prompt: POST `/audio/ai-detection` and POST `/audio/acr-check` for each uploaded track file, then read GET /metadata-rules and flag any track that fails

### Store targeting and takedowns

After a release is live, a manager can widen or narrow where it is sold. POST `/releases/{id}/distribute` takes store_ids from the distribution store list and queues delivery to extra stores without re-uploading assets, while POST `/releases/{id}/takedown` removes it from specific stores or all of them. The spec notes takedowns propagate to stores over days and cannot be un-requested.

Example prompt: Call POST `/releases/{id}/distribute` with store_ids for two additional stores from GET /distribution-stores, then confirm them in GET `/releases/{id}/status`

### Release event webhooks

A dashboard learns about releases without polling. POST /webhooks registers an https endpoint for release.status_changed, which fires on aggregate status transitions and per-store go-live or takedown, and release.approved, which carries the UPC and every track ISRC once the release goes live. Up to five endpoints per account are allowed, and the signing secret is returned exactly once.

Example prompt: POST /webhooks with url 'https://example.com/once-hook' and event_types ['release.approved', 'release.status_changed'], then store the returned signing secret

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/releases` | Submit a release for distribution |
| POST | `/releases/quote` | Price a release before submitting |
| GET | `/releases/{id}/status` | Get store delivery status |
| POST | `/releases/{id}/distribute` | Deliver to additional stores |
| POST | `/releases/{id}/takedown` | Take a release down |
| POST | `/files/from-url` | Import a file from a URL |
| GET | `/distribution-stores` | List supported stores |
| POST | `/webhooks` | Register a release webhook |

## Key resources

- **Files and uploads** — Base64 uploads, URL imports, chunked upload sessions, AI detection, registry checks, and AI cover art
- **Releases** — Drafts, quotes, submissions, merged metadata, store status, jobs, redistribution, takedowns, store targeting, and UGC policies
- **Reference data** — Release schema, distribution stores, language and script codes, metadata rules, and pricing
- **Account and credits** — Profile, credit balance and transactions, checkout, and auto-reload
- **Webhooks** — Endpoints for release status and approval events

## AI readiness

This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.

- **Score:** 47 / 100
- **Maturity:** Foundational
- **Dimensions:**
  - Foundational Compliance: 83 / 100
  - Developer Experience & Jentic Compatibility: 58 / 100
  - AI-Readiness & Agent Experience: 22 / 100
  - Agent Usability: 94 / 100
  - Security: 60 / 100
  - AI Discoverability: 70 / 100
- **View full report:** https://jentic.com/apis/once.app/once/scorecard
- **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/
- **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview

### Score it yourself

Every API in the directory is allowlisted, so you can re-score it with no key required.

- **Score your own API:** https://jentic.com/scorecard.md
- **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md

```sh
npx @jentic/api-scorecard-cli score <openapi-url>
```

## Why Jentic

- **Setup:** Wiring ONCE by hand means getting a bearer token through the verified-email or OAuth flow, uploading large audio in chunks, quoting credits before submit, and tracking per-store delivery. Through Jentic you install once, import ONCE from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** ONCE puts the release id in the URL path (`/releases/{id}/...`), so a rule can pin your agent to one release and the operations you pick on it. You choose the operations, so irreversible or spending ones like a takedown or a credit checkout are not included unless you add them.
- **Credential handling:** Your ONCE token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'submit a music release' or 'check store delivery status', and Jentic returns the matching ONCE operation with its input schema, including release and track fields, so the agent calls it correctly.

## Related APIs

- **Revelator Music API** — Music distribution, rights, and royalty infrastructure for labels
- **Spotify Web API** — Artist, album, track, and playback data on Spotify
- **Musixmatch API** — Lyrics and track metadata

## FAQ

### What authentication does the ONCE REST API use?

Per its OpenAPI spec, the ONCE REST API uses HTTP bearer authentication with a JWT or a personal access token starting once_pat_. Some routes are open without a token, including /status, /pricing, /distribution-stores, /metadata-rules, and the verified-email challenge and claim routes that issue a scoped bearer token. The fraud score route needs a token with the once:fraud scope. Through Jentic the token is stored by your own instance and attached at call time.

### Can I price a release before submitting it?

Yes. POST `/releases/quote` takes the same tracks you are about to submit and prices them with the same code that debits on submit, against your live balance, without creating or charging anything. GET /pricing lists per-credit and per-song prices, with human and AI songs priced separately.

### What are the rate limits for the ONCE REST API?

The OpenAPI spec does not give numeric rate limits, though it notes the verified-email challenge is rate limited per IP and per email, and error responses can carry retryAfterSeconds. Check the ONCE documentation at https://once.app for current limits.

### Is there a ONCE MCP server?

Yes. ONCE states that this REST API has the same capabilities as the ONCE MCP server. You can also connect it directly through Jentic: your agent gets the full 40-endpoint surface from the spec without loading another server's tool definitions into its context, your token is injected at call time by your self-hosted instance instead of living in an MCP config, and your rules decide which operations the agent may call.

### How do I submit a release through Jentic?

Search Jentic for 'submit a music release for distribution', load the ONCE release submit operation, and execute it with release metadata such as title, primary_artist_name, genre, and distribution_store_ids, plus the tracks with their audio_file_url. Read GET /release-schema first for the required fields. To run it on your own infrastructure, install Jentic One from its GitHub repo.

### Can a takedown be reversed?

No. Per the spec, POST `/releases/{id}/takedown` removes a release from the store_ids you pass, or from every store when you pass all, and takedowns propagate to stores over days and cannot be un-requested. To change targeting for the next submission without removing anything, use PUT `/releases/{id}/stores.`

### Can I limit what my agent is allowed to do with the ONCE REST API?

Yes. Write a rule that allows only GET `/releases/{id}/status` and GET `/releases/{id}` for one release id, and the agent can read that release's metadata and store status but cannot submit, take it down, or buy credits, and every call it makes is logged.