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 or https) 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

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

Parameter

Description

Data Type

Required

username

Username

String

yes

password

The user password

String

yes

Responses

HTTP Status

Description

Example

Notes

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) from POST /login/basic
Content-Type: multipart/form-data

Description

Uploads a file to the specified <path> .

Request parameters

Path parameters

Parameter

Description

Data Type

Required

Note

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

Parameter

Description

Data Type

Required

Note

file

The content of the file to upload.

binary

yes

Use @<local-filename> with curl

Responses

HTTP Status code

Description

Example

Notes

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) from POST /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

Parameter

Description

Data Type

Required

Note

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

Parameter

Description

Data Type

Required

Note

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)

Supported classes: Generic, Spazio2. Example: {"QUEUE_NAME":"QUEUE1","CORRELATION_ID":"invoices.xlsx"}

See How to manage metadata in Data Mover for details.

Responses

HTTP Status code

Description

Response example

Notes

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) from POST /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

Parameter

Description

Data Type

Required

Note

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

HTTP Status code

Description

Response example

Notes

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) from POST /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

Parameter

Description

Data Type

Required

Note

path

Folder where the file resides

string

yes

URL-encode special characters

file

File name to delete

string

yes

URL-encode special characters

Responses

HTTP Status code

Description

Response example

Notes

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 - see the list on the How to manage metadata in Data Mover page.

Insert or update metadata

Endpoint: /metadata/<path>/<file>
Method: POST
Authentication: session cookies (sp-http-usr, sp-http-ses) from POST /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

Parameter

Description

Data Type

Required

Note

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). See the How to manage metadata in Data Mover page for details.

Example of Generic metadata:

{
  "OFFICE": "Accounting",
  "CITY": "London"
}

Responses

HTTP Status code

Description

Response example

Notes

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 the OFFICE generic metadata, which has the value 'Accounting', and with CITY generic 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) from POST /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 whose metadata will be retrieved

string

yes

URL-encode special characters

Responses

HTTP Status code

Description

Response example

Notes

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) from POST /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

Default: *

type

Specifies which element types to count: all, files, or folders

string

Default: all

Response

HTTP Status code

Description

Response example

Notes

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) from POST /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

Default: *

sort

Sort field: name | size | put_date | read_date | expiry_date

string

Default: name

direction

Sort order

string

start

Zero-based offset of the first element to return

integer

Default: 0

limit

Max number of elements to return

integer

Default: 500

type

Specifies which element types to count: all, files, or folders

string

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

Default: all

Responses

HTTP Status code

Description

Response example

Notes

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

PreviousMessage Processing Rules 🚀NextJob Manager APIs 🚀

Last updated 15 days ago

Pre-requisites

Base URL

AUTHENTICATION

Login

Description

Request parameters

Responses

FILES

Upload file

Description

Request parameters

Responses

Examples

Upload file with metadata

Description

Request parameters

Responses

Examples

Download file

Description

Request parameters

Responses

Example

Delete file

Description

Request parameters

Responses

Examples

METADATA

Insert or update metadata

Description

Request parameters

Responses

Example

Read metadata

Description

Request parameters

Responses

Example

COUNTELEMENTS

Count elements

Description

Request parameters

Response

Example

DIRECTORIES

List elements

Description

Request parameters

Responses

Example