AtmosImportTask¶

An Atmos import task imports a Dolby Atmos audio file from an HTTPS URL and links it to a track as a record. You provide the source URL and the target track, then follow the import through its status field. IDs are UUIDs. Several fields (status, byteSize, actualMd5, validationErrors, record) are set by the system and are read-only.

Lists AtmosImportTasks¶

GET https://domain.com/api/v1/atmos-import-tasks

Headers¶

Name	Type	Description
Authorization*	String	Bearer \
Content-Type*	String	application/vnd.api+json

Response — 200 OK

{
  "data": [
    {
      "type": "atmos-import-tasks",
      "id": "01924f3b-2222-7000-bbbb-000000000002",
      "attributes": {
        "url": "https://cdn.example.com/audio/track-atmos.mp4",
        "secondaryIsrc": "USRC12345679",
        "declaredMd5": null,
        "status": "pending",
        "byteSize": null,
        "actualMd5": null,
        "validationErrors": null,
        "createdAt": "2025-05-27T10:00:00.000000Z",
        "updatedAt": "2025-05-27T10:00:00.000000Z"
      },
      "relationships": {
        "track": {
          "links": {
            "related": "https://domain.com/api/v1/atmos-import-tasks/<ID>/track",
            "self": "https://domain.com/api/v1/atmos-import-tasks/<ID>/relationships/track"
          }
        },
        "record": {
          "links": {
            "related": "https://domain.com/api/v1/atmos-import-tasks/<ID>/record",
            "self": "https://domain.com/api/v1/atmos-import-tasks/<ID>/relationships/record"
          }
        }
      },
      "links": {
        "self": "https://domain.com/api/v1/atmos-import-tasks/<ID>"
      }
    }
  ],
  "meta": {
    "page": {
      "currentPage": 1,
      "from": 1,
      "lastPage": 3,
      "perPage": 20,
      "to": 1,
      "total": 42
    }
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "first": "https://domain.com/api/v1/atmos-import-tasks?page[number]=1&page[size]=20",
    "last": "https://domain.com/api/v1/atmos-import-tasks?page[number]=3&page[size]=20",
    "next": "https://domain.com/api/v1/atmos-import-tasks?page[number]=2&page[size]=20"
  }
}

Filters¶

Filter	Example
ID	`/atmos-import-tasks?filter[id]=01924f3b-2222-7000-bbbb-000000000002`
Status	`/atmos-import-tasks?filter[status]=completed`
Track ID	`/atmos-import-tasks?filter[track-id]=01924f3b-1111-7000-aaaa-000000000001`

Status values¶

`status`	Meaning
`pending`	Import created; download not started yet (default on creation)
`downloading`	The file is being downloaded
`downloaded`	File downloaded successfully
`validating`	The file is being validated for Atmos compliance
`completed`	Import succeeded; a linked record has been created
`download_failed`	Download attempt failed
`validation_failed`	File failed Atmos validation

Get AtmosImportTask¶

GET https://domain.com/api/v1/atmos-import-tasks/:id

Path Parameters¶

Name	Type	Description
id*	UUID	AtmosImportTask ID

Headers¶

Name	Type	Description
Authorization*	String	Bearer \
Content-Type*	String	application/vnd.api+json

Response — 200 OK

{
  "data": {
    "type": "atmos-import-tasks",
    "id": "01924f3b-2222-7000-bbbb-000000000002",
    "attributes": {
      "url": "https://cdn.example.com/audio/track-atmos-v2.mp4",
      "secondaryIsrc": "USRC12345679",
      "declaredMd5": "d41d8cd98f00b204e9800998ecf8427e",
      "status": "completed",
      "byteSize": 524288000,
      "actualMd5": "d41d8cd98f00b204e9800998ecf8427e",
      "validationErrors": null,
      "createdAt": "2025-05-20T14:30:00.000000Z",
      "updatedAt": "2025-05-20T14:35:22.000000Z"
    },
    "relationships": {
      "track": {
        "links": {
          "related": "https://domain.com/api/v1/atmos-import-tasks/<ID>/track",
          "self": "https://domain.com/api/v1/atmos-import-tasks/<ID>/relationships/track"
        }
      },
      "record": {
        "links": {
          "related": "https://domain.com/api/v1/atmos-import-tasks/<ID>/record",
          "self": "https://domain.com/api/v1/atmos-import-tasks/<ID>/relationships/record"
        }
      }
    },
    "links": {
      "self": "https://domain.com/api/v1/atmos-import-tasks/<ID>"
    }
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "https://domain.com/api/v1/atmos-import-tasks/<ID>"
  }
}

Response — 404 Not Found

{
  "jsonapi": {
    "version": "1.0"
  },
  "errors": [
    {
      "status": "404",
      "title": "Not Found"
    }
  ]
}

Create AtmosImportTask¶

