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

# Register an 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 Object `objectId` on Storage Backend `storage_id`
- Copy the 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.

API instances SHALL NOT cascade the creation of new Object instances to initialisation Objects.
Clients MUST initiate the creation of new Object instances of initialisation Objects directly.

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 Object instance in the store.
  - object — Request the duplication of a 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 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 Object. Clients should include credentials if the provide URL is on the same origin as the API endpoint
    - `label` string, required — Label identifying this 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 Object.
- `404` — The Object does not exist. 404 MUST be returned if the ID has been assigned via the [`/flows/{flowId}/storage`](#/operations/POST_flows-flowId-storage), but not yet registered against a Flow Segment.

## Changes

> 23 revisions in range; 17 could not be searched.

- **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/eb3977b33601/schema)