Graphon API

S3 · Objects

HeadObject

HEAD/{bucket}/{key}

Reads the headers of an object, with no body.

Returns the same headers as GetObject. Use it to read the size, ETag, or version of an object without a download.

View as Markdown
Role
Viewer or higher
Support
Supported
Auth
SigV4 with your API key
  • The same headers as GetObject, with no body. A public-read bucket needs no signature.
  • An unsigned HEAD works on a bucket with the public-read permission.

Path parameters

bucketstringrequired

The bucket name.

keystringrequired

The object key. Keep each / as it is. Percent-encode the other reserved characters.

Query parameters

versionIdstringoptional

Read this version. Without it, storage reads the current version.

Headers

If-Matchstringoptional

Return the object only when its ETag matches. Otherwise, storage returns 412 PreconditionFailed.

If-None-Matchstringoptional

Return 304 Not Modified when the ETag matches. Use it to revalidate a cached copy.

If-Modified-Sincestringoptional

An HTTP date. Return 304 Not Modified when the object did not change after it. Storage ignores it when you send If-None-Match.

If-Unmodified-Sincestringoptional

An HTTP date. Return 412 PreconditionFailed when the object changed after it. Storage ignores it when you send If-Match.

x-amz-expected-bucket-ownerstringoptional

The workspace ID that must own the bucket. Another owner returns 403 AccessDenied.

Responses

200OK

The headers of the object.

Response headers

ETagstring

The entity tag of the object, in double quotes.

Content-Typestring

The media type that the write stored.

Content-Lengthinteger

The size of the object in bytes.

Last-Modifiedstring

When the version was written, as an HTTP date.

Accept-Rangesstring

Always bytes.

x-amz-version-idstring

The version ID of the object. Storage gives every write a version ID.

Cache-Control, Content-Disposition, Content-Encoding, Content-Languagestring

Each header that the write stored. When the object has a Content-Encoding, Cache-Control also has no-transform, so the bytes arrive as stored.

x-amz-checksum-*string

Each checksum that the write stored, such as x-amz-checksum-sha256.

This response has no body.

304Not Modified

If-None-Match or If-Modified-Since matched.

Response headers

ETagstring

The entity tag of the object, in double quotes.

x-amz-version-idstring

The version ID of the object. Storage gives every write a version ID.

This response has no body.

Errors

Select an error in the response example to see its XML body. Any request can also get the common errors, such as SignatureDoesNotMatch.

404NoSuchKey

The bucket has no object at this key, or no version with this versionId.

What to do: Check the key and the versionId.

404NoSuchBucket

No bucket has this name, or the bucket was deleted.

What to do: Check the bucket name. ListBuckets shows the buckets of the workspace.

403AccessDenied

The key does not have the role for this operation, or the bucket is in another workspace.

What to do: Use a key of the workspace that owns the bucket, with the role above.

405MethodNotAllowed

The versionId names a delete marker, which has no bytes.

What to do: Use the versionId of a version that holds data. ListObjectVersions shows each one.

412PreconditionFailed

If-Match or If-Unmodified-Since did not hold.

What to do: Read the object again to get its current ETag, then decide whether to retry.

Was this page helpful?