Skip to main content
NocoDB allows you to upload files and manage attachments through the API. Attachments can be uploaded via direct file upload or by providing a URL.

​
Upload Files

Upload one or more files to NocoDB storage.
POST /api/v1/db/storage/upload
curl -X POST "https://app.nocodb.com/api/v1/db/storage/upload" \
  -H "xc-auth: YOUR_API_TOKEN" \
  -F "file=@/path/to/image.jpg" \
  -F "file=@/path/to/document.pdf"

​
Using curl with multiple files

curl -X POST "https://app.nocodb.com/api/v1/db/storage/upload" \
  -H "xc-auth: YOUR_API_TOKEN" \
  -F "files[]=@image1.jpg" \
  -F "files[]=@image2.png" \
  -F "files[]=@document.pdf"
​
path
string
Optional path for organizing uploaded files
​
scope
string
Attachment scope: Determines access permissions
  • Not provided or empty: Private attachment
  • public: Publicly accessible attachment
​
array
array
Array of uploaded attachment objects
​
title
string
The filename of the uploaded file
​
mimetype
string
MIME type of the file (e.g., “image/jpeg”, “application/pdf”)
​
size
number
File size in bytes
​
path
string
Relative path to the uploaded file
​
signedPath
string
Signed path for temporary direct access to the file (local storage)
​
url
string
Full URL to the uploaded file (external storage like S3)
​
signedUrl
string
Signed URL for temporary direct access to the file (external storage)

​
Response Example

[
  {
    "title": "image.jpg",
    "mimetype": "image/jpeg",
    "size": 146143,
    "path": "download/noco/pm0umqsip16i1u5/m8yn03dncqal6ri/iDL5ednaHz2j2Sa3Cl.jpg",
    "signedPath": "dltemp/lNoLbqB62Jdo5Rmp/1709308800000/noco/pm0umqsip16i1u5/m8yn03dncqal6ri/iDL5ednaHz2j2Sa3Cl.jpg"
  },
  {
    "title": "document.pdf",
    "mimetype": "application/pdf",
    "size": 524288,
    "path": "download/noco/pm0umqsip16i1u5/m8yn03dncqal6ri/xyz789document.pdf",
    "signedPath": "dltemp/abc123/1709308800000/noco/pm0umqsip16i1u5/m8yn03dncqal6ri/xyz789document.pdf"
  }
]

​
Upload by URL

Upload files by providing their URLs instead of uploading files directly.
POST /api/v1/db/storage/upload-by-url
curl -X POST "https://app.nocodb.com/api/v1/db/storage/upload-by-url" \
  -H "xc-auth: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '[
    {
      "url": "https://example.com/image.jpg",
      "fileName": "my-image.jpg"
    },
    {
      "url": "https://example.com/document.pdf"
    }
  ]'
​
path
string
Optional path for organizing uploaded files
​
scope
string
Attachment scope for access permissions
​
array
array
required
Array of attachment objects to upload
​
url
string
required
URL of the file to download and upload
​
fileName
string
Optional custom filename for the uploaded file
​
mimetype
string
MIME type of the file

​
Response Example

[
  {
    "title": "my-image.jpg",
    "mimetype": "image/jpeg",
    "size": 32903,
    "url": "https://some-s3-server.com/nc/uploads/2023/10/16/some-key/3niqHLngUKiU2Hupe8.jpeg",
    "signedUrl": "https://some-s3-server.com/nc/uploads/2023/10/16/signed-url-misc-info"
  }
]

​
Download Attachment

Download an attachment from a specific table record.
GET /api/v2/downloadAttachment/{modelId}/{columnId}/{rowId}
curl -X GET "https://app.nocodb.com/api/v2/downloadAttachment/{modelId}/{columnId}/{rowId}?urlOrPath=download%2Fnoco%2Ffile.jpg" \
  -H "xc-auth: YOUR_API_TOKEN"
​
modelId
string
required
Unique Model/Table ID
​
columnId
string
required
Unique Column ID of the attachment field
​
rowId
string
required
Unique Row ID
​
urlOrPath
string
required
URL or path of the specific attachment file to download

​
File Access

NocoDB provides different endpoints for accessing uploaded files:

​
Direct Download

GET /download/{filename}
Downloads files from the local storage. The filename parameter should include the full path.

​
Signed Path Access

GET /dltemp/{param}
Accesses files using signed temporary URLs. This provides time-limited access to files.

​
Working with Attachment Fields

When inserting or updating records with attachment fields, use the response from the upload endpoints: 
# 1. Upload file(s)
curl -X POST "https://app.nocodb.com/api/v1/db/storage/upload" \
  -H "xc-auth: YOUR_API_TOKEN" \
  -F "file=@image.jpg"

# Response:
# [{
#   "title": "image.jpg",
#   "mimetype": "image/jpeg",
#   "size": 146143,
#   "path": "download/noco/..../image.jpg"
# }]

# 2. Create/update record with attachment
curl -X POST "https://app.nocodb.com/api/v1/db/data/noco/mybase/mytable" \
  -H "xc-auth: YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "Title": "My Record",
    "Attachment": [
      {
        "title": "image.jpg",
        "mimetype": "image/jpeg",
        "size": 146143,
        "path": "download/noco/..../image.jpg"
      }
    ]
  }'

​
Supported File Types

NocoDB supports uploading any file type. Common types include:
  • Images: JPG, PNG, GIF, SVG, WebP
  • Documents: PDF, DOC, DOCX, XLS, XLSX, PPT, PPTX
  • Archives: ZIP, RAR, 7Z
  • Videos: MP4, AVI, MOV, WebM
  • Audio: MP3, WAV, OGG
  • Code: TXT, JSON, XML, CSV

​
File Size Limits

File size limits depend on your NocoDB configuration:
  • Default limit: 20MB per file
  • Can be configured via NC_ATTACHMENT_FIELD_SIZE environment variable
  • Cloud instances may have different limits

​
Storage Options

NocoDB supports multiple storage backends:
  • Local Storage: Default option, stores files on the server filesystem
  • S3: Amazon S3 or S3-compatible storage
  • MinIO: Self-hosted S3-compatible storage
  • Google Cloud Storage: GCS integration
  • Azure Blob Storage: Azure storage integration
The response format varies slightly depending on the storage backend:
  • Local storage returns path and signedPath
  • External storage returns url and signedUrl