Initializing help system before first use

Folder resources

Operation Description
POST /api/folders

Create a new folder
GET /api/folders/{id}

Get a folder
DELETE /api/folders/{id}

Delete a folder
PATCH /api/folders/{id}

Update a folder
GET /api/folders/{id}/children

Get the contents of a folder
POST /api/folders/{id}/children

Move a folder or scenario

POST /api/folders

Create a new folder

Create a new folder in the app. To create a folder in the app root, the app must be the same as the parent if given.

Request Body

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

FolderCreationRequest

Responses

201 Created

The successfully created folder

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

Folder

Location

The URL of the created resource

 string
403 Forbidden

The current user is not authorized to create this folder

422 Unprocessable Entity

The app or parent folder were invalid

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",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}

GET /api/folders/{id}

Get a folder

Get a folder by ID.

Request Parameters

Name Description Type Data Type
id

The folder ID

 path string (uuid) required

Responses

200 OK

The folder

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

Folder

404 Not Found

The folder did not exist or was unavailable to the current user

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",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}

DELETE /api/folders/{id}

Delete a folder

Delete a folder by ID. This will delete the folder and all descendant folders and scenarios.

Security: FOLDER_DELETE is required to delete the folder.

Request Parameters

Name Description Type Data Type
id

The folder ID

 path string (uuid) required

Responses

204 No Content

The folder was deleted

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

Empty response body

403 Forbidden

The current user was not authorized to delete this folder

404 Not Found

The folder did not exist or was unavailable to the current user

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",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}

PATCH /api/folders/{id}

Update a folder

Update the properties of a folder. Only the name, share status and owner of a folder can be changed. Changes to share status and owner can optionally be cascaded to all descendant folders. When changing the name of a folder, a suffix may be applied to ensure that the name is unique. If the share status is PRIVATE and no owner is supplied, the current user becomes the owner to prevent loss of access.

Security: FOLDER_EDIT is required to change the name, FOLDER_SHARE is required to change the share status, and FOLDER_OWNER is required to change the owner. The user must have write access to the folder.

Request Body

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

Folder

Request Parameters

Name Description Type Data Type
id

The ID of the folder

 path string (uuid) required
cascadeOwner

Whether to change the owner of all descendants to be the same as this folder's

 query boolean
cascadeShareStatus

Whether to change the share status of all descendants to be the same as this folder's

 query boolean

Responses

200 OK

The updated folder

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

Folder

403 Forbidden

The current user was not authorized to update this folder

404 Not Found

The folder did not exist or was unavailable to the current user

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",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}
422 Unprocessable Entity

The requested changes were invalid. For example, the supplied name was too long.

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",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}

GET /api/folders/{id}/children

Get the contents of a folder

Get the folders and scenarios that are the immediate children of this folder.

Request Parameters

Name Description Type Data Type
id

The folder ID

 path string (uuid) required
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 children, both folders and scenarios, sorted by name

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

PageOfFolderOrScenario

404 Not Found

The folder did not exist or was unavailable to the current user

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",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}

POST /api/folders/{id}/children

Move a folder or scenario

Move a folder or scenario into the parent folder.

Request Body

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

Empty response body

Request Parameters

Name Description Type Data Type
id

The ID of the new parent folder

 path string (uuid) required

Responses

200 OK

The moved folder or scenario

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

Empty response body

403 Forbidden

The current user did not authorized to move the folder or scenario to this folder

404 Not Found

The folder or scenario did not exist or was unavailable to the current user

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",
        "spanId": "0000000000000123",
        "timestamp": "1970-01-03T02:01:33.219Z",
        "traceId": "0000000000000abc"
    }
}
422 Unprocessable Entity

The request tried to move some other type of object (not a folder or scenario), or it was unavailable to the current user

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",
        "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

Folder: object

Represents a folder in the app folder hierarchy. See the wider product documentation for more information on folders

Properties

app:

The app that owns this folder

id: string (uuid)

