Xpress-Insight projects are the primary entry point into the data model and are available through this resource.

The following resources are part of this group:

• /v1/data/project
• /v1/data/project/{id}
• /v1/data/project/{id}/attachments
• /v1/data/project/{id}/children
• /v1/data/project/{id}/folder
• /v1/data/project/{id}/modelschema
• /v1/data/project/{id}/publish-workbook-form
• /v1/data/project/{id}/scenario
• /v1/data/project/{id}/users
• /v1/data/project/{id}/views
• /v1/data/project/{id}/workbooks
• /v1/data/project/{id}/attachments/data
• /v1/data/project/{id}/attachments/new
• /v1/data/project/{id}/attachments/tags
• /v1/data/project/{id}/attachments/trash
• /v1/data/project/{id}/attachments/{attachmentId}
• /v1/data/project/{id}/publish-workbook/{workbook-name}
• /v1/data/project/{id}/attachments/{attachmentId}/data
• /v1/data/project/{id}/attachments/{attachmentId}/editor
• /v1/data/project/{id}/attachments/{attachmentId}/editor/{editorId}
• /v1/data/project/{id}/views/{workbookId}/{viewId}/tableau
• /v1/data/project/{id}/attachments/{attachmentId}/editor/{editorId}/command/{commandId}
• /v1/data/project/{id}/attachments/{attachmentId}/editor/{editorId}/command/{commandType}

/v1/data/project

The following operations are supported on this resource:

• GET
• POST
• POST

GET

Lists the available projects.

Parameters

name	description	type	default
start	Start at this position in the list	query	0
maxResults	The maximum number of items to return	query	50

Response Body

element:	webServiceBeanList
media types:	application/json

A paginated list of references to projects.

POST

Imports projects into the repository from a project export (.insight) file.

Request Body

element:	(custom)
media types:	application/octet-stream

A project export file ending in .insight

Response Body

element:	projectImportResult
media types:	application/json

An object holding a list of references to the imported projects and informational messages

POST

Imports projects into the repository from a project export (.insight) file or zip file. This method is typically invoked from an HTML form.

Response codes indicate the following:

• 200 OK: Check the returned JSON object for the status of the operation

Parameters

name	description	type	default
Content-Length	The approximate length of the project file being posted	header

Request Body

element:	(custom)
media types:	multipart/form-data

A multipart form with the following fields:

• project-file: The project file data to upload
• project-file-format: The format of the project file data (ZIP or INSIGHT)
• project-name: The name of the new project (only applies to zip files; can be overridden in the companion file)

Response Body

element:	projectImportFormResult
media types:	text/plain

An object holding a status, a list of references to the imported projects and informational messages

/v1/data/project/{id}

The following operations are supported on this resource:

• GET
• POST
• POST
• DELETE

GET

Reads a project.

Parameters

name	description	type	default
id	The id of the project	path

Response Body

element:	project
media types:	application/json

The project, or 404 Not Found if the project could not be found.

POST

Updates a project.

Currently only Project#getDisplayName() and Project#getNotes() can be updated. If an updatable property is null, it will not be updated. The value of the projectId parameter must match the value of Project#getId().

Parameters

name	description	type	default
id	the id of the project to update	path

Request Body

element:	project
media types:	application/json

the updates to apply to the project

Response Body

element:	project
media types:	application/json

An Project in response 200 OK if successful, or 404 Not Found if the project could not be found.

POST

Updates a project.

The request body should be a multipart form with a field named project-file containing a project zip file. The zip file may contain:

• The model companion file
• The compiled BIM file
• Updated model resources
• Updated client resources
• Managed Tableau workbooks

Any resource which is present in the zip file will replace the existing resource on the project. Other existing resources on the project will be unaffected.

This operation always returns 200 OK. The real status code for the operation is held in the status field of the returned JSON object. This embedded status may be one of:

• 200 OK: Check the messages field for any warning messages.
• 400 Bad Request: The project-file field did not contain a valid project zip file.
• 403 Forbidden: You do not have permission to modify the project.
• 404 Not Found: The project does not exist, or you do not have permission to view it.

Parameters

name	description	type	default
id	the id of the project to update	path
bypassModelNameValidation	(no documentation provided)	query	false

