Initializing help system before first use

Portation resources

Operation Description
GET /api/portations

Get all undismissed portations
POST /api/portations/dismissed

Dismiss portations
POST /api/portations/exports

Create an export
GET /api/portations/exports/{id}

Get an export
GET /api/portations/exports/{id}/file

Get the binary data of an export
GET /api/portations/files

Get all portation files
POST /api/portations/imports

Create an import
GET /api/portations/imports/{id}

Get an import
POST /api/portations/upgrades

Create an upgrade
GET /api/portations/upgrades/{id}

Get an upgrade

GET /api/portations

Get all undismissed portations

Get all portations visible to the current user that have not previously been dismissed.

Request Parameters

Name Description Type Data Type
page

Number of the page, starting at zero

 query integer (int32)
size

Number of elements per page

 query integer (int32)

Responses

200 OK

The page of portations

Content-Type application/vnd.com.fico.xpress.insight.v2+json

Properties

content: object[]
Array of Portation

POST /api/portations/dismissed

Dismiss portations

Dismiss portations identified by the provided IDs.

Request Body

Content-Type application/vnd.com.fico.xpress.insight.v2+json

Array of string

Responses

204 No Content

The portations have been dismissed

Content-Type application/vnd.com.fico.xpress.insight.v2+json

Empty response body

404 Not Found

A portation does not exist or the user does not have access to it

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-404",
        "desc": "Not Found",
        "innerError": {
            "code": "OPTI-Insight-Persistence-DocumentNotFound",
            "desc": "Document not found",
            "message": "Unable to find document"
        },
        "message": "Not Found",
        "parentId": "0000000000000def",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}

POST /api/portations/exports

Create an export

Create an export from the provided ExportRequest. The created export will record the progress and outcome of exporting the source described by the request.

Request Body

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ExportRequest

Responses

201 Created

Export created

Content-Type application/vnd.com.fico.xpress.insight.v2+json

Export

Location

The URL of the created resource

 string
403 Forbidden

Access denied

422 Unprocessable Entity

Attempting to export an unsupported object type (not an app, folder or scenario), or an invalid export path was specified.

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-422",
        "desc": "Unprocessable Entity",
        "innerError": {
            "code": "FICO-Platform-Validation-InvalidValue",
            "desc": "Entity processing failed",
            "message": "Entity processing failed"
        },
        "message": "Unprocessable Entity",
        "parentId": "0000000000000def",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}

GET /api/portations/exports/{id}

Get an export

Get an export by ID.

Request Parameters

Name Description Type Data Type
id

The ID of the export

 path string (uuid) required

Responses

200 OK

The export

Content-Type application/vnd.com.fico.xpress.insight.v2+json

Export

404 Not Found

The export does not exist or the user does not have access to it

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-404",
        "desc": "Not Found",
        "innerError": {
            "code": "OPTI-Insight-Persistence-DocumentNotFound",
            "desc": "Document not found",
            "message": "Unable to find document"
        },
        "message": "Not Found",
        "parentId": "0000000000000def",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}

GET /api/portations/exports/{id}/file

Get the binary data of an export

Get the binary data of the export identified by the provided ID.

Request Parameters

Name Description Type Data Type
id

The ID of the export

 path string (uuid) required

Responses

200 OK

Binary stream of the file contents

Content-Type application/vnd.com.fico.xpress.insight.v2+octet-stream

string (binary)

404 Not Found

The portation file does not exist or the user does not have access to it

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-404",
        "desc": "Not Found",
        "innerError": {
            "code": "OPTI-Insight-Persistence-DocumentNotFound",
            "desc": "Document not found",
            "message": "Unable to find document"
        },
        "message": "Not Found",
        "parentId": "0000000000000def",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}
Content-Type application/vnd.com.fico.xpress.insight.v2+octet-stream

Empty response body

GET /api/portations/files

Get all portation files

Get all portation files available for import to the server.

Request Parameters

Name Description Type Data Type
page

Number of the page, starting at zero

 query integer (int32)
size

Number of elements per page

 query integer (int32)

Responses

200 OK

