fetch, so it runs in a Next.js route handler, an Express or Hono server, or a queue worker. Keep IMPORTLY_API_KEY on the server: create it on the API key page (it’s shown once).
1. Connect your bucket once
Create a bucket and an upload-only key first (the steps for S3, R2, B2 and Spaces are in Deliver to your bucket). Then save the settings, either on the dashboard’s S3 Storage page or with one API call from a setup script:scripts/connect-bucket.ts
importly-test-<timestamp>.txt to the root of the bucket, and nothing is saved if that upload fails. To check credentials without saving them, send the same body to POST /s3-storage/test.
This is a one-time step per Importly account, not per import. All your app’s imports go to this bucket unless a request names another one with storageBucket.
2. Start an import into the bucket
When a user adds a link, start the import withstore: true and a storagePath that keeps your bucket organised. Save the jobId on your own record so the webhook can find it:
lib/importly.ts
storageFilename (no extension; Importly adds it). See Downloads for qualities, audio formats and transcripts in the same request.
3. Record where the file went
Importly sends onePOST to webhookUrl when the job finishes or fails. This handler takes only the jobId from it and reads the result from the API with your key, so a forged request can’t put data into your app. Every delivery is also signed: to reject forged requests before calling the API, check the Importly-Signature header as shown in Verify signatures. It’s a Next.js route handler here; in another framework, the body is the same.
app/api/webhooks/importly/route.ts
s3Storage has the object’s bucket, key and full url. Store the key rather than the URL: buckets are private by default, so you’ll usually serve the file through presigned URLs or a CDN in front of the bucket.
Each job gets one webhook delivery and no retries, so also check imports that have been pending for a few minutes with GET /import/status. The webhook URL must be public https://; in local development, poll the status endpoint instead. See Webhooks.
When the copy fails
A failed copy never fails the import. The job completes, you’re charged for the download as usual, and the result hass3StorageError instead of s3Storage. The usual reasons:
- No bucket saved:
store: trueon an account with no storage set up (or with storage turned off) gives ans3StorageErrorthat starts withNo S3 storage is set up for this account. Run step 1. - Credentials or permissions changed: a rotated key, or a bucket policy that no longer allows
s3:PutObject. Save the new key with step 1. - A storage class the region doesn’t support: leave
storageClassout, or pick one the bucket’s region offers.
Downloads cost $0.002 per MB, with a $0.01 minimum per import: a 10-minute 720p video is about $0.15. Copying it to your bucket costs nothing extra. Try it free, no card required. See Pricing & credits.