# Object Store API

For details on how to use this API, see Using OpenStack Object Store

## The Object Store Class

The Object Store high-level interface is exposed as the `object_store` object on `Connection` objects.

### Account Operations

class openstack.object_store.v1._proxy.Proxy(session, *, service_type=None, service_name=None, interface=None, region_name=None, endpoint_override=None, version=None, auth=None, user_agent=None, connect_retries=None, logger=None, allow=None, additional_headers=None, client_name=None, client_version=None, allow_version_hack=None, global_request_id=None, min_version=None, max_version=None, default_microversion=None, status_code_retries=None, retriable_status_codes=None, raise_exc=None, rate_limit=None, concurrency=None, connect_retry_delay=None, status_code_retry_delay=None, statsd_client=None, statsd_prefix=None, prometheus_counter=None, prometheus_histogram=None, influxdb_config=None, influxdb_client=None)
  get_account_metadata()

    Get metadata for this account.

    Return type:

      `Account`

  set_account_metadata(**metadata)

    Set metadata for this account.

    Parameters:

      metadata (kwargs) – Key/value pairs to be set as metadata on the container. Custom metadata can be set. Custom metadata are keys and values defined by the user.

  delete_account_metadata(keys)

    Delete metadata for this account.

    Parameters:

      keys – The keys of metadata to be deleted.

### Container Operations

class openstack.object_store.v1._proxy.Proxy(session, *, service_type=None, service_name=None, interface=None, region_name=None, endpoint_override=None, version=None, auth=None, user_agent=None, connect_retries=None, logger=None, allow=None, additional_headers=None, client_name=None, client_version=None, allow_version_hack=None, global_request_id=None, min_version=None, max_version=None, default_microversion=None, status_code_retries=None, retriable_status_codes=None, raise_exc=None, rate_limit=None, concurrency=None, connect_retry_delay=None, status_code_retry_delay=None, statsd_client=None, statsd_prefix=None, prometheus_counter=None, prometheus_histogram=None, influxdb_config=None, influxdb_client=None)
  containers(**query)

    Obtain Container objects for this account.

    Parameters:

      query (kwargs) – Optional query parameters to be sent to limit the resources being returned.

    Return type:

      A generator of `Container` objects.

  create_container(name, **attrs)

    Create a new container from attributes

    Parameters:

      - container – Name of the container to create.

      - attrs (dict) – Keyword arguments which will be used to create a `Container`, comprised of the properties on the Container class.

    Returns:

      The results of container creation

    Return type:

      `Container`

  delete_container(container, ignore_missing=True)

    Delete a container

    Parameters:

      - container – The value can be either the name of a container or a `Container` instance.

      - ignore_missing (bool) – When set to `False` `NotFoundException` will be raised when the container does not exist. When set to `True`, no exception will be set when attempting to delete a nonexistent server.

    Returns:

      `None`

  get_container_metadata(container)

    Get metadata for a container

    Parameters:

      container – The value can be the name of a container or a `Container` instance.

    Returns:

      One `Container`

    Raises:

      `NotFoundException` when no resource can be found.

  set_container_metadata(container, refresh=True, **metadata)

    Set metadata for a container.

    Parameters:

      - container – The value can be the name of a container or a `Container` instance.

      - refresh – Flag to trigger refresh of container object re-fetch.

      - metadata (kwargs) –

        Key/value pairs to be set as metadata on the container. Both custom and system metadata can be set. Custom metadata are keys and values defined by the user. System metadata are keys defined by the Object Store and values defined by the user. The system metadata keys are:

        - content_type

        - is_content_type_detected

        - versions_location

        - read_ACL

        - write_ACL

        - sync_to

        - sync_key

  delete_container_metadata(container, keys)

    Delete metadata for a container.

    Parameters:

      - container – The value can be the ID of a container or a `Container` instance.

      - keys – The keys of metadata to be deleted.

### Object Operations

