HTTP MFT Rest API
The HTTP MFT Rest API lets applications perform file transfer operations - listing, upload, download, and deletion - as well as metadata management over HTTP/HTTPS.
Users can authenticate and access Virtual File Systems according to the Connection Contract configuration and can operate on files and Virtual Paths according to ACLs.
As a result, file operations executed via this API may trigger contracts and downstream processing configured on the platform.
Pre-requisites
HTTP/S server is configured: an HTTP or HTTPS server must exist and be reachable. Details here: Server Connections and Server Connection: HTTP or Server Connection: HTTPS
Actor and User exist: an Actor is configured (typically a Partner) and a User is defined under that Actor and will authenticate to this API
In the Actor, a VFS is available
HTTP/S Connection contract binding the Actor/User to the target VFS/Virtual Path is configured; details here: Create a Connection Contract
Base URL
API calls must be sent to an HTTP/S server active on any STENG Peer that belongs to the target STENG Cluster.
host and port depend on your deployment setup:
If the HTTP/S server is enabled on a specific STENG Peer, use that peer’s host and port.
If a load balancer is configured in front of the cluster, use the balancer’s host and port; requests will be routed automatically to the active peers.
the protocol (
http
orhttps
) must match the configuration of the HTTP/S server on that STENG Peer.
The following Base URLs define the entry point for all API calls, depending on your deployment setup.
Base URL (STENG peer): https://<peer-host>:/2.0/
Base URL (load balancer): https://<lb-host>:/2.0/
Notes:
the /2.0/ path is constant across peers; the protocol must match the HTTP/S server config
from there, each endpoint shows only the path (relative to the Base URL).
AUTHENTICATION
Login
Endpoint:
/login/basic
Method:
POST
Content-Type:
application/x-www-form-urlencoded
Description
Authenticates a user and starts a new session on the configured HTTP / HTTPS server.
The server returns two session cookies (sp-http-usr
and sp-http-ses
) that identify the user in subsequent API calls.
Request parameters
username
Username
String
yes
password
The user password
String
yes
Responses
200
Authentication successful
No response body. Session cookie returned:
Set-Cookie: sp-http-usr=; Path=/; HttpOnly
Set-Cookie: sp-http-ses=; Path=/; HttpOnly
Save both cookies and include them in every subsequent request (Cookie: header)
401
Invalide username and password
{
"result":"failed",
"message":"Invalid username or password",
"errorType":"authentication"
}
Returned when credentials do not match
404
Missing Parameters
{
"result":"failed",
"message":"No username or password",
"errorType":"request_syntax"
}
Returned when one or both parameters are missing
Cookies returned from the call can be placed in a file (-c filename), which is then used in subsequent calls via curl, as in the example below:
curl -v "https://myHostName:21080/2.0/login/basic"
-H 'Content-Type: application/x-www-form-urlencoded; charset=UTF-8'
-d 'username=jdoe&password=secret'
-c cookies.txt
This command authenticates the user jdoe
and stores the session cookiies in the cookies.txt
file.
FILES
Upload file
Endpoint:
/files/<path>/<file>
Method:
PUT
Authentication: session cookies (
sp-http-usr
,sp-http-ses
) fromPOST /login/basic
Content-Type:
multipart/form-data
Description
Uploads a file to the specified <path>
.
Request parameters
Path parameters
path
Destination folder
string
yes
URL-encode special characters
file
Target filename to create in the destination folder
string
yes
URL-encode special characters
Multipart form fields
file
The content of the file to upload.
binary
yes
Use @<local-filename>
with curl
Responses
201
File uploaded successfully
{
"result":"ok",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"Upload successful",
"fileset":"251",
}
id : long value that represents the file Timestamp: UTC representation of the response creation using ISO-8601
400
Missing filename
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"No filename specified",
"errorType":"request_syntax"
}
Example if specified only path of folder. Timestamp: UTC representation of the response creation using ISO-8601
400
Missing parameters or syntax error
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"Missing parameters or syntax error",
"errorType":"request_syntax"
}
Example if metadata has syntax error or content-type header is missing. Timestamp: UTC representation of the response creation using ISO-8601
401
Connection contract not configured
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"Connection contract not configured",
"errorType":"configuration"
}
Timestamp: UTC representation of the response creation using ISO-8601
401
Authentication error
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"Invalid username or password",
"errorType":"authentication"
}
Messages depends on authentication type. timestamp: UTC representation of the response creation using ISO-8601
403
No write permission
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"No write permission",
"errorType":"authorization"
}
Timestamp: UTC representation of the response creation using ISO-8601
404
Path not found
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"Path '' doesn't exist",
"errorType":"io"
}
Timestamp: UTC representation of the response creation using ISO-8601
Examples
Upload the file HttpUploadV2.txt
in folder http_api
as HttpUploadV2.txt
:
curl -i -X PUT -v "http://myHostName:21080/2.0/files/http_api/HttpUploadV2.txt"
-H "Content-Type: multipart/form-data"
-F "[email protected];type=application/octet-stream"
-b cookies.txt
Upload file with metadata
Endpoint:
/files/<path>
Method:
POST
Authentication: session cookies (
sp-http-usr
,sp-http-ses
) fromPOST /login/basic
Content-Type:
multipart/form-data
Description
Uploads a file and associates one or more metadata with it.
The file is stored in the specified <path>
.
Metadata can include Generic and Spazio2 classes.
Request parameters
Path parameters
path
Destination folder
string
yes
URL-encode special characters
file
Target filename to create in the destination folder
string
yes
URL-encode special characters
Multipart form fields
file
The content of the file to upload
binary
yes
@<local-filename>
with curl
.
metadata
Optional JSON object containing metadata key–value pairs.
string (JSON)
no
Supported classes: Generic, Spazio2.
Example: {"QUEUE_NAME":"QUEUE1","CORRELATION_ID":"invoices.xlsx"}
See How to manage metadata in Data Mover for details.
Responses
201
File uploaded successfully
{
"result":"ok",
"message":"Upload successful",
"fileset":"251" ,
}
400
Missing filename
{
"result":"failed",
"message":"No filename specified",
"errorType":"request_syntax"
}
400
Missing parameters or syntax error
{
"result":"failed",
"message":"Missing parameters or syntax error",
"errorType":"request_syntax"
}
Metadata has a syntax error or the content-type header is missing.
401
Connection contract not configured
{
"result":"failed",
"message":"Connection contract not configured",
"errorType":"configuration"
}
Messages depend on authentication type.
401
Authentication error
{
"result":"failed",
"message":"Invalid username or password",
"errorType":"authentication"
}
403
No write permission
{
"result":"failed",
"message":"No write permission",
"errorType":"authorization"
}
404
Path not found
{
"result":"failed",
"message":"Path '' doesn't exist",
"errorType":"io"
}
Examples
Uploads the local file test.txt
to folder httpapi
, setting Spazio2 metadata values for QUEUE_NAME
and CORRELATION_ID
.
curl -i -X POST -v "https://myHostName:21080/2.0/files/httpapi"
-H "Content-Type: multipart/form-data"
-F "[email protected];type=application/octet-stream"
-F 'metadata={"SPFB_SP2_FILE_SYS_MD.QUEUE_NAME":"QUEUE1", "SPFB_SP2_FILE_SYS_MD.CORRELATION_ID":"invoices.xslx"}'
-b cookies.txt
Download file
Endpoint:
/files/<path>/<file>
Method:
GET
Authentication: session cookies (
sp-http-usr
,sp-http-ses
) fromPOST /login/basic
Content-Type:
multipart/form-data
Description
Downloads the file <file>
located in <path>
.
The response body contains the raw file content. The server sets the response Content-Type
according to the stored file type.
Request parameters
Path parameters
path
Virtual Path where the file resides
string
yes
URL-encode special characters
file
File name to download
string
yes
URL-encode special characters
Responses
200
File found and content returned
Body: binary file bytes
Headers: Content-Type: <detected or application/octet-stream>
; Content-Length
; Content-Disposition: attachment; filename="<file>"
400
Missing filename
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"No filename specified",
"errorType":"request_syntax"
}
Timestamp: UTC representation of the response creation using ISO-8601
401
Connection contract not configured
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"Connection contract not configured",
"errorType":"configuration"
}
Timestamp: UTC representation of the response creation using ISO-8601
401
Authentication error
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"Invalid username or password",
"errorType":"authentication"
}
Messages depend on the authentication type. Timestamp: UTC representation of the response creation using ISO-8601
403
No download permission
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"No read permission",
"errorType":"authorization"
}
Timestamp: UTC representation of the response creation using ISO-8601
404
File not found
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"File '' doesn't exist",
"errorType":"io"
}
Timestamp: UTC representation of the response creation using ISO-8601
404
Path not found
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"Path '' doesn't exist",
"errorType":"io"
}
Timestamp: UTC representation of the response creation using ISO-8601
Example
curl -X GET https://myHostName:21080/2.0/files/http_api/HttpUploadV2Cookies_3.txt
-o download_file.txt
-b cookies.txt
Delete file
Endpoint:
/files/<path>/<file>
Method:
DELETE
Authentication: session cookies (
sp-http-usr
,sp-http-ses
) fromPOST /login/basic
Content-Type:
multipart/form-data
Description
Deletes the specified <file>
located in <path>
.
The operation permanently removes the file from the folder.
Request parameters
Path parameters
path
Folder where the file resides
string
yes
URL-encode special characters
file
File name to delete
string
yes
URL-encode special characters
Responses
200
File successfully deleted
{
"result":"ok",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"File deleted",
"fileset":
}
Timestamp: UTC representation of the response creation using ISO-8601
400
Missing parameter or syntax error
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"missing param or syntax error",
"errorType":"syntax_error"
}
Timestamp: UTC representation of the response creation using ISO-8601
401
Connection contract not configured
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"Connection contract not configured",
"errorType":"configuration"
}
Timestamp: UTC representation of the response creation using ISO-8601
401
Authentication error
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"Invalid username or password",
"errorType":"authentication"
}
Timestamp: UTC representation of the response creation using ISO-8601
403
No delete permission
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"No delete permission",
"errorType":"authorization"
}
Timestamp: UTC representation of the response creation using ISO-8601
404
File not found
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"File '' doesn't exist",
"errorType":"io"
}
Timestamp: UTC representation of the response creation using ISO-8601
404
Path not found
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"Path '' doesn't exist",
"errorType":"io"
}
Timestamp: UTC representation of the response creation using ISO-8601
Examples
Deletes the file HttpUploadV2.txt
from folder http_api
.
curl -i -X DELETE https://myHostName:21080/2.0/files/http_api/HttpUploadV2Cookies_3.txt
-b cookies.txt
METADATA
The Metadata APIs allow you to add, update, or read metadata associated with files. Metadata can belong to one or more classes:
Generic metadata – custom user-defined attributes
Spazio2 metadata
Insert or update metadata
Endpoint:
/metadata/<path>/<file>
Method:
POST
Authentication: session cookies (
sp-http-usr
,sp-http-ses
) fromPOST /login/basic
Content-Type:
application/json
Description
Add or updates one or more metadata entries for the specified file <file>
in <path>
.
If a metadata key already exists, its value is replaced with the new one.
Request parameters
Path parameters
path
Folder containing the file
string
yes
URL-encode special characters
file
File name to update metadata for
string
yes
URL-encode special characters
Request body
A JSON object containing key values pairs of metadata entries. Each key corresponds to a metadata field.
Supported classes are: Generic and Spazio2 (keys with prefix SPFB_SP2_FILE_SYS_MD.
belong to Spazio2).
Example:
{
"OFFICE": "Accounting",
"CITY": "London"
}
Responses
200
Metadata updated successfully
{
"result":"ok",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"Metadata updated",
"fileset":"251"
}
timestamp: UTC representation of the response creation using ISO-8601
400
Missing filename
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"No filename specified",
"errorType":"request_syntax"
}
timestamp: UTC representation of the response creation using ISO-8601
400
Missing parameter or syntax error
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"Missing parameters or syntax error",
"errorType":"request_syntax"
}
timestamp: UTC representation of the response creation using ISO-8601
401
Connection contract not configured
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"Connection contract not configured",
"errorType":"configuration"
}
timestamp: UTC representation of the response creation using ISO-8601
401
Authentication error
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"Invalid username or password",
"errorType":"authentication"
}
timestamp: UTC representation of the response creation using ISO-8601
403
No write permission
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"No write permission",
"errorType":"authorization"
}
timestamp: UTC representation of the response creation using ISO-8601
404
File not found
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"File '' doesn't exist",
"errorType":"io"
}
timestamp: UTC representation of the response creation using ISO-8601
404
Path not found
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"Path '' doesn't exist",
"errorType":"io"
}
timestamp: UTC representation of the response creation using ISO-8601
Example
The file HttpUploadV2Cookies_3.txt
is associated with OFFICE
metadata, which has the value 'Accounting', and with CITY
metadata, which has the value 'London'.
curl -i -X POST -v "https://myHostName:21080/2.0/metadata/httpapi/HttpUploadV2Cookies_3.txt"
-H "Content-Type: application/json"
-d '{"OFFICE":"Accounting", "CITY":"London"}'
-b cookies.txt
Read metadata
Endpoint:
/meadata/<path>/<file>
Method:
GET
Authentication: session cookies (
sp-http-usr
,sp-http-ses
) fromPOST /login/basic
Description
Retrieves the list of metadata associated with the file <file>
located in <path>
.
The response includes both user-defined and system metadata.
Request parameters
Path parameters
path
Folder where the file resides
string
yes
URL-encode special characters
file
File name whosw metadata will be retrivied
string
yes
URL-encode special characters
Responses
200
Metadata retrieved successfully
"metadata":{
"dstFileName":"",
"size":"89",
"correlationId":"",
"putDate":"2020-09-15T10:55:01.669Z",
"firstReadDate":"",
"lastModifiedTime":"2020-09-15T10:55:01.583Z",
"lastAccessTime":"",
"creationTime":"2020-09-15T10:55:01.583Z",
"datatype":"application/octet-stream",
"description":"",
"Partner":"Partner5"
}
400
No filename provided
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"No filename specified",
"errorType":"request_syntax"
}
Example if specified only path of folder timestamp: UTC representation of the response creation using ISO-8601
401
Connection contract not configured
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"Connection contract not configured",
"errorType":"configuration"
}
timestamp: UTC representation of the response creation using ISO-8601
401
Authentication error
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"Invalid username or password",
"errorType":"authentication"
}
Messages depends on authentication type. timestamp: UTC representation of the response creation using ISO-8601
403
No read permission
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"No read permission",
"errorType":"authorization"
}
timestamp: UTC representation of the response creation using ISO-8601
404
File not found
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":" doesn't exist",
"errorType":"io"
}
timestamp: UTC representation of the response creation using ISO-8601
404
Path not found
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"Path '' doesn't exist",
"errorType":"io"
}
timestamp: UTC representation of the response creation using ISO-8601
Example
curl -i-X GET -v "http://myHostName:21080/2.0/metadata/http_api/HttpUploadV2Cookies_3.txt
-H "Accept: application/json"
-b cookies.txt
Response
{
"id": "/httpapi/testHttpUploadV2Cookies_3.txt",
"filename": "testHttpUploadV2Cookies_3.txt",
"fileset": 5832,
"owner": "",
"directory": false,
"attributes": {
"firstReadDate": "",
"lastModifiedTime": "2025-05-23T14:08:40.886Z",
"size": "6",
"creationTime": "2025-05-23T14:08:40.886Z",
"datatype": "application/octet-stream",
"description": "",
"correlationId": "",
"putDate": "2025-05-23T14:08:40.871Z"
}
}
COUNTELEMENTS
Count elements
Endpoint:
/countelements/<path>
Method:
GET
Authentication: session cookies (
sp-http-usr
,sp-http-ses
) fromPOST /login/basic
Content-Type:
application/json
Description
Returns the number of elements (files and/or folders) that exist in the specified <path>
.
You can filter the count by name pattern or by element type (files or folders only).
Request parameters
Path parameters
path
Folder to count the items in
string
yes
URL-encode special characters
Query parameters
filter
Pattern used to filter elements by name.
Use *
as a wildcard to match any sequence of characters
string
no
Default: *
type
Specifies which element types to count: all
, files
, or folders
string
no
Default: all
Response
200
Count operation completed successfully
2
Possible values is 0 or a positive number.
401
Connection contract not configured
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"Connection contract not configured",
"errorType":"configuration"
}
timestamp: UTC representation of the response creation using ISO-8601
401
Authentication error
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"Invalid username or password",
"errorType":"authentication"
}
timestamp: UTC representation of the response creation using ISO-8601
403
No list permission
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"No list permission",
"errorType":"authorization"
}
timestamp: UTC representation of the response creation using ISO-8601
404
Path not found
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"Path doesn't exist",
"errorType":"io"
}
timestamp: UTC representation of the response creation using ISO-8601
Example
Counts all elements (files and folders) in httpapi
folder:
curl -i -u part1:partner1 -X GET -v "https://myHostName:21080/2.0/countelements/httpapi?type=all"
-b cookies.txt
DIRECTORIES
List elements
Endpoint:
/directories/<path>
Method:
GET
Authentication: session cookies (
sp-http-usr
,sp-http-ses
) fromPOST /login/basic
Content-Type:
application/json
Description
Returns the list of folders and files contained in the given <path>
with optional filtering, sorting, and paging.
Request parameters
Path parameters
path
Folder to list
string
yes
URL-encode special characters
Query parameters
filter
Pattern used to filter elements by name.
Use *
as a wildcard to match any sequence of characters
string
no
Default: *
sort
Sort field: name
| size
| put_date
| read_date
| expiry_date
string
no
Default: name
direction
Sort order
string
no
start
Zero-based offset of the first element to return
integer
no
Default: 0
limit
Max number of elements to return
integer
no
Default: 500
type
Specifies which element types to count: all
, files
, or folders
string
no
Default: all
attributes
Comma-separated list of attribute names to include in each item. If an attribute is not present, its value is empty. Attributes names are: dstFileName
, size
, correlationId
, putDate
, firstReadDate
, lastModifiedTime
, lastAccessTime
, creationTime
, datatype
, description
string
no
Default: all
Responses
200
Folder listed successfully
See successful response body below
Example of list in inbox folder with 2 folders and 4 files.
401
Authentication error
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"Invalid username or password",
"errorType":"authentication"
}
timestamp: UTC representation of the response creation using ISO-8601
401
Connection contract not configured
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"Connection contract not configured",
"errorType":"configuration"
}
timestamp: UTC representation of the response creation using ISO-8601
403
No list permission
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"No list permission",
"errorType":"authorization"
}
timestamp: UTC representation of the response creation using ISO-8601
404
Path not found
{
"result":"failed",
"timestamp":"2020-11-13T08:58:20.680Z"
"message":"Path doesn't exist",
"errorType":"io"
}
timestamp: UTC representation of the response creation using ISO-8601
Successful response body example
{
"uri": "https://<host>:<port>/2.0/directories/<path>",
"totalCount": "number as string",
"files": [
{
"id": "/<path>/dir1",
"uri": "https://<host>:<port>/2.0/directories/<path>/dir1",
"filename": "dir1",
"owner": "",
"directory": true,
"attributes": {
"dstFileName": "",
"size": "",
"correlationId": "",
"putDate": "",
"firstReadDate": "",
"lastModifiedTime": "",
"lastAccessTime": "",
"creationTime": "",
"datatype": "",
"description": ""
}
},
{
"id": "/<path>/fileA.txt",
"uri": "https://<host>:<port>/2.0/files/<path>/fileA.txt",
"metaUri": "https://<host>:<port>/2.0/metadata/<path>/fileA.txt",
"filename": "fileA.txt",
"fileset": 54678,
"owner": "",
"directory": false,
"attributes": {
"dstFileName": "",
"size": "206",
"correlationId": "",
"putDate": "2020-09-15T10:55:05.649Z",
"firstReadDate": "",
"lastModifiedTime": "2020-09-15T10:55:05.601Z",
"lastAccessTime": "",
"creationTime": "2020-09-15T10:55:05.601Z",
"datatype": "application/octet-stream",
"description": ""
}
}
]
}
Example
List the first 25 items in httpapi
, sorted by size, descending:
curl -i -X GET -v "https://myHostName:21080/2.0/directories/httpapi?sort=size&direction=DESC&start=0&limit=25"
-o cookies.txt
Last updated