Screendragon API Integration Use Cases - Matrices

Modified on Fri, 21 Nov at 12:35 PM

Fetch Matrix List
Retrieve Matrix Data
Retrieve Matrix Structure
Create a new version of Matrix
Update a row in Matrix
Ingest a batch of data values into Matrix
Soft-delete a Matrix
Deletes a specific row from a Matrix

Fetch Matrix List

Endpoint

GET /api/matrix

Description

This endpoint retrieves a list of metadata attribute matrices from the database. Supports optional filtering by matrix title. The response includes top-level matrices and their child matrices (if any), structured hierarchically.

Query Parameters

Name	Type	Required	Description
`filter`	`String`	❌	Optional filter to match matrix titles (partial match).

Error Handling

Status Code	Message
400	"No data."

Notes

Only matrices marked as deleted = 0 are returned.
Parent-child relationships are determined.
Requires user credentials to be extracted.

Sample Request

GET /api/matrix?filter=Risk

Authorization: Bearer <token>

Sample Response (Success)

[
  {
    "id": 1,
    "title": "Risk Matrix",
    "type": "Standard",
    "tags":  [
        {
         "name" : "risk",
         "value" : "compliance" 
         }
     ]
    "children": []
  },
...
]

Sample Response (Error)

{
  "error": "No data"
}

Retrieve Matrix Data

Endpoint

GET /api/matrix/data/{id}

Description

This endpoint retrieves the contents of a matrix based on the provided matrix ID. Optional parameters allow filtering by sheet name and version. The endpoint also validates user credentials before processing the request.

Query Parameters

Name	Type	Required	Description
`sheet`	`String`	❌	Optional sheet name to filter matrix data.
`version`	`String`	❌	Optional version identifier for the matrix.

Route Parameters

Name	Type	Required	Description
`id`	`Int32`	❌	Optional sheet name to filter matrix data.
`version`	`String`	❌	Optional version identifier for the matrix.

Error Handling

Status Code	Message
404	"Project not found."
400	"No Data."
500	"Internal Server Error."

Notes

The endpoint automatically includes access level, sub-projects, and layout information without requiring additional query parameters.
Ensure the bearer token is valid and has permission to view the specified project.

Sample Request

GET /api/matrix/data/101
Authorization: Bearer <token>

Sample Response (Success)

[
    {
    "id": 101,
    "typeID": 12,
    "name": "Website Redesign",
    "type": "Deliverable",
    "sheets": [
    {
     "name": "Default",
     "guid": "e44d166d-99fa",
      [
        "guid": "9df9881c-4d97",
        "values": [
        "inputs": [
        {
            "name": "Deliverable",
            "value": "Banner"
            },
            ...
        ]
        "outputs": [
        {
            "name": "Role",
            "value": "Project Manager"
            },
             ...
        ]
    ]]
}]
}]

Sample Response (Error)

{
  "error": "No data"
}

Retrieve Matrix Structure

Endpoint

GET /api/matrix/{id}

Description

This endpoint retrieves the matrix structure for a specified matrix ID. Requires user authentication and authorization. Returns the matrix object if found; otherwise, returns an error message.

Path Parameters

Name	Type	Required	Description
`id`	`Int32`	✅	Unique identifier of the matrix.

Error Handling

Status Code	Message
400	"No data."

Notes

Only authenticated users with appropriate access rights can invoke this endpoint successfully.
If the matrix structure cannot be retrieved, a generic error message is returned.

Sample Request

GET /api/matrix/123
Authorization: Bearer {token}

Sample Response (Success)

{
    "id": 471,
    "typeID": 18,
    "name": "NA Units",
    "structure": "matrix",
    "type": "Deliverable",
    "sheets": [
        {
            "name": "Default",
            "guid": "e44d166d-99fa",
            "inputs": [
                {
                    "guid": "58308cbc-dc1c",
                    "name": "Deliverable",
                    "identifier": false,
                    "sortOrder": 0,
                    "columnType": "deliverable"
                }, 
              ...
            ],
            "outputs": [
                {
                    "guid": "dbea5a1a-caa7",
                    "name": "Role",
                    "identifier": false,
                    "sortOrder": 3,
                    "columnType": "drole"
                },
                ...
            ]
        }
    ],
    "versions": [
        {
            "guid": "50a613c5-5545",
            "name": "Version 1",
            "disabled": false,
            "isDefault": false
        }
    ],
    "isDiscrete": true
}

Sample Response (Error)

{
  "error": "No data"
}

Create a new version of Matrix

Endpoint

POST /api/matrix/{id}/version

Description

This endpoint creates a new version for the specified matrix, ensures the version name is unique within the matrix and optionally sets the new version as the default. Supports specifying a parent version by GUID or by reference.

Path Parameters

Name	Type	Required	Description
`id`	`Int32`	✅	Unique identifier of the matrix.

Query Parameters

Name	Type	Required	Description
`name`	`String`	✅	Name for the new version. Must be unique within the matrix.
`parentVersion`	`String`	❌	GUID or reference to the parent version. If not provided, no parent is set.
`isDefault`	`Boolean`	❌	If true, sets the new version as the default. Defaults to false.

Error Handling

Status Code	Message
400	"Version name '{name}' is already in use."
400	"No such matrix with specified ID."
404	"No such version could be created."

Notes

Ensure the user has the correct permissions to create versions for the specified matrix.
The version name must be unique within the matrix.
If isDefault is true, the new version is set as the default and any existing default version is updated.
If parentVersion is provided, it must be a valid GUID or resolvable reference; otherwise, no parent is set.
If the matrix or version cannot be found or created, a descriptive error message is returned.

