Create File

API Reference

Create File

Request

Registers a new file from a publicly accessible URL, optionally tagging it. The file is fetched, checked against the supported formats and the size limit, and stored.

Authentication

Requires a valid API key in the X-API-KEY header.

Request Body

{
  "url": "https://example.com/docs/product-datasheet.pdf",
  "tags": ["datasheets", "catalog", "summer-2024"]
}

URL Field (Required)

The URL must meet the following requirements:

Valid URL formats:

Must be a valid HTTP or HTTPS URL
Must be absolute (e.g., https://example.com/manual.pdf)
Relative URLs are NOT supported (e.g., /docs/manual.pdf)
The filename is taken from the URL path and becomes the file's reference

Examples of valid URLs:

https://example.com/product-datasheet.pdf
https://cdn.example.com/docs/2024/manual.docx
http://assets.example.com/exports/catalog_123.csv

Examples of invalid URLs:

/docs/manual.pdf                       (relative URL)
example.com/manual.pdf                 (missing protocol)
ftp://server.com/manual.pdf            (FTP not supported)
https://example.com/installer.exe      (extension not accepted)
https://example.com/datasheet          (no extension to derive the file type from)

URL validation rules:

Maximum length: 2048 characters
The URL must be publicly accessible (no authentication supported)
The host must resolve to a public address. URLs pointing at loopback, private ranges or the cloud metadata endpoint are rejected
The URL is probed with a HEAD request; anything other than a 2xx is rejected
An address that never answers, or that refuses the connection, is rejected the same way — as an address the caller has to correct, not as a technical error

Tags Field (Optional)

Optional array of strings to categorize and organize your files.

Rules:

Each tag cannot be empty or contain only whitespace
Tags are case-sensitive
No tag may contain a comma. A comma is the separator the set is stored with, so a tag carrying one would be read back as two; it is rejected rather than accepted and mangled
There is no explicit limit on the number of tags, but the whole comma-separated list must fit in 64 KB of storage

Supported File Formats

The file type is taken from the URL's file extension and must be one of:

Category	Extensions
Documents	`pdf`, `doc`, `docx`, `txt`, `rtf`, `odt`
Spreadsheets	`xls`, `xlsx`, `csv`, `ods`
Presentations	`ppt`, `pptx`, `odp`
Archives	`zip`, `rar`, `7z`, `tar`, `gz`, `tgz`
Video and audio	`mp4`, `mov`, `webm`, `m4v`, `mpeg`, `mpg`, `avi`, `mp3`, `wav`
Images	`jpg`, `jpeg`, `png`, `gif`, `bmp`, `tif`, `tiff`, `psd`, `webp`, `avif`, `heic`
Markup and data	`svg`, `html`, `htm`, `xml`, `json`
Print production	`ai`, `eps`, `indd`, `idml`, `idms`
CAD, BIM and 3D	`dwg`, `dxf`, `step`, `stp`, `iges`, `igs`, `stl`, `sat`, `obj`, `mtl`, `fbx`, `3ds`, `max`, `skp`, `glb`, `gltf`, `usdz`, `dae`, `3dm`, `x3d`, `ifc`, `rfa`, `rvt`, `iam`, `ipt`, `idw`
Photometry and product data	`ldt`, `ies`, `uld`, `gll`, `gdtf`, `bc3`, `bom`, `sup`
Fonts	`otf`, `ttf`, `woff`, `woff2`

The extension is matched case-insensitively and decides which format the file is filed as. The Content-Type the URL serves is not validated, unlike POST /images: several of the accepted formats have no registered media type and are commonly served as application/octet-stream, so a media-type allow-list would reject valid uploads without excluding anything.

File Size Limit

Maximum file size: 250 MB (262,144,000 bytes)
The transfer is cut off as soon as the limit is exceeded, so an oversized file is never stored

Response

Success Response (201 Created)

Returns the reference (filename) of the created file, wrapped in the house entity envelope. The reference is the public, tenant-unique key; the numeric id is internal only and is not exposed:

{
  "value": {
    "reference": "product-datasheet.pdf"
  },
  "@readLink": "https://api2.saleslayer.com/dam/files(product-datasheet.pdf)",
  "@editLink": "https://api2.saleslayer.com/dam/files(product-datasheet.pdf)"
}

Error Responses

400 Bad Request

Validation failures are returned in the shared envelope. Service-level messages carry no field context, so they are grouped under a generic error key:

{
  "validationFailures": {
    "error": ["URL is required"]
  }
}

The messages you can receive, verbatim:

Cause	Message
Missing or empty URL	`URL is required`
URL over 2048 characters	`URL exceeds maximum length of 2048 characters`
Not an absolute URL	`URL is not valid`
Scheme other than HTTP/HTTPS	`URL must use HTTP or HTTPS protocol`
No extension in the URL path	`Could not determine file type from URL. Please ensure the URL contains a filename with an extension.`
Unsupported extension	`File extension 'exe' is not allowed. Allowed extensions: 3dm, 3ds, 7z, ai, avi, ...` — the whole accepted set, alphabetically
Host is not publicly routable	`URL host 'localhost' is not allowed.`
URL not reachable (non-2xx `HEAD`)	`URL is not accessible. HTTP status: 404 Not Found`
URL did not answer in time	`URL is not accessible. The address did not respond in time.`
Connection refused, DNS or TLS failure	`URL is not accessible. The address 'cdn.example.com' could not be reached.`
Empty file	`The uploaded file is empty`
Stored copy missing	`The uploaded file could not be found in storage.`
File too large	`File size (300.00 MB) exceeds maximum allowed size of 250 MB`
Content is a different file type	`The address serves a PNG image, but the file name 'product-datasheet.pdf' announces a 'pdf' file.`
Content matches no known file type	`The address does not serve a 'pdf' file: its content matches no known file type.`
Empty or whitespace-only tag	`Tags cannot contain empty values`
Tag containing a comma	`Tags cannot contain commas`

401 Unauthorized

Missing or invalid API key in the X-API-KEY header. Emitted by the API gateway:

{
  "message": "Unauthorized",
  "request_id": "d8aafa5b8f3e400b60bea0123dd33317"
}

403 Forbidden

The API key does not have write permissions for this operation. Same body shape as the 401.

409 Conflict

Two distinct causes, both using the conflict envelope:

A file with the same filename (reference) already exists for this tenant:

{
  "error": "A file with the filename 'product-datasheet.pdf' already exists"
}

The tenant has reached its file-library quota:

{
  "error": "File library limit reached. Current: 500, Maximum: 500"
}

Deleted files do not count towards the quota. Delete unused files to free capacity, or contact Sales Layer to raise the limit. The file and image libraries have separate quotas, so files never consume image capacity or vice versa.

Complete Example

Request:

POST /files HTTP/1.1
Host: api2.saleslayer.com
X-API-KEY: your-api-key-here
Content-Type: application/json
            
{
  "url": "https://cdn.example.com/docs/2024/product-datasheet.pdf",
  "tags": ["datasheets", "catalog"]
}

Success Response:

HTTP/1.1 201 Created
Content-Type: application/json
Location: https://api2.saleslayer.com/dam/files(product-datasheet.pdf)
            
{
  "value": {
    "reference": "product-datasheet.pdf"
  }
}

Result:

{
  "value": {
    "reference": "product-datasheet.pdf",
    "status": "Ok",
    "fileType": "pdf",
    "sizeInBytes": 524288,
    "numLinks": 0,
    "tags": ["datasheets", "catalog"],
    "url": "https://cdn.example.com/CMP2009/files/product-datasheet.pdf",
    "createdOn": "2024-04-02T10:30:00",
    "modifiedOn": "2024-04-02T10:30:00"
  }
}

Headers

X-API-KEYstringrequired

Tenant's API key (required)

Body

Request containing the file URL and optional tags

urlstring or null

Publicly accessible HTTP or HTTPS URL of the file to import. Required. Must be absolute and end in a supported extension (pdf, doc, docx, txt, xls, xlsx, csv, rtf, ppt, pptx, zip, rar, tar, mpeg, mpg, avi, mov, tif, tiff, ai, eps, psd, x3d, sup, ldt, ies, dwg, obj, webp); the file's reference is the filename taken from the URL path. Maximum 2048 characters.

tagsArray of strings or null

Optional tags to associate with the file, e.g. ["datasheets", "catalog", "2024"]. Tags are case-sensitive and cannot be empty or whitespace. Avoid commas inside a tag — tags are stored as a comma-separated string and would be read back split.

POST

/files

curl -i -X POST \
  https://api2.saleslayer.com/dam/files \
  -H 'Content-Type: application/json' \
  -H 'X-API-KEY: string' \
  -d '{
    "url": "string",
    "tags": [
      "string"
    ]
  }'

Responses

Created

Bodyapplication/json

valueobject(CreateFileResponse)

The reference of a newly created file. Retrieve the full file with GET /files({reference}). Unlike an image, a file is usable as soon as it is created — nothing processes it afterwards — so it starts, and stays, in status Ok.

@readLinkstring or null

Canonical URL of the created file, the same resource the Location header names. Present only when hypermedia enrichment is enabled.

@editLinkstring or null

URL to modify the created file, identical to @readLink. Present only when hypermedia enrichment is enabled.

Response

{
  "value": {
    "reference": "string"
  },
  "@readLink": "string",
  "@editLink": "string"
}

Create File

Request

Authentication

Request Body

URL Field (Required)

Tags Field (Optional)

Supported File Formats

File Size Limit

Response

Success Response (201 Created)

Error Responses

400 Bad Request

401 Unauthorized

403 Forbidden

409 Conflict

Complete Example

Headers

Responses

Was this helpful?