# List Files

- **Method:** `GET`
- **Path:** `/api/v1/files`
- **Operation ID:** `list_files`
- **Tags:** files

This tenant's files, newest first. Metadata only: the API never serves an uploaded file back.

## Effective servers

- `https://api.saram.sh`

  Saram

## Authentication

- **HTTPBearer**: HTTP bearer

  a Saram API key (`sk_saram_<env>_...`) or a person's AuthKit access token, as `Authorization: Bearer <credential>`. Both are told apart by shape and produce the same principal.

## Responses

### 200 Successful Response

**Content type:** `application/json`

schema: `FileList`, no additional properties

The files this tenant has uploaded and not deleted, as metadata.

- **`files` (required)**: `array`

  This tenant's files, newest first.

  **Items:**

  schema: `FileRecord`, no additional properties

  One file this tenant uploaded, as `POST /api/v1/files` and the two read routes answer it.

  Metadata only, and deliberately: the API never serves an uploaded file's bytes back. Nothing needs them -
  the dashboard shows names - and `GET /api/v1/blobs` stays evidence-only, which is what keeps a `files/`
  key unreachable there. The tenant is not a field of its own: it is the ref's first segment, and it is
  always the tenant of whoever asked.
  - **`expires_at` (required)**: `string`

    When the file is deleted: its upload time plus how long this deployment keeps uploads. A run naming a file
    past this is refused at `POST /runs`.
  - **`media_type` (required)**: `string`
  - **`name` (required)**: `string`
  - **`ref` (required)**: `string`

    `saram-file://<tenant_id>/<file_id>`: what a run spec's `files[].ref` names, and the only handle a caller
    ever gets on the object. A file uploaded before files were a tenant's keeps the caller name it was uploaded
    under in that segment.
  - **`sha256` (required)**: `string`
  - **`size_bytes` (required)**: `integer`
  - **`uploaded_at` (required)**: `string`

**Example:**

```json
{
  "files": [
    {
      "ref": "",
      "name": "",
      "size_bytes": 1,
      "media_type": "",
      "sha256": "",
      "uploaded_at": "",
      "expires_at": ""
    }
  ]
}
```

### 403 the API key lacks the required scope

## Schemas

- `FileList` — shown above.
- `FileRecord` — shown above.