Response Body

element:	projectUpdateResult
media types:	text/plain

a ProjectUpdateResult indicating the result of the update

DELETE

Deletes an Insight project.

Response codes indicate the following:

• 204 No content: Operation successful
• 404 Not found: The project could not be found
• 423 Status locked: The project could not be delete

Parameters

name	description	type	default
id	the id of the project to delete	path

Response Body

element:	messages
media types:	application/json

Workbook feedback associated with this project, 204 No content, 404 Not found or 423 Status locked.

/v1/data/project/{id}/attachments

GET

Gets the list of attachments for a project.

Response codes indicate the following:

• 200 OK: The response contains the list of attachments.
• 404 Not Found: The project could not be found, or you do not have read access.

Parameters

name	description	type	default
id	The id of the project.	path
start	The starting index for pagination.	query	0
maxResults	The page size for pagination.	query	1000

Response Body

element:	webServiceBeanList
media types:	application/json

A WebServiceBeanList object with items set to an array of Attachment objects. The array will be empty if there are no attachments.

POST

Creates a file attachment on the project. Accepts a multi-part form submission with a single parameter, 'attachment', containing a file attachment. The response is an Attachment object containing the metadata for the successfully uploaded attachment, or if the upload was unsuccessful, an AttachmentError object describing the error.

If an attachment already exists with the same name as the new attachment, the behaviour is determined by the overwrite parameter: if true, the existing attachment will be overwritten by the new one; if false, the new attachment will be renamed to avoid the conflict.

Response codes indicate the following:

• 200 OK: Check JSON object to see whether the upload was successful

Parameters

name	description	type	default
id	The id of the project	path
overwrite	Whether to overwrite an existing attachment with the same name	query	false
tagName	A valid tag to apply to the attachment at upload time	query

Response Body

element:	attachment
media types:	text/plain

The metadata of the new attachment or an object describing the error

/v1/data/project/{id}/children

GET

Lists the children (folder items/refs) of a project.

Response codes indicate the following:

• 200 OK: Operation successful
• 400 Bad Request: One or more of the provided parameters are invalid
• 404 Not found: The project could not be found
• 403 Forbidden: The user does not have authorit to access the project and/or the VSG

Parameters

name	description	type	default
id	The id of the project	path
start	Start at this position in the list	query	0
maxResults	The maximum number of items to return	query	50

Response Body

element:	webServiceBeanList
media types:	application/json

A paginated list of references

POST

Move a given Folder or Scenario to the root of the project.

The response code indicates the following:

• 200 OK: folder or scenario successfully moved
• 403 Forbidden: insufficient rights to move the folder or scenario
• 404 Not Found: the folder or scenario does not exist
• 409 Conflict: the destination path, if specified, does not match this project's path

Parameters

name	description	type	default
id	the id of the project to update	path
destinationPath	the path of the destination project	query

Request Body

element:	reference
media types:	application/json

the folder or scenario to move

Response Body

element:	(custom)
media types:	application/json

the current folder or scenario data

/v1/data/project/{id}/folder

GET

Lists the folders within a project.

Parameters

name	description	type	default
id	The id of the project	path
start	Start at this position in the list	query	0
maxResults	The maximum number of items to return	query	50

Response Body

element:	webServiceBeanList
media types:	application/json

A paginated list of references to folders.

/v1/data/project/{id}/modelschema

GET

Reads a project's modelSchema.

Parameters

name	description	type	default
id	The id of the project	path

Response Body

element:	modelSchema
media types:	application/json

The modelSchema, or 404 Not Found if the project could not be found or the project has no modelSchema.

/v1/data/project/{id}/publish-workbook-form

POST

Publishes the provided workbook to Tableau.

Response codes indicate the following:

• 200 OK: Operation successful. With the response an entity is placed that provides the response.

Parameters

name	description	type	default
id	id of the project the workbook is associated with	path
Content-Length	length of the content sent up from the server	header

Request Body

element:	(custom)
media types:	multipart/form-data

workbook upload form

Response Body

element:	(custom)
media types:	text/plain

response to the publishing of the workbook

/v1/data/project/{id}/scenario

GET

Lists the scenarios within a project.

