Ingest from URI

POST 
/api/v1/assets/new/content/original/external

Ask FileSpin to download a file from an HTTPS URL or your own S3 bucket and create an asset from it. FileSpin checks the source first and returns the new asset's ID; the download runs in the background.

Different host for uploads

This endpoint is served on https://upload.filespin.io — not the standard https://app.filespin.io host used by the rest of the API. Make sure your client targets the upload host for this request.

What can be imported

• HTTP(S) URL: a public download link. A link that needs a sign-in (a course site, a private Google Drive, SharePoint or Dropbox file) can't be downloaded: FileSpin refuses it rather than saving the sign-in page as your file. URLs that point at private or internal network addresses are refused, including after a redirect. Downloads from external websites are rate-limited.
• S3 URI: s3://bucket/key in a bucket you own that grants FileSpin read access by bucket policy (see Asset Storage for the policy). FileSpin's own storage buckets are refused.

Request fields

Key	Required	Description
key	yes	The HTTPS URL or S3 URI
name	no	File name for the asset. Omitted, FileSpin uses the name the server gives (Content-Disposition), then the URL's last path segment, then a name made from the content type. For an S3 URI it defaults to the key's file name
data	no	Custom metadata, as on upload. Put data_schema_id inside it to choose the schema
size	no	File size in bytes, if you know it. Checked against your plan's file size limit before anything is created
md5_checksum	no	MD5 of the file

Example request JSON payload

Request to pull a file from an HTTPS URL (the name is read from the link)

{
  "key": "https://example.com/files/brochure.pdf"
}

Request to pull a file from your S3 bucket

{
  "name": "test.jpg",
  "key": "s3://my-bucket/test.jpg"
}

HTTP RESPONSE

200 when the import is queued.

Key	Value	Description
id	string	Asset ID, 32 character alphanumeric UUID
name	string	The file name the asset gets
status	string	"QUEUED"
message	string	Additional details about status

{
  "id": "ceace459cd2a4d2c904e38e9ab352ebb",
  "name": "brochure.pdf",
  "status": "QUEUED",
  "message": "Queued for import"
}

Follow the download with GET /api/v1/assets/new/{asset_id}/status: queued, processing, ready (the asset exists) or failed with a reason (one of the codes below, or download_failed).

Errors

A refused source returns "status": "ERROR", a message you can show, and a code. Nothing is created.

HTTP	code	Meaning
400	source_requires_login	The link answered 401/403: it needs a sign-in
400	source_returned_web_page	The link returned an HTML page where a file was expected, usually a sign-in or preview page. Name the file *.html to import a web page on purpose
400	source_unreachable	The host could not be found or reached, or answered with another error
400	invalid_source_url	key is not an http(s):// or s3:// URI
400	size_exceeded	The file is larger than your plan allows
403	source_not_allowed	A private or internal address, or an S3 bucket you can't import from

Request

Responses

200

Successful operation

400

The source was refused (see code), or the request is invalid

401

Unauthorized - Invalid or missing authentication

403

Forbidden - Insufficient permissions, or source_not_allowed

500

Internal server error