Upload Asset to Segment

Uploads an asset (image, video, or other file) to a specific segment. Assets are stored in the project's reference material folder and can be retrieved later for display in editors or other contexts.

URL

(POST) /api/resources/assets/{segmentid}

PARAMETERS

Parameter	Type	Required	Description
segmentid (URL)	int	Mandatory	The unique segment identifier where the asset will be attached
scope (Query)	string	Mandatory	The scope parameter that defines the project context. Format: `pr{projectid}` (e.g., `pr7214`)

Request Body

The message body contains a JSON object with these properties:

Property	Type	Required	Description
filetoken	string	Mandatory	The file token obtained from the media upload API (`/api/media/upload`). Example: `"74fac397d6314cf4a2958f8318f3a9a4"`
locale	string	Optional	Language code to associate the asset with a specific language. If provided, the asset will be stored in a language-specific subfolder. Example: `"en"`, `"de"`, `"fr"`
relativePath	string	Optional	Relative path within the segment's asset folder to organize files. Example: `"/public/images"`, `"documents/pdfs"`. If not provided, the path can be included as part of the filename

ACCESS RIGHTS

The user must have access rights to the project's reference material. The system checks project-level permissions to ensure the user can upload assets to the specified scope.

EXAMPLE REQUEST

CODE

curl --location '{{URL}}/api/resources/assets/27665601?scope=pr7214' \
--header 'X-Auth-Token: {{AUTH_TOKEN}}' \
--header 'X-Auth-AccountId: {{ACCOUNT_ID}}' \
--header 'Content-Type: application/json' \
--data '{
    "filetoken": "{{FILE_TOKEN}}",
    "locale": "en"
}'

RESULTS

The response contains a JSON object with the uploaded asset details:

Property	Type	Description
projectId	int	The project identifier extracted from the scope
documentId	int	The document identifier that contains the segment
segmentId	int	The segment identifier where the asset was uploaded
locale	string?	The language code if the asset was associated with a specific language
relativePath	string	The relative path within the segment's asset folder. Empty string if the asset is stored at the root level (segment)
name	string	The stored filename
size	int	The file size in bytes
contentType	string	The MIME type of the uploaded file
createdDate	datetime	ISO 8601 timestamp when the asset was first created
modifiedDate	datetime	ISO 8601 timestamp when the asset was last modified
downloadUrl	string	Direct URL to download the asset. Includes locale, scope, filename, and version parameters

EXAMPLE RESPONSE

CODE

{
    "projectId": 7214,
    "documentId": 19641,
    "segmentId": 27665601,
    "locale": "en",
    "relativePath": "",
    "name": "pexels-gons3.jpg",
    "size": 2268156,
    "contentType": "image/jpeg",
    "createdDate": "2025-07-27T15:58:53.4687698Z",
    "modifiedDate": "2025-07-27T15:58:33.8999983Z",
    "downloadUrl": "http://{{URL}}/api/resources/assets/27665601?locale=en&scope=pr7214&filename=pexels-gons3.jpg&v=638892287138999983"
}

PREREQUISITES

Before uploading an asset, you must first upload the file content using the media upload API:

CODE

POST /api/media/upload?filename={filename}

This returns a filetoken that you then use in the asset upload request.

STORAGE STRUCTURE

Assets are stored in the project's reference material folder following this structure:

CODE

{reference material}/assets/{document ID}/{segment ID % 1000}/{segment ID}/

If a locale is specified:

CODE

{reference material}/assets/{document ID}/{segment ID % 1000}/{segment ID}/{locale}

NOTES

Assets are attached to segments, not to specific languages (unless explicitly specified via locale parameter)
Multiple assets can be uploaded to the same segment
Supported file types include images, videos, and other media files
File Path Handling: The system supports two ways to specify file paths:
- Use the relativePath parameter to specify the folder structure
- Include the path directly in the filename (e.g., "subfolder/image.jpg")
- If both are provided, relativePath takes precedence
Path separators are automatically normalized by the system