# File Upload API
Landing: https://developers.vsee.io/api/file-upload-api  ·  Spec JSON: https://developers.vsee.io/specs/file_upload_api_openapi.json
Base URL: https://api.vseepreview.com/api_v3

## POST /files
URL: https://developers.vsee.io/api/file-upload-api/post/files
Auth: User Token — Requires a user access token from login or SSO.

Upload file

Upload a file with optional metadata

### File Categories (`meta.category`)
- `intake_attachment` — Per-visit files, only visible on the visit page.
- `user_consent` — User consent documents.
- `user_avatar` — User profile picture.
- `user_document` — Per-user profile documents, visible under the patient's Documents page and provider's Documents tab.

### Uploading on Behalf of a Patient
When using a clinic/admin token to upload for a patient, include:
- `meta.target.id` — The patient's user ID
- `meta.target.type` — Set to `user`

**Example (upload for patient):**
```
curl -X POST https://api.vseepreview.com/api_v3/files \
  -H 'X-ApiToken: {admin_token}' \
  -H 'X-AccountCode: {account_code}' \
  -F file=@/path/to/file.png \
  -F meta.target.id=20002340748 \
  -F meta.target.type=user \
  -F meta.category=user_document
```

Parameters:
- X-ApiToken (header, string, required) — API token
- X-AccountCode (header, string, required) — Account code

Request body (multipart/form-data):
- file (string, required) — Binary file content
- meta.title (string, optional) — File title
- meta.description (string, optional) — File description
- meta.target.id (string, optional) — Target ID (user ID or visit ID). Required if uploading for someone else
- meta.target.type (string, optional) — Target type (user or visit). Required if uploading for someone else
- meta.category (string, optional) — File category (intake_attachment, user_consent, user_avatar, user_document)

Example request:
```json
{
  "file": "binary",
  "meta.title": "string",
  "meta.description": "string",
  "meta.target.id": "string",
  "meta.target.type": "string",
  "meta.category": "string"
}
```

Responses:
- 200 — Successful upload
```json
{
  "data": {
    "id": "5e15d150-19b4-4cbd-b217-332fc71b6977",
    "name": "p878984.jpg",
    "size": 40679,
    "ext": "jpg",
    "fullpath": "https://vclinic.vseepreview.com/files/view/5e15d150-19b4-4cbd-b217-332fc71b6977?auth_code=e86ceb8b57c91e4db41611f08311a125e2df0b09&time=1578488144",
    "meta": {
      "category": "user_document",
      "target": {
        "id": "350936",
        "type": "user"
      },
      "account": {
        "code": "vclinic"
      }
    },
    "creator": {
      "id": "350936",
      "username": "test+member01@test.com",
      "email": "test+member01@test.com",
      "full_name": "Test User"
    }
  }
}
```

## GET /files
URL: https://developers.vsee.io/api/file-upload-api/get/files
Auth: User Token — Requires a user access token from login or SSO.

List files

Retrieve list of files with optional filtering

Parameters:
- X-ApiToken (header, string, required) — API token
- X-AccountCode (header, string, required) — Account code
- target_id (query, string, optional) — The ID of the target (user_id or visit_id)
- target_type (query, string, optional) — Target type (user or visit) [enum: user, visit]
- category_type (query, string, optional) — File category type (user_document, intake_attachment, user_consent, user_avatar)
- include_shared (query, boolean, optional) — Include shared files

Responses:
- 200 — Successful response
```json
{
  "data": [
    {
      "created": 1657668358,
      "creator": {
        "full_name": "Patient's Name",
        "type": 200,
        "username": "62ce09a2940adc6474"
      },
      "ext": "pdf",
      "fullpath": "https://api-vclinic.vsee.me/files/view/62ce0306-bd68-8fj3-7771-6dfc0ks8219474?auth_code=bb7e2d413f9jd93unf92u4e35584d10&time=1669924552",
      "id": "62ce0306-bd68-8fj3-7771-6dfc0ks8219474",
      "is_deletable": true,
      "meta": {
        "account": {
          "code": "vclinic"
        },
        "category": "user_document",
        "target": {
          "id": "2317820300",
          "type": "user"
        }
      },
      "name": "2017-01-21 04:00:00 - filename.pdf",
      "size": 274988
    }
  ]
}
```

