POST
https://spideriq.ai
/
api
/
v1
/
media
/
files
/
import-url
Import from URL
curl --request POST \
  --url https://spideriq.ai/api/v1/media/files/import-url \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "url": "<string>",
  "filename": "<string>",
  "folder": "<string>",
  "urls": [
    {}
  ]
}
'
{
  "success": true,
  "file_id": "products/20260111_product.jpg",
  "bucket": "client-cli-abc123",
  "key": "products/20260111_product.jpg",
  "url": "https://media.spideriq.ai/client-cli-abc123/products/20260111_product.jpg",
  "size": 45231,
  "content_type": "image/jpeg"
}
Import files directly from URLs without downloading them first. The server fetches the file(s) and stores them in your bucket. This is the easiest method for automation tools.
Best for automation: This endpoint is designed for Xano, N8N, Make, and similar automation platforms where you have image/file URLs and want to store them in SpiderMedia.

​
Two Modes

This endpoint supports both single file and batch imports:
ModePayloadResponse
Single{"url": "..."}FileUploadResponse
Batch{"urls": [...]}FileImportBatchResponse
The API automatically detects which mode based on the payload structure.

​
Single File Import

Use the url field to import a single file.

​
Request

​
url
string
required
URL of the file to import
​
filename
string
Custom filename (auto-detected from URL if not provided)
​
folder
string
Optional folder path within your bucket (e.g., “logos”, “ads/banners”)

​
Response

​
success
boolean
Whether the upload succeeded
​
url
string
Public URL to access the uploaded file
​
key
string
File key within the bucket
​
content_type
string
MIME type of the uploaded file
​
size
integer
File size in bytes

​
Example

curl -X POST "https://spideriq.ai/api/v1/media/files/import-url" \
  -H "Authorization: Bearer cli_abc123:sk_xxx:secret_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/images/product.jpg",
    "folder": "products"
  }'

{
  "success": true,
  "file_id": "products/20260111_product.jpg",
  "bucket": "client-cli-abc123",
  "key": "products/20260111_product.jpg",
  "url": "https://media.spideriq.ai/client-cli-abc123/products/20260111_product.jpg",
  "size": 45231,
  "content_type": "image/jpeg"
}

​
Batch Import

Use the urls array to import multiple files in a single request. Each file is processed independently - if one fails, others continue.

​
Request

​
urls
array
required
Array of file objects to import. Each object contains:
  • url (required): URL of the file to import
  • filename (optional): Custom filename for this specific file
​
folder
string
Folder path for ALL files in this batch (e.g., “ads”, “campaign-123”)

​
Response

​
success
boolean
true only if ALL files uploaded successfully
​
total
integer
Total number of files in the request
​
successful
integer
Number of files successfully uploaded
​
failed
integer
Number of files that failed
​
results
array
Array of per-file results, each containing:
  • success: Whether this file succeeded
  • url: Source URL that was imported
  • file_url: Public URL of uploaded file (if successful)
  • filename: Final filename used
  • size: File size in bytes
  • error: Error message (if failed)

​
Example

curl -X POST "https://spideriq.ai/api/v1/media/files/import-url" \
  -H "Authorization: Bearer cli_abc123:sk_xxx:secret_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": [
      {"url": "https://example.com/logo.png"},
      {"url": "https://example.com/banner.jpg", "filename": "main-banner.jpg"},
      {"url": "https://example.com/icon.svg"}
    ],
    "folder": "campaign-assets"
  }'

{
  "success": true,
  "total": 3,
  "successful": 3,
  "failed": 0,
  "results": [
    {
      "success": true,
      "url": "https://example.com/logo.png",
      "file_url": "https://media.spideriq.ai/client-cli-abc123/campaign-assets/20260111_logo.png",
      "filename": "logo.png",
      "size": 15234,
      "error": null
    },
    {
      "success": true,
      "url": "https://example.com/banner.jpg",
      "file_url": "https://media.spideriq.ai/client-cli-abc123/campaign-assets/20260111_main-banner.jpg",
      "filename": "main-banner.jpg",
      "size": 89012,
      "error": null
    },
    {
      "success": true,
      "url": "https://example.com/icon.svg",
      "file_url": "https://media.spideriq.ai/client-cli-abc123/campaign-assets/20260111_icon.svg",
      "filename": "icon.svg",
      "size": 2048,
      "error": null
    }
  ]
}

​
Use Cases

​
Xano: Import Product Images

When scraping product data, import all images to your media storage: 
// After SpiderSite returns product data with image URLs
{
  "urls": product_images.map(img => ({ "url": img.src })),
  "folder": "products/" + product_id
}

​
N8N: Campaign Asset Upload

Import multiple ad creatives from a Google Drive folder or external source: 
// Batch import campaign assets
{
  "urls": [
    {"url": drive_url_1, "filename": "ad-variant-a.jpg"},
    {"url": drive_url_2, "filename": "ad-variant-b.jpg"},
    {"url": drive_url_3, "filename": "ad-variant-c.jpg"}
  ],
  "folder": "campaigns/q1-2026"
}

​
Dynamic Filename from Variable

// Single file with dynamic naming
{
  "url": scraped_logo_url,
  "filename": company_name.toLowerCase().replace(/\s+/g, '-') + "-logo.png",
  "folder": "logos"
}

​
Error Handling

Single mode vs Batch mode errors:
  • Single file: Returns HTTP 400 error if import fails
  • Batch: Always returns HTTP 200, with per-file success/error in results

​
Common Errors

ErrorCauseSolution
404 NOT FOUNDSource URL doesn’t existVerify the URL is accessible
Timeout downloading fileSource server too slowTry again or use a different URL
Downloaded file is emptyURL returned no contentCheck if URL requires authentication
Must provide either 'url' or 'urls'Neither field providedInclude url or urls in payload