POST https://domain.com/api/v1/atmos-import-tasks

status starts at pending and may already have changed by the time you next poll it.

Headers¶

Name	Type	Description
Authorization*	String	Bearer \
Content-Type*	String	application/vnd.api+json

Request Body¶

Name	Type	Required	Description
url	String	Yes	HTTPS URL of the source Atmos file (HTTP rejected, max 2048 chars)
secondaryIsrc	String	Yes	ISRC assigned to the resulting record (12-char ISRC format; must be unique among valid Atmos records)
track	Object	Yes	Track resource (relationship)
declaredMd5	String	No	32-char hex MD5 checksum for integrity verification

Response — 201 Created

{
  "data": {
    "type": "atmos-import-tasks",
    "id": "01924f3b-2222-7000-bbbb-000000000002",
    "attributes": {
      "url": "https://cdn.example.com/audio/track-atmos.mp4",
      "secondaryIsrc": "USRC12345678",
      "declaredMd5": "d41d8cd98f00b204e9800998ecf8427e",
      "status": "pending",
      "byteSize": null,
      "actualMd5": null,
      "validationErrors": null,
      "createdAt": "2025-05-27T10:00:00.000000Z",
      "updatedAt": "2025-05-27T10:00:00.000000Z"
    },
    "relationships": {
      "track": {
        "links": {
          "related": "https://domain.com/api/v1/atmos-import-tasks/<ID>/track",
          "self": "https://domain.com/api/v1/atmos-import-tasks/<ID>/relationships/track"
        }
      },
      "record": {
        "links": {
          "related": "https://domain.com/api/v1/atmos-import-tasks/<ID>/record",
          "self": "https://domain.com/api/v1/atmos-import-tasks/<ID>/relationships/record"
        }
      }
    },
    "links": {
      "self": "https://domain.com/api/v1/atmos-import-tasks/<ID>"
    }
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "https://domain.com/api/v1/atmos-import-tasks/<ID>"
  }
}

Response — 422 Unprocessable Entity

{
  "jsonapi": {
    "version": "1.0"
  },
  "errors": [
    {
      "detail": "The secondary isrc has already been taken.",
      "source": {
        "pointer": "/data/attributes/secondaryIsrc"
      },
      "status": "422",
      "title": "Unprocessable Entity"
    }
  ]
}

Update AtmosImportTask¶

PATCH https://domain.com/api/v1/atmos-import-tasks/:id

Only url, secondaryIsrc and declaredMd5 (and the track relationship) are writable. The system-managed fields are read-only.

Path Parameters¶

Name	Type	Description
id*	UUID	AtmosImportTask ID

Headers¶

Name	Type	Description
Authorization*	String	Bearer \
Content-Type*	String	application/vnd.api+json

Request Body¶

Name	Type	Required	Description
url	String	No	HTTPS URL of the source Atmos file
secondaryIsrc	String	No	ISRC for the resulting record
declaredMd5	String	No	32-char hex MD5 checksum

Response — 200 OK

{
  "data": {
    "type": "atmos-import-tasks",
    "id": "01924f3b-2222-7000-bbbb-000000000002",
    "attributes": {
      "url": "https://cdn.example.com/audio/track-atmos-v2.mp4",
      "secondaryIsrc": "USRC12345679",
      "declaredMd5": null,
      "status": "pending",
      "byteSize": null,
      "actualMd5": null,
      "validationErrors": null,
      "createdAt": "2025-05-20T14:30:00.000000Z",
      "updatedAt": "2025-05-20T14:31:00.000000Z"
    },
    "relationships": {
      "track": {
        "links": {
          "related": "https://domain.com/api/v1/atmos-import-tasks/<ID>/track",
          "self": "https://domain.com/api/v1/atmos-import-tasks/<ID>/relationships/track"
        }
      },
      "record": {
        "links": {
          "related": "https://domain.com/api/v1/atmos-import-tasks/<ID>/record",
          "self": "https://domain.com/api/v1/atmos-import-tasks/<ID>/relationships/record"
        }
      }
    },
    "links": {
      "self": "https://domain.com/api/v1/atmos-import-tasks/<ID>"
    }
  },
  "jsonapi": {
    "version": "1.0"
  },
  "links": {
    "self": "https://domain.com/api/v1/atmos-import-tasks/<ID>"
  }
}

Delete AtmosImportTask¶

DELETE https://domain.com/api/v1/atmos-import-tasks/:id

Path Parameters¶

Name	Type	Description
id*	UUID	AtmosImportTask ID

Headers¶

Name	Type	Description
Authorization*	String	Bearer \
Content-Type*	String	application/vnd.api+json

Response — 204 No Content (delete OK, empty body)

Response — 404 Not Found

{
  "jsonapi": {
    "version": "1.0"
  },
  "errors": [
    {
      "status": "404",
      "title": "Not Found"
    }
  ]
}