class openstack.object_store.v1._proxy.Proxy(session, *, service_type=None, service_name=None, interface=None, region_name=None, endpoint_override=None, version=None, auth=None, user_agent=None, connect_retries=None, logger=None, allow=None, additional_headers=None, client_name=None, client_version=None, allow_version_hack=None, global_request_id=None, min_version=None, max_version=None, default_microversion=None, status_code_retries=None, retriable_status_codes=None, raise_exc=None, rate_limit=None, concurrency=None, connect_retry_delay=None, status_code_retry_delay=None, statsd_client=None, statsd_prefix=None, prometheus_counter=None, prometheus_histogram=None, influxdb_config=None, influxdb_client=None)
  objects(container, **query)

    Return a generator that yields the Container’s objects.

    Parameters:

      - container (`Container`) – A container object or the name of a container that you want to retrieve objects from.

      - query (kwargs) – Optional query parameters to be sent to limit the resources being returned.

    Return type:

      A generator of `Object` objects.

  get_object(obj, container=None, resp_chunk_size=1024, outfile=None, remember_content=False)

    Get the data associated with an object

    Parameters:

      - obj – The value can be the name of an object or a `Object` instance.

      - container – The value can be the name of a container or a `Container` instance.

      - resp_chunk_size (int) – chunk size of data to read. Only used if the results are being written to a file or stream is True. (optional, defaults to 1k)

      - outfile – Write the object to a file instead of returning the contents. If this option is given, body in the return tuple will be None. outfile can either be a file path given as a string, or a File like object.

      - remember_content (bool) – Flag whether object data should be saved as data property of the Object. When left as false and outfile is not defined data will not be saved and need to be fetched separately.

    Returns:

      Instance of the `Object` objects.

    Raises:

      `NotFoundException` when no resource can be found.

  download_object(obj, container=None, **attrs)

    Download the data contained inside an object.

    Parameters:

      - obj – The value can be the name of an object or a `Object` instance.

      - container – The value can be the name of a container or a `Container` instance.

    Raises:

      `NotFoundException` when no resource can be found.

  upload_object(container, name, filename=None, md5=None, sha256=None, segment_size=None, use_slo=True, metadata=None, generate_checksums=None, data=None, **headers)

    Create a file object.

    Automatically uses large-object segments if needed.

    Parameters:

      - container – The name of the container to store the file in. This container will be created if it does not exist already.

      - name – Name for the object within the container.

      - filename – The path to the local file whose contents will be uploaded. Mutually exclusive with data.

      - data – The content to upload to the object. Mutually exclusive with filename.

      - md5 – A hexadecimal md5 of the file. (Optional), if it is known and can be passed here, it will save repeating the expensive md5 process. It is assumed to be accurate.

      - sha256 – A hexadecimal sha256 of the file. (Optional) See md5.

      - segment_size – Break the uploaded object into segments of this many bytes. (Optional) SDK will attempt to discover the maximum value for this from the server if it is not specified, or will use a reasonable default.

      - headers – These will be passed through to the object creation API as HTTP Headers.

      - use_slo – If the object is large enough to need to be a Large Object, use a static rather than dynamic object. Static Objects will delete segment objects when the manifest object is deleted. (optional, defaults to True)

      - generate_checksums – Whether to generate checksums on the client side that get added to headers for later prevention of double uploads of identical data. (optional, defaults to True)

      - metadata – This dict will get changed into headers that set metadata of the object

    Raises:

      `:class:`~openstack.exceptions.SDKException`` on operation error.

  copy_object()

    Copy an object.

  delete_object(obj, ignore_missing=True, container=None)

    Delete an object

    Parameters:

      - obj – The value can be either the name of an object or a `Container` instance.

      - container – The value can be the ID of a container or a `Container` instance.

      - ignore_missing (bool) – When set to `False` `NotFoundException` will be raised when the object does not exist. When set to `True`, no exception will be set when attempting to delete a nonexistent server.

    Returns:

      `None`

  get_object_metadata(obj, container=None)

    Get metadata for an object.

    Parameters:

      - obj – The value can be the name of an object or a `Object` instance.

      - container – The value can be the ID of a container or a `Container` instance.

    Returns:

      One `Object`

    Raises:

      `NotFoundException` when no resource can be found.

  set_object_metadata(obj, container=None, **metadata)

    Set metadata for an object.

    Note: This method will do an extra HEAD call.

    Parameters:

      - obj – The value can be the name of an object or a `Object` instance.

      - container – The value can be the name of a container or a `Container` instance.

      - metadata (kwargs) –

        Key/value pairs to be set as metadata on the container. Both custom and system metadata can be set. Custom metadata are keys and values defined by the user. System metadata are keys defined by the Object Store and values defined by the user. The system metadata keys are:

        - content_type

        - content_encoding

        - content_disposition

        - delete_after

        - delete_at

        - is_content_type_detected

  delete_object_metadata(obj, container=None, keys=None)

    Delete metadata for an object.

    Parameters:

      - obj – The value can be the name of an object or a `Object` instance.

      - container – The value can be the ID of a container or a `Container` instance.

      - keys – The keys of metadata to be deleted.

this page last updated: 2026-01-16 23:06:19

Except where otherwise noted, this document is licensed under Creative Commons Attribution 3.0 License. See all OpenStack Legal Documents.