Sample Request

POST /api/matrix/123/version?name=Q3%20Release
&parentVersion=abc123-guid&isDefault=true
Authorization: Bearer {token}

Sample Response (Error)

{
  "error": "Version name 'Q3 Release' is already in use."
}

Update a row in Matrix

Endpoint

PUT /api/matrix/{id}/row

Description

This endpoint updates a single row in the specified matrix. Supports optional targeting of a sheet and version, and allows enabling the row, sorting by column type, and using identifiers for row matching.

Path Parameters

Name	Type	Required	Description
`id`	`Int32`	✅	Unique identifier of the matrix.

Query Parameters

Name	Type	Required	Description
`sheet`	`String`	❌	Name of the sheet to update.
`version`	`String`	❌	Version identifier to target.
`enableRow`	`Boolean`	❌	If true, enables the row after update. Defaults to false.
`sortByColumnType`	`String`	❌	Column type used for sorting. If empty, no sorting is applied.
`useIdentifier`	`String`	❌	If true, uses a unique identifier to locate the row. Defaults to false.

Body Parameters

Name	Type	Required	Description
`values`	`List<String>`	✅	List of string values representing the row to update.

Error Handling

Status Code	Message
400	"The row update operation failed"

Notes

Ensure the user has the correct permissions to update rows in the specified matrix.
The values parameter must be a list of strings representing the row data.
If sortByColumnType is provided, the matrix is updated using sorted logic; otherwise, a direct row edit is performed.
If useIdentifier is true, the row is matched using a unique identifier rather than position.
If the update fails, a descriptive error message is returned.

Sample Request

PUT /api/matrix/123/row?sheet=Financials&version=v1&enableRow=true&sortByColumnType=Date&useIdentifier=true
Content-Type: application/json
[
  "2025-09-01",
  "Revenue",
  "€1,000,000"
]

Sample Response (Error)

{
    "error": "Invalid row data or update failed"
  }

Ingest a batch of data values into Matrix

Endpoint

PUT /api/matrix/{id}

Description

This endpoint ingests a batch of matrix data values into the specified matrix. Optionally targets a specific sheet and version. The data is provided as a two-dimensional array of strings.

Path Parameters

Name	Type	Required	Description
`id`	`Int32`	✅	Unique identifier of the matrix.

Query Parameters

Name	Type	Required	Description
`sheet`	`String`	❌	Name of the sheet to update.
`version`	`String`	❌	Version identifier to target.

Body Parameters

Name	Type	Required	Description
`values`	`List<List<String>>`	✅	Two-dimensional array of string values to ingest.

Error Handling

Status Code	Message
400	"Ingest Failed {error details}."

Notes

Ensure the user has the correct permissions to ingest data for the specified matrix.
The values parameter must be a two-dimensional array of strings and is required.
If the ingest operation fails, a descriptive error message is returned.

Sample Request

POST /api/matrix/123?sheet=Financials&version=v1
Content-Type: application/json

[
  ["Header1", "Header2", "Header3"],
  ["Value1", "Value2", "Value3"],
  ["Value4", "Value5", "Value6"]
]

Sample Response (Error)

{
    "error": "Ingest Failed <error details>"
}

Soft-delete a Matrix

Endpoint

DELETE /api/matrix/{id}

Description

This endpoint marks the specified matrix as deleted by updating its metadata. The matrix is not physically removed from the database but is flagged as deleted and logged in MongoDB for audit purposes.

Path Parameters

Name	Type	Required	Description
`id`	`Int32`	✅	Unique identifier of the matrix.

Error Handling

Status Code	Message
400	"No such matrix with specified ID"

Notes

Ensure the user has the correct permissions to delete the specified matrix.
The matrix is soft-deleted by setting a deleted flag and recording metadata such as deletedById and deletedTime.
If the matrix ID is invalid or the operation fails, a descriptive error message is returned.

Sample Request

DELETE /api/matrix/123
Authorization: Bearer {token}

Sample Response (Error)

{
    "error": "No such matrix with specified ID"
}

Deletes a specific row from a Matrix

Endpoint

DELETE /api/matrix/{id}/row

Description

This endpoint deletes a single row from the specified matrix. Supports optional targeting of a sheet and version, and allows using a unique identifier to locate the row.

Path Parameters

Name	Type	Required	Description
`id`	`Int32`	✅	Unique identifier of the matrix.

Query Parameters

Name	Type	Required	Description
`sheet`	`String`	❌	Name of the sheet to delete the row from.
`version`	`String`	❌	Version identifier to target.
`useIdentifier`	`Boolean`	❌	If true, uses a unique identifier to locate the row. Defaults to false.

Body Parameters

Name	Type	Required	Description
`values`	`String`	❌	List of string values representing the row to delete.

Error Handling

Status Code	Message
400	"The row deletion operation failed"

Notes

Ensure the user has the correct permissions to delete rows from specified matrix.
The values parameter must be a list of strings representing the row data to delete.
If useIdentifier is true, the row is matched using a unique identifier rather than position.
If the deletion fails, a descriptive error message is returned.

Sample Request

DELETE /api/matrix/123/row?sheet=Financials&version=v1&useIdentifier=true
Content-Type: application/json

[
  "2025-09-01",
  "Revenue",
  "€1,000,000"
]

Sample Response (Error)

{
    "error": "Row deletion failed due to invalid data"
  }