Parameters

name	description	type	default
id	The id of the project	path
start	Start at this position in the list	query	0
maxResults	The maximum number of items to return	query	50

Response Body

element:	webServiceBeanList
media types:	application/json

A paginated list of references to scenarios.

/v1/data/project/{id}/users

GET

Lists all users associated with the project.

Parameters

name	description	type	default
id	The id of the project	path
start	Start at this position in the list	query	0
maxResults	The maximum number of items to return	query	50

Response Body

element:	webServiceBeanList
media types:	application/json

A paginated list of references to users

/v1/data/project/{id}/views

GET

List browser type views from the project's companion file.

Each item in the return list corresponds to a View.

Response codes indicate the following:

• 200 OK: Operation successful
• 404 Not Found: The project could not be found

Parameters

name	description	type	default
id	The id of the project	path
start	Start at this position in the list	query	0
maxResults	The maximum number of items to return	query	50

Response Body

element:	webServiceBeanList
media types:	application/json

A paginated list of references to browser type views.

/v1/data/project/{id}/workbooks

GET

Lists workbooks associated with the project defined in the companion file.

Parameters

name	description	type	default
id	The id of the project	path
includeUnmanaged	True to include unmanaged workbooks, false to exclude them	query	false
extendedProperties	True to fetch additional information from tableau, false to skip this.	query	false
start	Start at this position in the list	query	0
maxResults	The maximum number of items to return	query	50

Response Body

element:	webServiceBeanList
media types:	application/json

A paginated list of references to the workbooks

/v1/data/project/{id}/attachments/data

POST

Downloads a zip file containing the given file attachments.

Response codes indicate the following:

• 200 OK: The response contains the attachment data
• 404 Not found: The project or attachment could not be found, or you do not have read access

Parameters

name	description	type	default
id	The id of the project	path
attachmentIds	The attachment ids to download, encoded as a JSON array of strings	form

Response Body

element:	(custom)
media types:	application/octet-stream

The data stream

/v1/data/project/{id}/attachments/new

POST

Creates an attachment for a given editor, optionally including data from an editor to specify content.

Note that this has undergone a compatibility-breaking change in Insight version 4.10.1: prior to that, the data was POSTed as a multipart form, rather than as JSON.

Parameters

name	description	type	default
id	(no documentation provided)	path

Request Body

element:	attachmentWithEditorData
media types:	application/json

Details of attachment and editor

Response Body

element:	attachment
media types:	application/json

The new attachment as an Attachment, or a AttachmentError if an error occurs.

/v1/data/project/{id}/attachments/tags

GET

Gets the list of attachment tags for a project.

Parameters

name	description	type	default
id	The id of the project.	path
maxResults	(no documentation provided)	query	1000

Response Body

element:	webServiceBeanList
media types:	application/json

A WebServiceBeanList object with items set to an array of com.fico.xpress.insight.resources.schema.AttachmentTag objects.

/v1/data/project/{id}/attachments/trash

POST

Delete multiple attachments by their UUID's.

Parameters

name	description	type	default
id	The project containing the UUID's to delete	path

Request Body

element:	(custom)
media types:	application/json

an array of UUID's to delete

Response Body

element:	(custom)
media types:	application/json

A AttachmentsDeleteResponse object containing the status of the delete operation for the various attachments.

/v1/data/project/{id}/attachments/{attachmentId}

The following operations are supported on this resource:

• GET
• DELETE
• POST

GET

Get an attachment.

Parameters

name	description	type	default
id	The id of the related scenario.	path
attachmentId	The id of the attachment to get.	path

Response Body

element:	(custom)
media types:	application/json

A WebServiceBean object.

DELETE

Deletes an attachment.

Parameters

name	description	type	default
id	The id of the related project.	path
attachmentId	The id of the attachment to delete.	path

Response Body

element:	(custom)
media types:	application/json

No content

POST

Update the attachment metadata by providing a new attachment with the updated fields, currently filename and description.

• 200 OK: The response contains the attachment data.
• 400 Bad Request: The updated filename was invalid.
• 403 Forbidden: You do not have permission to modify project attachments.
• 404 Not Found: The project or attachment does not exist, or you do not have permission to view it.