## GET /files/{id}
URL: https://developers.vsee.io/api/file-upload-api/get/files/%7Bid%7D
Auth: User Token — Requires a user access token from login or SSO.

Get file info

Retrieve file information including download link

Parameters:
- X-ApiToken (header, string, required) — API token
- X-AccountCode (header, string, required) — Account code
- id (path, string, required) — File ID

Responses:
- 200 — Successful response
```json
{
  "data": {
    "id": "57e8c9a2-5c30-4b2c-b9d0-11d6ac1f0144",
    "name": "Screenshot 2023-02-22 at 21.47.43.png",
    "size": 25473,
    "ext": "png",
    "fullpath": "https://api-vclinic.vsee.me/files/view/57e8c9a2-5c30-4b2c-b9d0-11d6ac1f0144?auth_code=01f72b633c40c73a87f1bc66694ee31&time=1677099046",
    "meta": {
      "target": {
        "id": "63f67fb0-9864-4059-ad1b-63b10adc6474",
        "type": "intake"
      },
      "category": "intake_attachment",
      "account": {
        "code": "vclinic"
      }
    },
    "creator": {
      "username": "anton+test2@vseelab.com",
      "type": 200,
      "full_name": "anton test_2",
      "id": "27769243"
    },
    "created": 1677098901
  }
}
```

## POST /files/{id}
URL: https://developers.vsee.io/api/file-upload-api/post/files/%7Bid%7D
Auth: User Token — Requires a user access token from login or SSO.

Update file info

Modify file information (name, title, description)

Currently only the `name` field can be modified (deprecated in favor of `meta.title` — coming soon).

Parameters:
- X-ApiToken (header, string, required) — API token
- X-AccountCode (header, string, required) — Account code
- id (path, string, required) — File ID

Request body (application/x-www-form-urlencoded):
- name (string, optional) — File name
- meta.title (string, optional) — File title
- meta.description (string, optional) — File description

Example request:
```json
{
  "name": "string",
  "meta.title": "string",
  "meta.description": "string"
}
```

Responses:
- 200 — Successful update
```json
{
  "data": {
    "id": "5e1598e7-4118-47ca-84da-0923c71b6977",
    "name": "test2.jpg",
    "size": 184259,
    "ext": "jpg",
    "meta": {
      "target": {
        "id": "350936",
        "type": "user"
      },
      "category": "user_document"
    }
  }
}
```

## DELETE /files/{id}
URL: https://developers.vsee.io/api/file-upload-api/delete/files/%7Bid%7D
Auth: User Token — Requires a user access token from login or SSO.

Delete file

Delete a file

Parameters:
- X-ApiToken (header, string, required) — API token
- X-AccountCode (header, string, required) — Account code
- id (path, string, required) — File ID

Responses:
- 200 — Successful deletion
```json
{
  "data": true
}
```

## GET /files/view/{id}
URL: https://developers.vsee.io/api/file-upload-api/get/files/view/%7Bid%7D
Auth: User Token — Requires a user access token from login or SSO.

Download file

Download the file content. Parameters available for authenticated access.

**Note:** The file view URL includes an `auth_code` and `time` parameter for secure, time-limited access.

Parameters:
- X-ApiToken (header, string, required) — API token
- X-AccountCode (header, string, required) — Account code
- id (path, string, required) — File ID
- auth_code (query, string, optional) — Authentication code from file info response
- time (query, string, optional) — Timestamp from file info response
- size (query, string, optional) — Optional resized image dimensions (WxH format, e.g. 320x240)

Responses:
- 200 — File content
```json
binary
```