AthausDocs

Retrieve a file

Request, parameters, response and errors of GET /v1/files/{id}.

Last updated:

Returns the metadata of one file. The bytes come from GET /files/{id}/content. Needs read access to files.

Requires the scope read and at least the level read on files.

Try it in the console

Request

GET https://api.athaus.ai/v1/files/{id}

Parameters

Path

NameTypeRequiredDescription
idstring (uuid)yesUUID of the file.

Header

NameTypeRequiredDescription
Athaus-VersionstringnoOptional and carries nothing a client needs: the version is the path. Accepted when it says v1 or 1. Any other value is a 400 api_version_unsupported.
If-None-MatchstringnoAn ETag you hold. If it is still current, the answer is 304 without a body.

Example

curl "https://api.athaus.ai/v1/files/0190f3a2-7c1e-7b0e-9a41-5d2f6e8c3b17" \
  -H "Authorization: Bearer ath_live_..."

Response

On success the status is 200 with File.

File

FieldTypeDescription
objectstringAlways file.
idstringUUID of the file.
listingIdstring
kindstringOne of photo, floor_plan, document.
documentTypestring | nullFor a document, which paper it is, in the keys the app uses. Null if it was not sorted.
filenamestring | null
mimeTypestring | null
sizeBytesinteger | null
widthinteger | nullIn pixels, for an image where it is known.
heightinteger | nullIn pixels, for an image where it is known.
captionstring | null
positionintegerThe order within the property. Position 0 is the cover.
createdAtstring (date-time)

Response headers

HeaderDescription
Request-IdIdentifies this request. Quote it in a support request.
Athaus-VersionThe API version of this response: v1.
Athaus-ReleaseThe release of v1 that answered, for example 1.0. A label for support and changelogs; no request can select it.
ETagA strong entity tag of this state of the resource. Send it as If-Match to change or delete the resource only if it is unchanged, or as If-None-Match to read it only if it changed.
RateLimit-PolicyThe quota policy of the bucket that applies.
RateLimitRemaining quota and seconds until the bucket is full again.

With If-None-Match naming the current ETag, the operation answers 304 without a body.

Errors

Every error arrives as problem details. Branch on code, not on title or detail.

StatusCodesMeaning
400invalid_id, api_version_unsupported, invalid_inputInvalid request.
401unauthorizedMissing or invalid API key.
403insufficient_permissions, plan_requiredThe key lacks a right, or the plan does not include API access.
404not_foundNothing under this ID.
429rate_limitedRate limit exceeded.
500internal_errorServer error.

Keep reading

On this page