Create file record

Create a file record after uploading. This endpoint should be called AFTER uploading the file using the presigned URL from /files/upload-url. It creates the database record and updates storage usage tracking.

POST /files

cURL

cURL

# Step 1: Get presigned upload URL
curl -X POST https://app.mavera.io/api/v1/files/upload-url \
  -H "Authorization: Bearer mvra_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "file_name": "document.pdf",
    "file_type": "application/pdf",
    "file_size": 1048576,
    "workspace_id": "ws_abc123"
  }'

# Step 2: Upload file to the presigned URL (use upload_url from step 1)
curl -X PUT "PRESIGNED_URL_FROM_STEP_1" \
  -H "Content-Type: application/pdf" \
  --data-binary @document.pdf

# Step 3: Create the file record (use public_url from step 1)
curl -X POST https://app.mavera.io/api/v1/files \
  -H "Authorization: Bearer mvra_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "document.pdf",
    "type": "application/pdf",
    "url": "PUBLIC_URL_FROM_STEP_1",
    "workspace_id": "ws_abc123",
    "file_size": 1048576
  }'

201

{
  "id": "<string>",
  "object": "file",
  "name": "<string>",
  "url": "<string>",
  "type": "<string>",
  "size": 123,
  "source": "upload",
  "workspace_id": "<string>",
  "folder_id": "<string>",
  "folder": {
    "id": "<string>",
    "name": "<string>"
  },
  "thumbnail_url": "<string>",
  "metadata": {},
  "is_favorite": true,
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

Authorizations

Authorization · string · header · required

API key prefixed with mvra_live_. Create keys at Settings > Developer > API Keys.

Body

application/json

name · string · required

File name

type · string · required

MIME type of the file

url · string<uri> · required

Public URL where the file was uploaded (from upload-url response)

workspace_id · string · required

Workspace to store the file in

file_size · integer · required

File size in bytes

Required range: x >= 1

folder_id · string

Optional folder ID to organize the file

metadata · object

Optional custom metadata

Response

201

application/json

File created successfully

A file/asset stored in Mavera

id · string

Unique file identifier

object · enum<string>

Available options: file

name · string

File name

url · string<uri>

Direct URL to access the file

type · string

MIME type of the file (e.g., 'image/png', 'application/pdf')

size · integer | null

File size in bytes

source · enum<string>

Source of the file upload

Available options: upload, google_drive, dropbox, dropbox_chooser, onedrive, onedrive_picker, url

workspace_id · string

Workspace ID

folder_id · string | null

Folder ID if file is in a folder

folder · object

Folder details if file is in a folder

Show child attributes

thumbnail_url · string<uri> | null

Thumbnail URL for images/videos

metadata · object

Custom metadata attached to the file

is_favorite · boolean

Whether the file is in your favorites

created_at · string<date-time>

updated_at · string<date-time>