{ "openapi": "3.0.3", "info": { "title": "File Upload API", "version": "3.0", "contact": { "email": "admin@vsee.com" } }, "servers": [ { "url": "https://api.vseepreview.com/api_v3", "description": "Staging" } ], "x-readme": { "explorer-enabled": false, "proxy-enabled": false, "samples-languages": [ "curl", "python", "javascript", "java" ] }, "paths": { "/files": { "post": { "summary": "Upload file", "description": "Upload a file with optional metadata\n\n### File Categories (`meta.category`)\n- `intake_attachment` \u2014 Per-visit files, only visible on the visit page.\n- `user_consent` \u2014 User consent documents.\n- `user_avatar` \u2014 User profile picture.\n- `user_document` \u2014 Per-user profile documents, visible under the patient's Documents page and provider's Documents tab.\n\n### Uploading on Behalf of a Patient\nWhen using a clinic/admin token to upload for a patient, include:\n- `meta.target.id` \u2014 The patient's user ID\n- `meta.target.type` \u2014 Set to `user`\n\n**Example (upload for patient):**\n```\ncurl -X POST https://api.vseepreview.com/api_v3/files \\\n -H 'X-ApiToken: {admin_token}' \\\n -H 'X-AccountCode: {account_code}' \\\n -F file=@/path/to/file.png \\\n -F meta.target.id=20002340748 \\\n -F meta.target.type=user \\\n -F meta.category=user_document\n```", "tags": [ "File Upload" ], "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" }, { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" } ], "requestBody": { "description": "File upload with metadata", "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "Binary file content" }, "meta.title": { "type": "string", "description": "File title" }, "meta.description": { "type": "string", "description": "File description" }, "meta.target.id": { "type": "string", "description": "Target ID (user ID or visit ID). Required if uploading for someone else" }, "meta.target.type": { "type": "string", "description": "Target type (user or visit). Required if uploading for someone else" }, "meta.category": { "type": "string", "description": "File category (intake_attachment, user_consent, user_avatar, user_document)" } }, "required": [ "file" ] } } } }, "responses": { "200": { "description": "Successful upload", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "size": { "type": "integer" }, "ext": { "type": "string" }, "fullpath": { "type": "string" }, "meta": { "type": "object" }, "creator": { "type": "object" } } } } }, "examples": { "File Uploaded": { "value": { "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" } } } } } } } } }, "x-auth-type": "user-token" }, "get": { "summary": "List files", "description": "Retrieve list of files with optional filtering", "tags": [ "File Upload" ], "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" }, { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" }, { "name": "target_id", "in": "query", "description": "The ID of the target (user_id or visit_id)", "required": false, "schema": { "type": "string" }, "example": "2317820300" }, { "name": "target_type", "in": "query", "description": "Target type (user or visit)", "required": false, "schema": { "type": "string", "enum": [ "user", "visit" ] }, "example": "user" }, { "name": "category_type", "in": "query", "description": "File category type (user_document, intake_attachment, user_consent, user_avatar)", "required": false, "schema": { "type": "string" }, "example": "user_document" }, { "name": "include_shared", "in": "query", "description": "Include shared files", "required": false, "schema": { "type": "boolean" }, "example": true } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "size": { "type": "integer" }, "ext": { "type": "string" }, "fullpath": { "type": "string" }, "meta": { "type": "object" } } } } } }, "examples": { "Files List": { "value": { "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 } ] } } } } } } }, "x-auth-type": "user-token" } }, "/files/{id}": { "get": { "summary": "Get file info", "description": "Retrieve file information including download link", "tags": [ "File Upload" ], "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" }, { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" }, { "name": "id", "in": "path", "description": "File ID", "required": true, "schema": { "type": "string" }, "example": "57e8c9a2-5c30-4b2c-b9d0-11d6ac1f0144" } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "size": { "type": "integer" }, "ext": { "type": "string" }, "fullpath": { "type": "string" }, "meta": { "type": "object" }, "creator": { "type": "object" }, "created": { "type": "integer" } } } } }, "examples": { "File Info": { "value": { "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 } } } } } } } }, "x-auth-type": "user-token" }, "post": { "summary": "Update file info", "description": "Modify file information (name, title, description)\n\nCurrently only the `name` field can be modified (deprecated in favor of `meta.title` \u2014 coming soon).", "tags": [ "File Upload" ], "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" }, { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" }, { "name": "id", "in": "path", "description": "File ID", "required": true, "schema": { "type": "string" }, "example": "5e1598e7-4118-47ca-84da-0923c71b6977" } ], "requestBody": { "description": "File update details", "required": true, "content": { "application/x-www-form-urlencoded": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "File name" }, "meta.title": { "type": "string", "description": "File title" }, "meta.description": { "type": "string", "description": "File description" } } } } } }, "responses": { "200": { "description": "Successful update", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "object" } } }, "examples": { "Updated": { "value": { "data": { "id": "5e1598e7-4118-47ca-84da-0923c71b6977", "name": "test2.jpg", "size": 184259, "ext": "jpg", "meta": { "target": { "id": "350936", "type": "user" }, "category": "user_document" } } } } } } } } }, "x-auth-type": "user-token" }, "delete": { "summary": "Delete file", "description": "Delete a file", "tags": [ "File Upload" ], "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" }, { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" }, { "name": "id", "in": "path", "description": "File ID", "required": true, "schema": { "type": "string" }, "example": "57aa6ede-bf6c-4a88-81e1-6bcdac1f0144" } ], "responses": { "200": { "description": "Successful deletion", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "boolean" } } }, "examples": { "Deleted": { "value": { "data": true } } } } } } }, "x-auth-type": "user-token" } }, "/files/view/{id}": { "get": { "summary": "Download file", "description": "Download the file content. Parameters available for authenticated access.\n\n**Note:** The file view URL includes an `auth_code` and `time` parameter for secure, time-limited access.", "tags": [ "File Upload" ], "parameters": [ { "name": "X-ApiToken", "in": "header", "description": "API token", "required": true, "schema": { "type": "string" }, "example": "your_api_token" }, { "name": "X-AccountCode", "in": "header", "description": "Account code", "required": true, "schema": { "type": "string" }, "example": "vclinic" }, { "name": "id", "in": "path", "description": "File ID", "required": true, "schema": { "type": "string" }, "example": "57e8c9a2-5c30-4b2c-b9d0-11d6ac1f0144" }, { "name": "auth_code", "in": "query", "description": "Authentication code from file info response", "required": false, "schema": { "type": "string" }, "example": "01f72b633c40c73a87f1bc66694ee31" }, { "name": "time", "in": "query", "description": "Timestamp from file info response", "required": false, "schema": { "type": "string" }, "example": "1677099046" }, { "name": "size", "in": "query", "description": "Optional resized image dimensions (WxH format, e.g. 320x240)", "required": false, "schema": { "type": "string" }, "example": "320x240" } ], "responses": { "200": { "description": "File content", "content": { "application/octet-stream": { "schema": { "type": "string", "format": "binary" } }, "image/png": { "schema": { "type": "string", "format": "binary" } } } } }, "x-auth-type": "user-token" } } } }