---
title: "Register a Media Object instance"
method: POST
path: "/objects/{objectId}/instances"
tags: ["Objects"]
---

# Register a Media Object instance

`POST /objects/{objectId}/instances`

Request the service to create an Object instance on a new Storage Backend. Or add a new uncontrolled URL to `get_urls`.

To request the duplication of the Object to a new Storage Backend, clients POST a `storage_id` to this endpoint that does not currently have an instance of the Object. The API will then:

- Allocate storage for Media Object `objectId` on Storage Backend `storage_id`
- Copy the Media Object from an existing location to the newly allocated storage
- Start advertising the new copy in `get_urls` once ready

The API instances SHOULD be capable of handling the case where the only existant instances are uncontrolled.

Where a client has written a new uncontrolled Object instance, the client is responsible for ensuring that the Object written is complete and correct before registering it with this method.

All instances of an Object MUST be identical.

## Path parameters

- `objectId` string, required

## Request body

- union — Register a Media Object instance in the store.
  - object — Request the duplication of a Media Object instance to a new Storage Backend, via it's `storage_id`.
    - `storage_id` string, required — A Universally Unique Identifier (UUID) as defined in [RFC9562](https://www.rfc-editor.org/rfc/rfc9562)
  - object — Register an uncontrolled Media Object instance via its `url`.
    - `url` string, required — A URL to which a GET request can be made to directly retrieve the contents of the media object. Clients should include credentials if the provide URL is on the same origin as the API endpoint
    - `label` string, required — Label identifying this Media Object instance. Service implementations should reject any requests using labels that are already associated with Storage Backends.

## Response `201`

Object instance successfully registered.

## Other responses

- `400` — Bad request. Invalid request JSON.
- `403` — Forbidden. You do not have permission to modify this Media Object.
- `404` — The Media Object does not exist.

## Changes

- **2025-10-21** `4c8d2bfcb854` — 1 breaking
  - the request property `oneOf[subschema #2: Uncontrolled instance]/label` became required
- **2025-10-16** `b23d7880c91d` — 1 info
  - endpoint added
- **2025-04-24** `b01aaf8cffe2` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/aws-samples/apis/time-addressable-media-store/changes/objects/:objectId/instances/post.md)

---

[API](https://skmtc.dev/aws-samples/apis/time-addressable-media-store.md) · [All operations](https://skmtc.dev/aws-samples/apis/time-addressable-media-store/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/aws-samples/time-addressable-media-store/revisions/4c8d2bfcb854/schema)