# Get File

In DAM, files are identified by their filename (`reference`), which is unique per tenant.
Use this endpoint to retrieve a specific file when you already know its filename.
## Authentication
Requires a valid API key in the `X-API-KEY` header.
## Example

```
GET /files(product-datasheet.pdf)
X-API-KEY: your-api-key-here
```
## Response (200 OK)
The file is wrapped in the house entity envelope — its fields are under `value`, never at the
top level:

```json
{
  "value": {
    "reference": "product-datasheet.pdf",
    "numLinks": 3,
    "status": "Ok",
    "modifiedOn": "2024-04-05T08:44:33",
    "fileType": "pdf",
    "createdOn": "2024-04-05T08:44:33",
    "tags": ["datasheets", "catalog"],
    "url": "https://cdn.example.com/product-datasheet.pdf",
    "sizeInBytes": 102400
  },
  "@readLink": "https://api2.saleslayer.com/dam/files(product-datasheet.pdf)",
  "@editLink": "https://api2.saleslayer.com/dam/files(product-datasheet.pdf)"
}
```
Notes on the payload:
- `status` tells you whether the file is usable yet — see the status values documented on
`GET /files`.
- `url` and `sizeInBytes` come from the stored metadata and are empty / `0` until processing has
recorded them.
- `tags` is stored as a comma-separated string, so a tag that itself contains a comma comes back
split into several tags.
- `@readLink` and `@editLink` are the canonical URL of this file (this request, echoed back), and
are only emitted when hypermedia enrichment is configured for the deployment.

## Error Responses
- **401 Unauthorized**: Missing or invalid API key. Returned by the API gateway as
`{ "message": "Unauthorized", "request_id": "d8aafa5b8f3e400b60bea0123dd33317" }`
- **403 Forbidden**: The API key does not have read permissions for this operation. Same body
shape as the 401
- **404 Not Found**: No file with the given reference exists for this tenant. The body is the
message string, e.g. `"File with reference 'missing.pdf' was not found."`
- **500 Internal Server Error**: Technical error (e.g. database unavailable)

Endpoint: GET /files({reference})
Version: 2.0.0

## Path parameters:

  - `reference` (string, required)
    File name, unique per tenant (e.g. `product-datasheet.pdf`)

## Header parameters:

  - `X-API-KEY` (string, required)
    Tenant's API key (required)

## Response 200 fields (application/json):

  - `value` (object)
    A file asset.

  - `value.reference` (string)
    The file's filename, unique per tenant. This is the public key used to address the file and the
value entities use to reference it.

  - `value.numLinks` (integer)
    Number of entities (products, variants, categories, …) currently using this file.

  - `value.status` (string)
    Processing status: `Vd` (void), `Up` (uploading/updating), `Ok` (ready to use),
`Re` (reprocessing), `Er` (processing failed) or `Dv` (deleted). Only `Ok`
guarantees the stored file is usable.

  - `value.modifiedOn` (string)
    When the file was last modified.

  - `value.fileType` (string)
    File extension of the file, without the dot (e.g. `pdf`, `csv`). Derived from the
filename, not from the served Content-Type.

  - `value.createdOn` (string)
    When the file was created. Null for files predating creation-date tracking.

  - `value.tags` (array)
    Tags assigned to the file. Stored as a comma-separated string, so a tag containing a comma is
read back as several tags. Not usable in `$filter` or `$orderby`.

  - `value.url` (string)
    URL of the stored file. Empty until processing has run.

  - `value.sizeInBytes` (integer)
    Size of the file in bytes; `0` until processing has recorded it. Not usable in
`$filter` or `$orderby`.

  - `@readLink` (string)
    Canonical URL of this file — this request, echoed back. Present only when hypermedia enrichment
is enabled.

  - `@editLink` (string)
    URL to modify this file, identical to `@readLink`. Present only when hypermedia enrichment
is enabled.

## Response 401 fields (application/json):

  - `message` (string)
    Error description, e.g. `Unauthorized`.

  - `request_id` (string)
    Gateway request identifier, to quote when contacting support.

## Response 403 fields (application/json):

  - `message` (string)

  - `request_id` (string)

## Response 500 fields (application/json):

  - `error` (string)

  - `details` (any)