The portation files

Content-Type application/vnd.com.fico.xpress.insight.v2+json

Properties

content: object[]
Array of PortationDirectory

403 Forbidden

Access denied

POST /api/portations/imports

Create an import

Create an import from the provided insight file. This will record the progress and outcome of importing the supplied file.

Request Body

Content-Type multipart/form-data

Properties

importUploadRequest: required

Options controlling the import

insightFile: string (binary) required

The insight file to be imported

Responses

201 Created

Import created

Content-Type application/vnd.com.fico.xpress.insight.v2+json

Import

Location

The URL of the created resource

 string
403 Forbidden

Access denied

413 Request Entity Too Large

The file to import exceeds the maximum insight file upload size

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-413",
        "desc": "Payload Too Large",
        "innerError": {
            "code": "FICO-Platform-Validation-FileTooLarge",
            "desc": "Insight file too large",
            "message": "File larger than 300 MB cannot be imported via upload. Try importing via file system."
        },
        "message": "Payload Too Large",
        "parentId": "0000000000000def",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}
422 Unprocessable Entity

Invalid import type, invalid target or unsupported security option for the supplied import type

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-422",
        "desc": "Unprocessable Entity",
        "innerError": {
            "code": "FICO-Platform-Validation-InvalidValue",
            "desc": "Entity processing failed",
            "message": "Entity processing failed"
        },
        "message": "Unprocessable Entity",
        "parentId": "0000000000000def",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}

GET /api/portations/imports/{id}

Get an import

Get an import by ID.

Request Parameters

Name Description Type Data Type
id

The ID of the import

 path string (uuid) required

Responses

200 OK

The import

Content-Type application/vnd.com.fico.xpress.insight.v2+json

Import

404 Not Found

The import did not exist or the user did not have access to it

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-404",
        "desc": "Not Found",
        "innerError": {
            "code": "OPTI-Insight-Persistence-DocumentNotFound",
            "desc": "Document not found",
            "message": "Unable to find document"
        },
        "message": "Not Found",
        "parentId": "0000000000000def",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}

POST /api/portations/upgrades

Create an upgrade

Create an upgrade from the provided app zip file. Upgrading an app will augment all the resources in the app with the contents of the zip. This will record the progress and outcome of upgrading the app.

Request Body

Content-Type multipart/form-data

Properties

app: string (binary) required

The zip file of the app to be upgraded

upgradeRequest: required

Options controlling the upgrade

Responses

201 Created

Upgrade created

Content-Type application/vnd.com.fico.xpress.insight.v2+json

Upgrade

Location

The URL of the created resource

 string
403 Forbidden

Access denied

413 Request Entity Too Large

The file containing the upgrade contents exceeds the maximum file upload size

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-413",
        "desc": "Payload Too Large",
        "innerError": {
            "code": "FICO-Platform-Validation-FileTooLarge",
            "desc": "App file too large",
            "message": "File exceeded upload threshold (300 MB)."
        },
        "message": "Payload Too Large",
        "parentId": "0000000000000def",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}
422 Unprocessable Entity

invalid target for the supplied upgrade file

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-422",
        "desc": "Unprocessable Entity",
        "innerError": {
            "code": "FICO-Platform-Validation-InvalidValue",
            "desc": "Entity processing failed",
            "message": "Entity processing failed"
        },
        "message": "Unprocessable Entity",
        "parentId": "0000000000000def",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}

GET /api/portations/upgrades/{id}

Get an upgrade

Get an upgrade by ID.

Request Parameters

Name Description Type Data Type
id

The ID of the upgrade

 path string (uuid) required

Responses

200 OK

The upgrade

Content-Type application/vnd.com.fico.xpress.insight.v2+json

Upgrade

404 Not Found

The upgrade did not exist or the user did not have access to it

Content-Type application/vnd.com.fico.xpress.insight.v2+json

ErrorResponse

