# Files

> Upload files and list them, to attach to journals.

Part of the [Prosaic API reference](https://developer.prosaic.works/docs/api.md). Base URL: `https://app.prosaic.works/api/public/v1`. Authenticate with `Authorization: Bearer <API key or access token>`.

## List files

`GET /api/public/v1/entities/{entityId}/files`

SDK: `prosaic.files.list(entityId, params)`

Returns the entity's files, newest first: those filed under it or attached to it,
excluding deleted files. Use a file's `id` in `fileIds` when creating a journal
(`POST /api/public/v1/entities/{entityId}/journals`) or attaching files to one.
Requires API key authentication and entity access.

### Path parameters

- `entityId` (string, required)

### Query parameters

- `search` (string): Part of the file name, matched in any case.
- `limit` (integer): Most files to return. Default: `20`.

### Responses

- `200`: Successful response
  - `data` (array of objects, required)
    - `id` (string, required)
    - `name` (string, required)
    - `contentType` (string, required)
    - `size` (number, required)
    - `createdAt` (string, required)
  - `meta` (object)
    - `count` (number, required)
- `400`: Invalid query parameters
- `401`: Invalid or missing API key
- `404`: Entity not found or not accessible

### Example (Node SDK)

```ts
const { data } = await prosaic.files.list(entityId);
```

### Example (curl)

```bash
curl https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/files \
  -H "Authorization: Bearer $PROSAIC_API_KEY"
```

## Upload a file

`POST /api/public/v1/entities/{entityId}/files/upload`

SDK: `prosaic.files.upload(entityId, file)`

Uploads a file for an entity. Files must be validated against size (20MB) and type restrictions. Returns a fileId that can be used when creating or attaching to journals. Requires API key authentication and entity access.

### Path parameters

- `entityId` (string, required)

### Request body

Content type: `multipart/form-data`

- `file` (string, binary, required): The file to upload (max 20MB). Accepted types — PDF, JPEG, PNG, GIF, WebP, CSV, plain text, Excel (XLS/XLSX), Word (DOC/DOCX), Outlook MSG.

### Responses

- `201`: Successful response
  - `success` (boolean, required)
  - `file` (object, required)
    - `id` (string, required)
    - `filename` (string, required)
    - `name` (string, required)
    - `contentType` (string, required)
    - `size` (number, required)
    - `createdAt` (string, required)
- `400`: Bad request - validation failed
  - `error` (string)
  - `code` (string)
- `401`: Unauthorized - Invalid or missing API key
  - `error` (string)
- `403`: Forbidden - No access to the specified entity
  - `error` (string)
  - `code` (string)
- `500`: Internal server error - Upload failed
  - `error` (string)

### Example (Node SDK)

```ts
const result = await prosaic.files.upload(entityId, file);
```

### Example (curl)

```bash
curl -X POST https://app.prosaic.works/api/public/v1/entities/$ENTITY_ID/files/upload \
  -H "Authorization: Bearer $PROSAIC_API_KEY" \
  -F "file=@receipt.pdf"
```