> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usehasp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Files

> Upload files once, reference them across inference requests, and retrieve or delete them — with the same BAA gate, malware scan, and audit trail as any other PHI-bearing surface.

Files are org-scoped binary objects you upload once and reference by id. Uploads are virus-scanned before they become retrievable and are covered by the same BAA requirement as every other endpoint — see [BAA gating](/ai-api/concepts/baa-gating).

## Upload a file

```
POST https://api.usehasp.com/v1/files
Authorization: Bearer hasp_api_live_...
Content-Type: multipart/form-data
```

### Body

| Field     | Type   | Description                                                                   |
| --------- | ------ | ----------------------------------------------------------------------------- |
| `file`    | file   | **Required.** The file to upload.                                             |
| `purpose` | string | Optional free-form label (max 64 characters) describing what the file is for. |

```bash theme={null}
curl -X POST https://api.usehasp.com/v1/files \
  -H "Authorization: Bearer hasp_api_live_<key>" \
  -F "file=@intake-form.pdf" \
  -F "purpose=intake"
```

An upload that fails the malware scan is rejected with `MALWARE_DETECTED` and no file is stored.

## List files

```
GET https://api.usehasp.com/v1/files
Authorization: Bearer hasp_api_live_...
```

Cursor-paginated, scoped to the caller's org. See [Pagination](/ai-api/concepts/pagination).

## Retrieve metadata

```
GET https://api.usehasp.com/v1/files/{id}
Authorization: Bearer hasp_api_live_...
```

Returns the file's metadata — id, purpose, size, content type, scan state, and creation time. It does not return the bytes.

## Download content

```
GET https://api.usehasp.com/v1/files/{id}/content
Authorization: Bearer hasp_api_live_...
```

Returns the stored bytes. This is a content read, so it is recorded in the audit chain as a disclosure — the metadata endpoint above is not.

## Delete a file

```
DELETE https://api.usehasp.com/v1/files/{id}
Authorization: Bearer hasp_api_live_...
```

Deletes the record and the underlying storage object. Files belonging to another org return `404`.

## Errors

| Code                | HTTP | Meaning                                                        |
| ------------------- | ---- | -------------------------------------------------------------- |
| `MALWARE_DETECTED`  | 422  | The upload failed the virus scan and was not stored.           |
| `VALIDATION_FAILED` | 422  | Missing file, or `purpose` longer than 64 characters.          |
| `NOT_FOUND`         | 404  | No such file in the caller's org.                              |
| `BAA_REQUIRED`      | 402  | No active BAA — see [BAA gating](/ai-api/concepts/baa-gating). |