Example: 
{
    "error": {
        "code": "FICO-Platform-Http-404",
        "desc": "Not Found",
        "innerError": {
            "code": "OPTI-Insight-Persistence-DocumentNotFound",
            "desc": "Document not found",
            "message": "Unable to find document"
        },
        "message": "Not Found",
        "parentId": "0000000000000def",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}

ErrorDetail: object

An error detail

Properties

code: string

The unique code for this error

Example: 
"FICO_PLATFORM_VALIDATION_INVALID_VALUE"
desc: string

A description of this error for client information, not intended for display to the end user

Example: 
"Conflict"
message: string

A message providing further information which may be displayed to the end user

Example: 
"Conflict"
target: string

An identifier to help the client locate the error. Typically a JSON property name.

timestamp: string (date-time)

When the error was first detected

ErrorResponse: object

An error response containing fault or error information

Properties

error:

The top level error

Export: object

Contains the status and location of an export.

Properties

dismissed: boolean

True indicates this portation has been dismissed by the owner.

downloadUrl: string (uri)

The download url of this export

Example: 
"/api/portations/exports/9b70bd59-9499-4848-9b5b-75aaa0c26f35/file"
errorMessages: string[]

The error messages produced by this portation

Array of string
filename: string

The filename for this portation

Example: 
"MyFile.insight"
finished: string (date-time)

When this portation finished

id: string (uuid)

The ID of this export

Example: 
"02864266-a4a8-a1bc-fd79-bd98e09b5690"
includeFoldersAndScenarios: boolean

The filter to indicate whether folders and scenario are included as part of this export or not. This is applicable only for an app export

infoMessages: string[]

The info messages produced by this portation

Array of string
name: string (1 to 255 chars) , must match ^[^\p{Cntrl}]*$ & ^\S(?:[\s\S]*\S)?$

The name of this export

Example: 
"My export"
objectType: string , one of { EXPORT }
owner:

The user that owns this portation

parent:

The parent of this portation. This is populated when this portation belongs to another. For example when importing an insight file which contains many apps then each app import will be parented by the original import portation.

path: string

The path for this export relative to the configured portation directory.

Example: 
"exports/MyExport.insight"
reference:

The reference of the item (app, folder or scenario) being ported

started: string (date-time)

When this portation started

status: string , one of { QUEUED , MIGRATING , PORTING , SUCCESS , ERROR }

The status of this portation

url: string (uri)

The URL of this export

Example: 
"/api/portations/exports/02864266-a4a8-a1bc-fd79-bd98e09b5690"

ExportRequest: object

Properties

includeFoldersAndScenarios: boolean true

Filter to indicate whether to include folders and scenario as part of an app export. This is not required for a folder or a scenario export

path: string

Path to the export location. Should be used when exporting to FICO Drive.

Example: 
"/exports/path/"
source:

Reference to the item (app, folder or scenario) to be exported

Import: object

Contains the status and location of an import.

Properties

dismissed: boolean

True indicates this portation has been dismissed by the owner.

errorMessages: string[]

The error messages produced by this portation

Array of string
filename: string

The filename for this portation

Example: 
"MyFile.insight"
finished: string (date-time)

When this portation finished

id: string (uuid)

The ID of this import

Example: 
"816db222-428d-6802-7e92-4dde3c7e3059"
importType: string , one of { APP , FOLDER_OR_SCENARIO , REPOSITORY }

Type of import to perform with the supplied file.

Example: 
"APP"
infoMessages: string[]

The info messages produced by this portation

Array of string
name: string (1 to 255 chars) , must match ^[^\p{Cntrl}]*$ & ^\S(?:[\s\S]*\S)?$

The name of this import

Example: 
"My import"
objectType: string , one of { IMPORT }
owner:

The user that owns this portation

parent:

The parent of this portation. This is populated when this portation belongs to another. For example when importing an insight file which contains many apps then each app import will be parented by the original import portation.

reference:

The reference of the item (app, folder or scenario) being ported

security: string , one of { ORIGINAL , PRIVATE }

Controls the security of imported assets

Example: 
"ORIGINAL"
started: string (date-time)

When this portation started

status: string , one of { QUEUED , MIGRATING , PORTING , SUCCESS , ERROR }

The status of this portation

target:

The reference to the parent of the imported scenario or folder. This will not be populated for an app import

url: string (uri)

The URL of this import

Example: 
"/api/portations/imports/816db222-428d-6802-7e92-4dde3c7e3059"

ImportUploadRequest: object

Properties

importType: string , one of { APP , FOLDER_OR_SCENARIO , REPOSITORY }

Type of import to perform with the supplied file.

Example: 
"APP"
security: string , one of { ORIGINAL , PRIVATE (default) }

Controls the security of imported assets

Example: 
"ORIGINAL"
target:

The reference to the target item (app or folder) to which a folder or a scenario is to be imported. This will not be needed for an app or repository import

InnerError: object

More specific error information

Properties

code: string

The unique code for this error

Example: 
"FICO-Platform-Validation-FileTooLarge"
desc: string

A description of this error for client information, not intended for display to the end user

Example: 
"Attachment upload too large"
innerError:

More specific error information

message: string

A message providing further information which may be displayed to the end user

Example: 
"Files larger than 300 MB cannot be uploaded as attachments."

OuterError: object

The top level error

Properties

code: string , one of { FICO-Platform-Http-400 , FICO-Platform-Http-404 , FICO-Platform-Http-406 , FICO-Platform-Http-409 , FICO-Platform-Http-413 , FICO-Platform-Http-422 , FICO-Platform-Http-423 , FICO-Platform-Http-429 , FICO-Platform-Http-500 , FICO-Platform-Http-502 , FICO-Platform-Http-503 }

The unique code for this error

Example: 
"FICO-Platform-Http-409"
desc: string

A description of this error for client information, not intended for display to the end user

Example: 
"Conflict"
details: object[]

Details about specific errors that led to this reported error

Array of ErrorDetail
innerError:

More specific error information

message: string

A message providing further information which may be displayed to the end user

Example: 
"Conflict"
parentId: string

An OpenTracing parent-span ID

Example: 
"0020000000000001"
spanId: string

An OpenTracing span ID

Example: 
"b2fb4a1d1a96d312"
timestamp: string (date-time)

When the error was first detected

traceId: string

An OpenTracing trace ID

Example: 
"463ac35c9f6413ad48485a3953bb6125"

Page: object

A page containing a subset of content which can be paginated through

Properties

content: object[]

The items in this page of results

Array of object
first: boolean

Whether this is the first page

Example: 
false
last: boolean

Whether this is the last page

Example: 
true
number: integer (int32)

The page number, starting at 0

Example: 
4
numberOfElements: integer (int32)

The number of elements in this page of results

Example: 
18
size: integer (int32)

The number of results per page

Example: 
20
sort:

The sort order applied to the results

totalElements: integer (int32)

The total number of elements in all the pages

Example: 
98
totalPages: integer (int32)

The total number of pages

Example: 
5

Portation: object

Contains the status and location of a portation.

Properties

dismissed: boolean

True indicates this portation has been dismissed by the owner.

errorMessages: string[]

The error messages produced by this portation

Array of string
filename: string

The filename for this portation

Example: 
"MyFile.insight"
finished: string (date-time)

When this portation finished

id: string (uuid)

The ID of this reference

infoMessages: string[]

The info messages produced by this portation

Array of string
name: string (1 to 255 chars) , must match ^[^\p{Cntrl}]*$ & ^\S(?:[\s\S]*\S)?$

The name of this reference

Example: 
"name"
objectType: string , one of { EXPORT , IMPORT , UPGRADE }
owner:

The user that owns this portation

parent:

The parent of this portation. This is populated when this portation belongs to another. For example when importing an insight file which contains many apps then each app import will be parented by the original import portation.

reference:

The reference of the item (app, folder or scenario) being ported

started: string (date-time)

When this portation started

status: string , one of { QUEUED , MIGRATING , PORTING , SUCCESS , ERROR }

The status of this portation

url: string (uri)

The URL of this reference

PortationDirectory: object

Describes the location and contents of a directory within the configured portation path.

Properties

files: object[]

The portation files present in this directory

Array of PortationFile
name: string

The directory name

Example: 
"exports"
path: string

The directory path, relative to the configured portation path

Example: 
"/exports"

PortationFile: object

Describes the location and attributes of a portation file.

Properties

filename: string

The filename

Example: 
"MyExport.insight"
lastModified: string (date-time)

When the file was last modified

path: string

The file path, relative to the configured portation path

Example: 
"/exports/MyExport.insight"
size: integer (int64)

The file size in bytes

ReferenceApp: object

The basic details of an app

Properties

id: string (uuid)

The ID of this app

Example: 
"00007eff-83f9-05fe-ffff-81007c05fc01"
name: string (1 to 255 chars) , must match ^[^\p{Cntrl}]*$ & ^\S(?:[\s\S]*\S)?$

The name of this app

Example: 
"My app"
objectType: string , one of { APP }
url: string (uri)

The URL of this app

Example: 
"/api/apps/00007eff-83f9-05fe-ffff-81007c05fc01"

ReferenceUser: object

The basic details of a user

Properties

id: string (uuid)

The ID of this user

Example: 
"0013ebae-4d4c-793c-ffec-1451b28ba2f9"
name: string (1 to 255 chars) , must match ^[^\p{Cntrl}]*$ & ^\S(?:[\s\S]*\S)?$

The name of this user

Example: 
"My user"
objectType: string , one of { USER }
url: string (uri)

The URL of this user

Example: 
"/api/admin/users/0013ebae-4d4c-793c-ffec-1451b28ba2f9"

Sort: object

Details of how paged results were sorted

Properties

empty: boolean

True if there are no results

sorted: boolean

True if the results are sorted

unsorted: boolean

True if the results are not sorted

Upgrade: object

Contains the status of an upgrade

Properties

dismissed: boolean

True indicates this portation has been dismissed by the owner.

errorMessages: string[]

The error messages produced by this portation

Array of string
filename: string

The filename for this portation

Example: 
"MyFile.zip"
finished: string (date-time)

When this portation finished

id: string (uuid)

The ID of this upgrade

Example: 
"0b382251-9579-09f4-f4c7-ddae4d82d010"
infoMessages: string[]

The info messages produced by this portation

Array of string
name: string (1 to 255 chars) , must match ^[^\p{Cntrl}]*$ & ^\S(?:[\s\S]*\S)?$

The name of this upgrade

Example: 
"My upgrade"
objectType: string , one of { UPGRADE }
owner:

The user that owns this portation

parent:

The parent of this portation. This is populated when this portation belongs to another. For example when importing an insight file which contains many apps then each app import will be parented by the original import portation.

reference:

The reference of the App to be upgraded

started: string (date-time)

When this portation started

status: string , one of { QUEUED , MIGRATING , PORTING , SUCCESS , ERROR }

The status of this portation

url: string (uri)

The URL of this upgrade

Example: 
"/api/portations/upgrades/0b382251-9579-09f4-f4c7-ddae4d82d010"
validateModelName: boolean true

Whether to validate that the new model name matches the previous model name

Example: 
true

UpgradeRequest: object

The request to upgrade an app

Properties

reference:

The reference of the App to be upgraded.

upgradeType: string , one of { FULL , PARTIAL (default) }

Whether the upgrade app file should be considered to represent the full app or a partial. A full upgrade will replace the existing app with the app being uploaded, deleting any existing app content that is not in the app being uploaded. A partial upgrade will add and/or replace content in the existing app.

Example: 
"PARTIAL"
validateModelName: boolean

Whether the model name should be validated or not.

Example: 
true
Parent Topic Insight 5 REST API

© 2001-2025 Fair Isaac Corporation. All rights reserved. This documentation is the property of Fair Isaac Corporation (“FICO”). Receipt or possession of this documentation does not convey rights to disclose, reproduce, make derivative works, use, or allow others to use it except solely for internal evaluation purposes to determine whether to purchase a license to the software described in this documentation, or as otherwise set forth in a written software license agreement between you and FICO (or a FICO affiliate). Use of this documentation and the software described in it must conform strictly to the foregoing permitted uses, and no other use is permitted.