Skip to main content

Files API Reference

Upload, download, and manage file attachments via the API.

Endpoints Overview​

MethodEndpointDescription
POST/v1/tags/{id}/filesUpload file to tag
GET/v1/tags/{id}/filesList files in tag
GET/v1/files/{file_id}Get file metadata
GET/v1/files/{file_id}/downloadDownload file
DELETE/v1/files/{file_id}Delete file

Upload File​

Upload a file to a tag.

Request​

POST /v1/tags/{id}/files
Content-Type: multipart/form-data

Form Parameters​

ParameterTypeRequiredDescription
filefileYesFile to upload
namestringNoCustom display name
descriptionstringNoFile description

Example​

curl -X POST https://api.tagd-ai.com/v1/tags/abc123/files \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@document.pdf" \
  -F "name=User Manual" \
  -F "description=Product user manual v2.1"

Response​

{
  "success": true,
  "data": {
    "id": "file_xyz789",
    "name": "User Manual",
    "original_name": "document.pdf",
    "description": "Product user manual v2.1",
    "mime_type": "application/pdf",
    "size": 2457600,
    "url": "https://files.tagd-ai.com/file_xyz789",
    "created_at": "2024-01-15T10:30:00Z"
  }
}

Upload via URL​

Upload a file from a URL.

Request​

POST /v1/tags/{id}/files/from-url
Content-Type: application/json

Body Parameters​

ParameterTypeRequiredDescription
urlstringYesURL to fetch file from
namestringNoCustom display name

Example​

curl -X POST https://api.tagd-ai.com/v1/tags/abc123/files/from-url \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/document.pdf",
    "name": "External Document"
  }'

List Files​

Get all files attached to a tag.

Request​

GET /v1/tags/{id}/files

Query Parameters​

ParameterTypeDescription
limitintegerItems per page (max 100)
offsetintegerSkip items

Example​

curl https://api.tagd-ai.com/v1/tags/abc123/files \
  -H "Authorization: Bearer YOUR_API_KEY"

Response​

{
  "success": true,
  "data": [
    {
      "id": "file_xyz789",
      "name": "User Manual",
      "original_name": "document.pdf",
      "mime_type": "application/pdf",
      "size": 2457600,
      "created_at": "2024-01-15T10:30:00Z"
    },
    {
      "id": "file_abc456",
      "name": "Product Photo",
      "original_name": "photo.jpg",
      "mime_type": "image/jpeg",
      "size": 524288,
      "created_at": "2024-01-15T10:35:00Z"
    }
  ],
  "pagination": {
    "total": 2,
    "limit": 20,
    "offset": 0,
    "has_more": false
  }
}

Get File Metadata​

Get details about a specific file.

Request​

GET /v1/files/{file_id}

Example​

curl https://api.tagd-ai.com/v1/files/file_xyz789 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response​

{
  "success": true,
  "data": {
    "id": "file_xyz789",
    "tag_id": "abc123",
    "name": "User Manual",
    "original_name": "document.pdf",
    "description": "Product user manual v2.1",
    "mime_type": "application/pdf",
    "size": 2457600,
    "url": "https://files.tagd-ai.com/file_xyz789",
    "download_count": 42,
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z"
  }
}

Download File​

Download the file content.

Request​

GET /v1/files/{file_id}/download

Example​

curl https://api.tagd-ai.com/v1/files/file_xyz789/download \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -o downloaded_file.pdf

Response​

Binary file content with appropriate Content-Type header.

Update File Metadata​

Update file name or description.

Request​

PATCH /v1/files/{file_id}
Content-Type: application/json

Body Parameters​

ParameterTypeDescription
namestringNew display name
descriptionstringNew description

Example​

curl -X PATCH https://api.tagd-ai.com/v1/files/file_xyz789 \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Manual Name",
    "description": "Updated description"
  }'

Delete File​

Permanently delete a file.

Request​

DELETE /v1/files/{file_id}

Example​

curl -X DELETE https://api.tagd-ai.com/v1/files/file_xyz789 \
  -H "Authorization: Bearer YOUR_API_KEY"

Response​

{
  "success": true,
  "message": "File deleted successfully"
}

File Size Limits​

PlanMax Per FileTotal Storage
Pro100 MB1 GB
Enterprise500 MB10 GB

Supported File Types​

Documents​

  • PDF (.pdf)
  • Word (.doc, .docx)
  • Excel (.xls, .xlsx)
  • PowerPoint (.ppt, .pptx)
  • Text (.txt, .rtf)

Images​

  • JPEG (.jpg, .jpeg)
  • PNG (.png)
  • GIF (.gif)
  • WebP (.webp)
  • SVG (.svg)

Archives​

  • ZIP (.zip)
  • RAR (.rar)

Data​

  • CSV (.csv)
  • JSON (.json)
  • XML (.xml)

Blocked Types​

  • Executables (.exe, .app, .sh)
  • Scripts (.js, .py, .rb) unless in archive

Image-Specific Endpoints​

Get Image Thumbnail​

GET /v1/files/{file_id}/thumbnail?width=200&height=200

Image Transformations​

GET /v1/files/{file_id}/download?width=800&quality=80&format=webp

Error Responses​

400 Bad Request​

{
  "success": false,
  "error": {
    "code": "file_too_large",
    "message": "File exceeds maximum size of 100MB"
  }
}

415 Unsupported Media Type​

{
  "success": false,
  "error": {
    "code": "unsupported_file_type",
    "message": "File type .exe is not allowed"
  }
}

507 Insufficient Storage​

{
  "success": false,
  "error": {
    "code": "storage_limit_exceeded",
    "message": "Account storage limit exceeded"
  }
}

Next Steps​