The ID of this folder

Example: 
"01f7774e-00c2-004e-fe08-88b1834def44"
name: string (1 to 255 chars) , must match ^[^\p{Cntrl}]*$ & ^\S(?:[\s\S]*\S)?$

The name of this folder

Example: 
"My folder"
objectType: string , one of { FOLDER }
owner:

The user that owns this folder

parent:

The parent of this folder

path: string

The path within the repository

Example: 
"/app-name/folder-a/folder-b"
shareStatus: string , one of { FULLACCESS , PRIVATE , READONLY }

The share status of this folder

url: string (uri)

The URL of this folder

Example: 
"/api/folders/01f7774e-00c2-004e-fe08-88b1834def44"

FolderCreationRequest: object

A request to create a new folder

Properties

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

The name for the folder

Example: 
"myFolder"
parent:

The app or folder to create this folder under

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-409 , FICO-Platform-Http-413 , FICO-Platform-Http-422 , FICO-Platform-Http-423 , FICO-Platform-Http-429 , FICO-Platform-Http-500 , 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"

PageOfFolderOrScenario: object

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

Properties

content: []

The items in this page of results

Array of

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

Folder
Scenario
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

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"

Scenario: object

This object represents one scenario in the system. See the wider product documentation for an explanation of what a scenario is used for.

Properties

app:

The app that owns this scenario

created: string (date-time)

The datetime this scenario was created

id: string (uuid)

The ID of this scenario

Example: 
"003584bb-9e7b-eb70-ffca-7b446118b100"
name: string (1 to 255 chars) , must match ^[^\p{Cntrl}]*$ & ^\S(?:[\s\S]*\S)?$

The name of this scenario

Example: 
"My scenario"
objectType: string , one of { SCENARIO }
owner:

The user that owns this scenario

parent:

The parent of this scenario

path: string

The path within the repository

Example: 
"/app-name/folder-a/folder-b/scenario-a"
scenarioType: string

The scenario's custom type if it has one, otherwise SCENARIO.

Example: 
"SCENARIO"
shareStatus: string , one of { FULLACCESS , PRIVATE , READONLY }

The share status of this scenario

summary:

The summary of this scenario's data

url: string (uri)

The URL of this scenario

Example: 
"/api/scenarios/003584bb-9e7b-eb70-ffca-7b446118b100"

ScenarioSummary: object

This object is a container for a number of properties describing the state of a scenario, its data and the most recent job that executed it.

Properties

executionDuration: integer (int64)

The duration of the last execution of this scenario in milliseconds

Example: 
500
executionFinished: string

When this scenario last finished loading or executing

executionMode: string

The execution mode for the last execution

executionStarted: string

When this scenario last started loading or executing

executionUser:

The user that last executed this scenario

modelDataVersion: integer (int32)

The version number of the model data

Example: 
2
modelStatus: string , one of { BREAK , ERROR , EXIT , INSTR , IOERR , LICERR , MATHERR , NA , NIFCT , NULL , OK , PROB , STOP , UNKNOWN , UNKN_PF , UNKN_SYS }

The model status for this scenario

Example: 
"OK"
objective: number (double)

The objective result for this scenario

problemStatus: string , one of { INFEASIBLE , NA , OPTIMAL , OTHER , SOLUTION , UNBOUNDED , UNFINISHED , UNKNOWN }

The problem status for this scenario

Example: 
"SOLUTION"
reservedForJob: boolean

Whether the scenario is reserved for a job

Example: 
false
state: string , one of { LOADED , RESULTS , RESULTS_DIRTY , UNLOADED }

The current state of this scenario's data

Example: 
"LOADED"

Sort: object

Details of how paged results were sorted

Properties

empty: boolean

True if there are no results

Example: 
false
sorted: boolean

True if the results are sorted

Example: 
false
unsorted: boolean

True if the results are not sorted

Example: 
false
Parent Topic Insight 5 REST API

© 2001-2022 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.