> ## Documentation Index > Fetch the complete documentation index at: https://developer.ammdistro.com/llms.txt > Use this file to discover all available pages before exploring further. # Create or update a release > Send the whole release. The same `releaseId` updates the release instead of creating another; an identical body changes nothing (`changed: false`). Only drafts and releases with changes requested can be updated. Needs a key with `delivery:write`. ## OpenAPI ````yaml /api-reference/openapi.json put /delivery/releases/{releaseId} openapi: 3.1.0 info: title: AMM Distro API version: '2026-10-22' description: >- Deliver releases and catalog transfers to AMM Distro from your own systems, check readiness, and follow each release's status. API access is turned on per account by AMM Distro. The account's admins then create keys in **Settings → API**. contact: name: AMM Distro support email: support@ammdistro.com url: https://ammdistro.com servers: - url: https://api.ammdistro.com/api/v2/external description: Production security: - bearerAuth: [] tags: - name: Accounts - name: Releases description: Create, update, validate and submit releases, and read their status. - name: Files description: Upload artwork and audio yourself instead of sending URLs. - name: Catalog transfers description: Move already-released catalog from another distributor. - name: Reference data - name: Ingestion check description: Look up any UPC or ISRC in the account's catalog. paths: /delivery/releases/{releaseId}: parameters: - name: releaseId in: path required: true description: Your ID for the release. schema: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$ example: NOVA-004 put: tags: - Releases summary: Create or update a release description: >- Send the whole release. The same `releaseId` updates the release instead of creating another; an identical body changes nothing (`changed: false`). Only drafts and releases with changes requested can be updated. Needs a key with `delivery:write`. operationId: putRelease requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/ReleaseInput' examples: newRelease: summary: New release value: title: Night Drive type: EP releaseDate: '2026-12-04' genre: primary: Electronic cLine: Nova Records pLine: Nova Records artists: - name: Nova spotifyId: 0OdUWJ0sBjDrqHygGUXeCF legalFirstName: Nora legalLastName: Vance artwork: url: https://masters.s3.amazonaws.com/nova/cover.jpg tracks: - externalId: NOVA-004-01 title: Night Drive explicit: false audio: url: https://masters.s3.amazonaws.com/nova/night-drive.wav credits: - firstName: Nora lastName: Vance roles: - Composer - Producer - Vocals share: 100 transfer: summary: Catalog transfer value: title: First Light releaseDate: '2027-01-15' originalReleaseDate: '2019-04-01' upc: '4006381333931' transfer: batch: nova-2026-11 previousDistributor: Previous distributor genre: primary: Electronic artists: - name: Nova spotifyId: 0OdUWJ0sBjDrqHygGUXeCF legalFirstName: Nora legalLastName: Vance artwork: url: https://masters.s3.amazonaws.com/nova/first-light.jpg tracks: - title: First Light isrc: USRC11900001 audio: url: https://masters.s3.amazonaws.com/nova/first-light.wav credits: - firstName: Nora lastName: Vance roles: - Composer - Producer - Vocals responses: '200': description: Updated. content: application/json: schema: type: object properties: release: $ref: '#/components/schemas/Release' changed: type: boolean '201': description: Created. content: application/json: schema: type: object properties: release: $ref: '#/components/schemas/Release' changed: type: boolean '400': description: The body has errors; `details` lists each one with its path. content: application/json: schema: $ref: '#/components/schemas/Error' examples: invalid_payload: value: error: invalid_payload message: The release has errors. account_required: value: error: account_required message: This key covers more than one account. Pass accountId. '401': description: No key, or a revoked key. content: application/json: schema: $ref: '#/components/schemas/Error' examples: missing_api_key: value: error: missing_api_key message: 'Send your API key as `Authorization: Bearer `.' invalid_api_key: value: error: invalid_api_key message: API key is invalid or has been revoked. '403': description: Not allowed. content: application/json: schema: $ref: '#/components/schemas/Error' examples: insufficient_scope: value: error: insufficient_scope message: This key does not grant delivery:write. api_access_disabled: value: error: api_access_disabled message: >- API access is not turned on for the accounts this key covers. release_creation_disabled: value: error: release_creation_disabled message: >- Release creation is turned off for this account. Contact your AMM Distro representative. submissions_paused: value: error: submissions_paused message: >- Release submissions are paused for this account. Contact your AMM Distro representative. '404': description: Unknown account. content: application/json: schema: $ref: '#/components/schemas/Error' examples: account_not_found: value: error: account_not_found message: Account not found for this key. '409': description: Conflict. content: application/json: schema: $ref: '#/components/schemas/Error' examples: release_locked: value: error: release_locked message: >- This release is in review and can no longer be changed through the API. upc_in_use: value: error: upc_in_use message: This UPC is already used by another release on AMM Distro. isrc_in_use: value: error: isrc_in_use message: >- An ISRC in this release belongs to a recording in another catalog. transfer_closed: value: error: transfer_closed message: >- Transfer nova-2026-11 was already submitted. Use a new transfer ID. '429': description: >- Rate limit reached. Wait for the time in the `RateLimit-Reset` header. content: application/json: schema: $ref: '#/components/schemas/Error' examples: rate_limited: value: error: rate_limited message: >- Rate limit of 60 requests per minute exceeded for this key. components: schemas: ReleaseInput: type: object required: - title - releaseDate - genre - artists - tracks properties: accountId: type: string description: Required when the key covers more than one account. title: type: string maxLength: 300 example: Night Drive version: type: string maxLength: 200 example: Deluxe type: type: string enum: - Single - EP - Album - Compilation description: 'Defaults from the track count: 1–3 Single, 4–6 EP, 7+ Album.' releaseDate: type: string format: date example: '2026-12-04' description: The date it goes live in stores. originalReleaseDate: type: string format: date example: '2019-04-01' description: >- Catalog transfers only: when it first came out. Can't be in the future. upc: type: string description: >- 12 or 13 digits with a valid check digit. Required for transfers; otherwise assigned at approval. example: '036000291452' catalogNumber: type: string maxLength: 100 language: type: string default: en genre: type: object required: - primary properties: primary: oneOf: - type: string - type: integer description: Genre name or ID from GET /reference/genres. example: Electronic secondary: oneOf: - type: string - type: integer cLine: type: string maxLength: 300 description: >- Copyright holder, without the year. Defaults to the account's, then the first artist. pLine: type: string maxLength: 300 description: Sound recording copyright holder, without the year. copyrightYear: type: integer minimum: 1900 description: Defaults to the release year (the original year for transfers). artists: type: array minItems: 1 maxItems: 20 items: $ref: '#/components/schemas/ArtistInput' description: At least one primary artist. artwork: $ref: '#/components/schemas/FileInput' transfer: type: object description: >- Marks this as a catalog transfer. Then `upc`, `originalReleaseDate` and every track's `isrc` are required. properties: batch: type: string description: Transfer ID to group it under; created on first use. example: nova-2026-11 previousDistributor: type: string maxLength: 200 tracks: type: array minItems: 1 maxItems: 100 items: $ref: '#/components/schemas/TrackInput' description: The full track list. A track left out of a later PUT is removed. Release: type: object properties: externalId: type: string example: NOVA-004 id: type: string description: AMM Distro's ID for the release. accountId: type: string kind: type: string enum: - new - transfer status: type: string enum: - draft - in_review - changes_requested - delivering - delivered - live - rejected - taken_down description: See the Statuses page. title: type: string version: type: - string - 'null' type: type: string releaseDate: type: - string - 'null' format: date originalReleaseDate: type: - string - 'null' format: date upc: type: - string - 'null' description: Appears once assigned. catalogNumber: type: - string - 'null' transfer: type: - object - 'null' properties: batch: type: - string - 'null' artwork: type: object properties: present: type: boolean description: Artwork is in place on the release. file: $ref: '#/components/schemas/FileStatus' tracks: type: array items: type: object properties: externalId: type: - string - 'null' id: type: string discNumber: type: integer trackNumber: type: integer title: type: string isrc: type: - string - 'null' durationMs: type: - integer - 'null' audio: type: object properties: present: type: boolean file: $ref: '#/components/schemas/FileStatus' storeLinks: type: object description: Fills in as stores go live. properties: spotify: type: string format: uri appleMusic: type: string format: uri deezer: type: string format: uri tidal: type: string format: uri amazonMusic: type: string format: uri youtubeMusic: type: string format: uri submittedAt: type: - string - 'null' format: date-time createdAt: type: string format: date-time updatedAt: type: string format: date-time Error: type: object required: - error - message properties: error: type: string description: Stable code to branch on. example: invalid_payload message: type: string description: What happened, in plain words. details: type: array description: >- Per-field problems (payload errors) or per-release problems (transfer submit). items: oneOf: - $ref: '#/components/schemas/PayloadProblem' - $ref: '#/components/schemas/Issue' - $ref: '#/components/schemas/TransferReleaseProblem' ArtistInput: type: object required: - name properties: name: type: string maxLength: 200 description: As it should appear in stores. example: Nova role: type: string enum: - primary - featuring default: primary spotifyId: type: string pattern: ^[A-Za-z0-9]{22}$ description: The artist's existing Spotify profile. example: 0OdUWJ0sBjDrqHygGUXeCF appleMusicId: type: string pattern: ^\d{1,15}$ description: The artist's existing Apple Music profile. example: '1234567890' legalFirstName: type: string maxLength: 100 description: Needed for every artist before submission. legalLastName: type: string maxLength: 100 spotifyProtection: $ref: '#/components/schemas/SpotifyProtection' FileInput: description: >- A file we download from your URL, or one you upload yourself. Leaving the field out of a later PUT keeps the current file. oneOf: - type: object title: From a URL required: - url additionalProperties: false properties: url: type: string format: uri description: >- HTTPS URL on an accepted host. Signed URLs are fine; keep them valid for at least a day. example: https://masters.s3.amazonaws.com/nova/night-drive.wav sha256: type: string pattern: ^[a-f0-9]{64}$ description: Optional. A downloaded file that doesn't match is refused. - type: object title: Upload it yourself required: - upload additionalProperties: false properties: upload: type: boolean const: true description: Reserve the slot; then request an upload URL for it. TrackInput: type: object required: - title properties: externalId: type: string pattern: ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$ description: >- Your ID for the track. With it, later updates change the same track even if it moves. discNumber: type: integer minimum: 1 maximum: 20 default: 1 trackNumber: type: integer minimum: 1 maximum: 999 description: Defaults to the track's position in the list. title: type: string maxLength: 300 version: type: string maxLength: 200 example: Sped Up isrc: type: string description: >- Required for catalog transfers. Leave it out for a new recording and one is assigned at approval. example: USRC12600001 iswc: type: string example: T1234567890 explicit: oneOf: - type: boolean - type: string enum: - clean default: false description: '`"clean"` marks an edited version.' language: type: string description: >- Lyrics language; defaults to the release language. `zxx` for instrumentals. example: en lyrics: type: string maxLength: 20000 compositionType: type: string enum: - original - cover - public_domain default: original aiUsage: type: string enum: - none - some - material - all default: none description: How much of the recording is AI-generated. artists: type: array items: $ref: '#/components/schemas/ArtistInput' description: Defaults to the release's artists. audio: $ref: '#/components/schemas/FileInput' credits: type: array maxItems: 50 items: $ref: '#/components/schemas/CreditInput' FileStatus: type: - object - 'null' properties: id: type: string description: Use as `fileId` for uploads. source: type: string enum: - url - upload status: type: string enum: - awaiting_upload - pending - ready - failed error: type: - string - 'null' description: Why the file can't be used (when failed). example: The artwork file is 1200×1200; artwork must be at least 1400×1400 details: type: object description: >- What we read from the file, e.g. width/height, or format, sampleRate, bitDepth, channels, durationMs. PayloadProblem: type: object required: - path - message properties: path: type: string description: Where in your request body the problem is. example: tracks[2].credits[0].roles[1] message: type: string example: '"Wizard" is not a known role (see GET /reference/credit-roles)' Issue: type: object required: - severity - message properties: severity: type: string enum: - error - warning rule: type: string description: Stable rule code, when the problem comes from a release rule. example: credit.production field: type: - string - 'null' example: credits track: type: object description: Which track, when the problem is on one. properties: externalId: type: - string - 'null' discNumber: type: integer trackNumber: type: integer message: type: string TransferReleaseProblem: type: object properties: externalId: type: string errors: type: array items: $ref: '#/components/schemas/Issue' SpotifyProtection: type: object required: - decision description: >- Needed once per Spotify profile, the first time a release goes to it. Requires spotifyId on the same artist. properties: decision: type: string enum: - not_enabled - artist_key - manual_approval description: >- `not_enabled`: the profile has no release protection. `artist_key`: send the artist key. `manual_approval`: the artist will approve the release in Spotify for Artists (it may be delayed). artistKey: type: string pattern: ^([0-9A-F]{5}-){4}[0-9A-F]{5}$ description: Required for `artist_key`. acknowledged: type: boolean description: Must be true for `manual_approval`. CreditInput: type: object required: - roles description: Give `firstName` and `lastName` (songwriters need both), or `name`. properties: firstName: type: string maxLength: 100 example: Nora lastName: type: string maxLength: 100 example: Vance name: type: string maxLength: 200 description: Credit name, if different from the legal name. roles: type: array minItems: 1 items: type: string description: Role names from GET /reference/credit-roles. example: - Composer - Producer - Vocals share: type: number exclusiveMinimum: 0 maximum: 100 description: >- Songwriting share in percent. Give it for every songwriter on the track (totalling 100) or for none (split evenly). ipi: type: string pattern: ^\d{9,11}$ description: Songwriter's IPI number. pro: type: string maxLength: 50 description: Songwriter's performing rights organisation. example: ASCAP securitySchemes: bearerAuth: type: http scheme: bearer description: An API key from Settings → API in AMM Distro. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.