Skip to main content
PATCH
Update a matrix column

Authorizations

​
Authorization
string
header
required

Workspace credential issued from the automation console at /automation. Send it as Authorization: Bearer vq_ws_.... This is NOT a Data API key: a vq_key_ credential is refused here and names the other product in the error.

Path Parameters

​
matterId
string
required

mat_ identifier of the matter to work inside. Everything in this API hangs off a matter, and the matter in the path is what the authorization boundary is checked against. Take it from GET /v1/matters.

​
matrixId
string
required

mtx_ identifier of the matrix. Take it from the matter's matrix list.

​
columnId
string
required

col_ identifier of one column of the matrix, which is one question asked of every document. Take it from the matrix's columns.

Body

application/json

Change one column, including whether it is conditional on another.

Changing question, columnType or options BLANKS every cell in this column. MatrixService.update_column bulk-resets them to pending with a null answer, no citations and no answer_data, which destroys a manually edited or approved answer and the verifier's verdict along with it. That is defensible in a browser where a human just typed the new question and is looking at the grid; it is not something a PATCH should do silently, which is why it is stated in each of those three field descriptions and not only here. A generated client shows the field description.

label and instructions do not reset anything: they change how the column reads and what guidance it carries, not what was asked.

​
label
string | null

New column heading. Resets nothing.

Required string length: 1 - 200
Example:

"Liability cap"

​
question
string | null

New question for this column. WARNING: changing it clears every existing answer in this column, including answers a human wrote or approved and any verification verdict on them, and leaves the cells unanswered until the next run.

Required string length: 1 - 4000
Example:

"What is the liability cap, and what does it apply to?"

​
columnType
enum<string> | null

New answer shape: free_text, single_select, date, money, yes_no or party_name. WARNING: changing it clears every existing answer in this column, as changing the question does.

Available options:
free_text,
single_select,
date,
money,
yes_no,
party_name
Example:

"free_text"

​
options
string[] | null

New allowed answers for a single_select column. WARNING: changing them clears every existing answer in this column, as changing the question does.

Example:
​
instructions
string | null

New extractor guidance scoped to this column. Resets nothing.

Maximum string length: 4000
Example:

"House paper. Cap liability at 12 months of fees; never accept uncapped indemnity."

​
dependsOnColumnId
string | null

col_ identifier of a column in this same matrix that this one becomes conditional on, or null to make it unconditional again. A cycle is refused.

Example:

"col_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"

​
gateExpression
string | null

The condition on the upstream answer that has to hold for this column to run, or null to run whenever the dependency has answered. One of any, not_empty, yes, no, yes_no:yes, yes_no:no, equals:VALUE or in:A|B|C. Anything else is refused: an expression we cannot parse would mark every cell in the column as deliberately skipped with no error anywhere. yes, no and equals: match the WHOLE upstream answer, not part of it, so they belong on a yes_no or single_select upstream column; over a free_text one, use not_empty.

Maximum string length: 500
Pattern: ^(any|not_empty|yes|no|yes_no:(?:yes|no)|equals:.+|in:.+)$
Example:

"yes"

​
injectUpstream
boolean | null

True prepends the upstream column's answer to this column's prompt, so the question can refer to it. False asks the question on its own.

Example:

false

Response

Successful Response

The grid header plus its axes. Cells are a separate, paged read.

Rows and columns are inlined because they are bounded and because a cell is unreadable without them: a cell names a row id and a column id and nothing else, so a client that could not resolve those would have to page the whole grid to interpret one answer.

​
id
string
required

Public identifier, mtx_ followed by 32 hex characters.

Example:

"mtx_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"

​
matterId
string
required

mat_ identifier of the matter this matrix belongs to.

Example:

"mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"

​
title
string
required

Display title for the matrix.

Example:

"Vendor agreement review"

​
status
enum<string>
required

Matrix status, using the same five public values as an operation.

Available options:
queued,
running,
succeeded,
failed,
cancelled
Example:

"succeeded"

​
createdAt
string<date-time>
required

When the matrix was created (RFC 3339).

Example:

"2026-08-19T14:32:10Z"

​
updatedAt
string<date-time>
required

When the matrix was last updated (RFC 3339).

Example:

"2026-08-19T14:32:10Z"

​
description
string | null

Free-text description of what the matrix is for.

Example:

"Master services agreement with Acme for the 2026 platform rollout."

​
columns
MatrixColumn · object[]

Every column, inlined. A cell names only ids, so these are what make one readable.

​
rows
MatrixRow · object[]

Every row, inlined, one per document.

​
cellCount
integer
default:0

Total cells in the grid, which is rows times columns.

Example:

24

​
pendingCellCount
integer
default:0

Cells that have not produced an answer yet. Zero means extraction is complete.

Example:

0

​
errorCellCount
integer
default:0

Cells whose extraction failed. These are distinct from cells that succeeded with a null answer.

Example:

0

Last modified on August 23, 2026