/api/v1/media/import

Requires the media:write scope.

Bulk-import every image in a Google Drive folder into your library. Returns an import id to poll — the work runs in the background.

Body fields

The shape is strict. Any field not in this table is 422 validation_failed rather than a silently ignored key — including url, storage_path and preview_url.

Name	Type	Required	Notes
`provider`	`string`	yes	Currently 'google_drive'.
`folder_id`	`string`	yes	The Drive folder to import from — a folder id, NOT a URL. We resolve it through the Drive API and download only from Google.
`recursive`	`boolean`	no	Reserved; v1 imports the folder itself, not sub-folders. Default false.

Request

curl -s -X POST "https://omniscape.io/api/v1/media/import" \
  -H "Authorization: Bearer $OMNISCAPE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: import-campaign-1" \
  -d '{"provider":"google_drive","folder_id":"1AbC..."}'

Response

HTTP/1.1 202 Accepted

{
  "object": "media_import",
  "id": "imp_9f2a1c3b7e40",
  "status": "pending",
  "provider": "google_drive",
  "folder_id": "1AbC...",
  "counts": { "discovered": 0, "imported": 0, "skipped": 0, "failed": 0 },
  "created_at": "2026-08-30T21:05:00.000Z"
}

Notes

You give a folder id, never a URL — the API never fetches a location you name, exactly like the rest of it. Each file is byte-sniffed and stored under your workspace, the same as a direct upload.
Only images are imported (JPEG, PNG, WebP, GIF). Re-importing the same folder skips files already imported, so it is safe to run again.
Bounded: up to 500 files per import, and it stops when your storage cap is reached and reports a partial. A Google connection is required first (409 integration_not_connected otherwise).
Send an Idempotency-Key to make a retried request return the same import instead of starting a second one.

Codes this call can return are on Error handling. If something is behaving unexpectedly, Troubleshooting is organised by symptom.