Parameters

name	description	type	default
id	The id of the project.	path
attachmentId	The id of the attachment to update.	path

Request Body

element:	attachment
media types:	application/json

An Attachment object holding the fields with the updated data.

Response Body

element:	attachment
media types:	application/json

The updated attachment data.

/v1/data/project/{id}/publish-workbook/{workbook-name}

POST

Publishes the provided workbook to Tableau.

Response codes indicate the following:

• 200 OK: Operation successful
• 403 Forbidden: The user does not have access or rights to perform the operation
• 404 Not Found: The project could not be found
• 500 Internal server Error: An error has occurred whilst trying to integrate or upload the workbook to the Tableau Server

Parameters

name	description	type	default
id	id of the project the workbook is associated with	path
workbook-name	name of the workbook	path

Request Body

element:	(custom)
media types:	application/octet-stream

input steam of the workbook

Response Body

element:	(custom)
media types:	application/json

response to the publishing of the workbook

/v1/data/project/{id}/attachments/{attachmentId}/data

GET

Downloads the binary data for the given file attachment.

Response codes indicate the following:

• 200 OK: The response contains the attachment data
• 404 Not found: The project, scenario or attachment could not be found, or you do not have read access

Parameters

name	description	type	default
id	The id of the project	path
attachmentId	The id of the attachment	path

Response Body

element:	(custom)
media types:	application/octet-stream

The data stream

/v1/data/project/{id}/attachments/{attachmentId}/editor

GET

Begins a new attachment editor for the specified attachment, using the default editor Response codes indicate the following:

• 200 OK: The response contains the editor info
• 404 Not found: The project or attachment could not be found, or you do not have read access, or no editor found

Parameters

name	description	type	default
id	The id of the project to which the attachment belongs	path
attachmentId	The id of the attachment to edit	path

Response Body

element:	(custom)
media types:	application/json

Response containing editor specific properties which the view should use to display the editor

/v1/data/project/{id}/attachments/{attachmentId}/editor/{editorId}

GET

Begins a new attachment editor for the specified attachment Response codes indicate the following:

• 200 OK: The response contains the editor info
• 404 Not found: The project or attachment could not be found, or you do not have read access, or no editor found

Parameters

name	description	type	default
id	The id of the project to which the attachment belongs	path
attachmentId	The id of the attachment to edit	path
editorId	The id of the editor	path

Response Body

element:	(custom)
media types:	application/json

Response containing editor specific properties which the view should use to display the editor

POST

Parameters

name	description	type	default
id	(no documentation provided)	path
attachmentId	(no documentation provided)	path
editorId	(no documentation provided)	path

Request Body

element:	(custom)
media types:	application/json

(no documentation provided)

Response Body

element:	(custom)
media types:	application/json

(no documentation provided)

/v1/data/project/{id}/views/{workbookId}/{viewId}/tableau

POST

Gets the tableau view.

Response codes indicate the following:

• 200 OK: Operation successful
• 403 Forbidden: The user does not have access or rights to the view
• 404 Not Found: The project could not be found
• 500 Internal server Error: An error has occurred whilst trying to integrate with the Tableau Server

Parameters

name	description	type	default
id	The id of the project	path
workbookId	Id of the Tableau workbook	path
viewId	Id of the Tableau view in the workbook	path

Response Body

element:	(custom)
media types:	application/json

Tableau viz properties

/v1/data/project/{id}/attachments/{attachmentId}/editor/{editorId}/command/{commandId}

GET

Parameters

name	description	type	default
id	(no documentation provided)	path
attachmentId	(no documentation provided)	path
editorId	(no documentation provided)	path
commandId	(no documentation provided)	path

Response Body

element:	(custom)
media types:	*

(no documentation provided)

/v1/data/project/{id}/attachments/{attachmentId}/editor/{editorId}/command/{commandType}

POST

Parameters

name	description	type	default
id	(no documentation provided)	path
attachmentId	(no documentation provided)	path
editorId	(no documentation provided)	path
commandType	(no documentation provided)	path

Request Body

element:	(custom)
media types:	application/json

(no documentation provided)

Response Body

element:	(custom)
media types:	*

(no documentation provided)