curl --request PATCH \
--url https://api.vaquill.ai/workspace/v1/matters/{matterId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Acme / Series B Financing",
"clientId": "cli_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
"description": "Master services agreement with Acme for the 2026 platform rollout.",
"instructions": "House paper. Cap liability at 12 months of fees; never accept uncapped indemnity.",
"status": "open",
"practiceArea": "commercial",
"matterType": "financing",
"caseNumber": "2026-CV-0117",
"responsibleAttorneyName": "Dana Whitfield",
"openDate": "2026-08-19",
"closeDate": "2026-08-19",
"billingType": "hourly",
"billingRate": "450.00",
"billingCurrency": "USD",
"country": "US",
"metadata": {
"externalId": "CRM-4471"
}
}
'import requests
url = "https://api.vaquill.ai/workspace/v1/matters/{matterId}"
payload = {
"name": "Acme / Series B Financing",
"clientId": "cli_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
"description": "Master services agreement with Acme for the 2026 platform rollout.",
"instructions": "House paper. Cap liability at 12 months of fees; never accept uncapped indemnity.",
"status": "open",
"practiceArea": "commercial",
"matterType": "financing",
"caseNumber": "2026-CV-0117",
"responsibleAttorneyName": "Dana Whitfield",
"openDate": "2026-08-19",
"closeDate": "2026-08-19",
"billingType": "hourly",
"billingRate": "450.00",
"billingCurrency": "USD",
"country": "US",
"metadata": { "externalId": "CRM-4471" }
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'Acme / Series B Financing',
clientId: 'cli_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6',
description: 'Master services agreement with Acme for the 2026 platform rollout.',
instructions: 'House paper. Cap liability at 12 months of fees; never accept uncapped indemnity.',
status: 'open',
practiceArea: 'commercial',
matterType: 'financing',
caseNumber: '2026-CV-0117',
responsibleAttorneyName: 'Dana Whitfield',
openDate: '2026-08-19',
closeDate: '2026-08-19',
billingType: 'hourly',
billingRate: '450.00',
billingCurrency: 'USD',
country: 'US',
metadata: {externalId: 'CRM-4471'}
})
};
fetch('https://api.vaquill.ai/workspace/v1/matters/{matterId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.vaquill.ai/workspace/v1/matters/{matterId}"
payload := strings.NewReader("{\n \"name\": \"Acme / Series B Financing\",\n \"clientId\": \"cli_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6\",\n \"description\": \"Master services agreement with Acme for the 2026 platform rollout.\",\n \"instructions\": \"House paper. Cap liability at 12 months of fees; never accept uncapped indemnity.\",\n \"status\": \"open\",\n \"practiceArea\": \"commercial\",\n \"matterType\": \"financing\",\n \"caseNumber\": \"2026-CV-0117\",\n \"responsibleAttorneyName\": \"Dana Whitfield\",\n \"openDate\": \"2026-08-19\",\n \"closeDate\": \"2026-08-19\",\n \"billingType\": \"hourly\",\n \"billingRate\": \"450.00\",\n \"billingCurrency\": \"USD\",\n \"country\": \"US\",\n \"metadata\": {\n \"externalId\": \"CRM-4471\"\n }\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"id": "mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
"name": "Acme / Series B Financing",
"clientId": "cli_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
"description": "Master services agreement with Acme for the 2026 platform rollout.",
"instructions": "House paper. Cap liability at 12 months of fees; never accept uncapped indemnity.",
"status": "open",
"practiceArea": "commercial",
"matterType": "financing",
"caseNumber": "2026-CV-0117",
"responsibleAttorneyName": "Dana Whitfield",
"openDate": "2026-08-19",
"closeDate": "2026-08-19",
"billingType": "hourly",
"billingRate": "450.00",
"billingCurrency": "USD",
"country": "US",
"metadata": {
"externalId": "CRM-4471"
},
"isDefault": false,
"createdAt": "2026-08-19T14:32:10Z",
"updatedAt": "2026-08-19T14:32:10Z"
}{
"type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
"title": "Insufficient scope",
"status": 403,
"detail": "This credential carries matters:read. This operation needs matters:write.",
"instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
"requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}{
"type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
"title": "Insufficient scope",
"status": 403,
"detail": "This credential carries matters:read. This operation needs matters:write.",
"instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
"requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}{
"type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
"title": "Insufficient scope",
"status": 403,
"detail": "This credential carries matters:read. This operation needs matters:write.",
"instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
"requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}{
"type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
"title": "Insufficient scope",
"status": 403,
"detail": "This credential carries matters:read. This operation needs matters:write.",
"instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
"errors": [
{
"location": "<string>",
"message": "<string>",
"type": "<string>"
}
],
"requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}{
"type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
"title": "Insufficient scope",
"status": 403,
"detail": "This credential carries matters:read. This operation needs matters:write.",
"instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
"requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}{
"type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
"title": "Insufficient scope",
"status": 403,
"detail": "This credential carries matters:read. This operation needs matters:write.",
"instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
"requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}{
"type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
"title": "Insufficient scope",
"status": 403,
"detail": "This credential carries matters:read. This operation needs matters:write.",
"instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
"requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}Update a matter
Apply a partial update to a matter.
Omitted fields are left alone; an explicit null clears the field, except
name, which cannot be nulled. Setting closeDate does not change
status: the two are independent, so close the matter explicitly if that is
what you mean.
curl --request PATCH \
--url https://api.vaquill.ai/workspace/v1/matters/{matterId} \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"name": "Acme / Series B Financing",
"clientId": "cli_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
"description": "Master services agreement with Acme for the 2026 platform rollout.",
"instructions": "House paper. Cap liability at 12 months of fees; never accept uncapped indemnity.",
"status": "open",
"practiceArea": "commercial",
"matterType": "financing",
"caseNumber": "2026-CV-0117",
"responsibleAttorneyName": "Dana Whitfield",
"openDate": "2026-08-19",
"closeDate": "2026-08-19",
"billingType": "hourly",
"billingRate": "450.00",
"billingCurrency": "USD",
"country": "US",
"metadata": {
"externalId": "CRM-4471"
}
}
'import requests
url = "https://api.vaquill.ai/workspace/v1/matters/{matterId}"
payload = {
"name": "Acme / Series B Financing",
"clientId": "cli_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
"description": "Master services agreement with Acme for the 2026 platform rollout.",
"instructions": "House paper. Cap liability at 12 months of fees; never accept uncapped indemnity.",
"status": "open",
"practiceArea": "commercial",
"matterType": "financing",
"caseNumber": "2026-CV-0117",
"responsibleAttorneyName": "Dana Whitfield",
"openDate": "2026-08-19",
"closeDate": "2026-08-19",
"billingType": "hourly",
"billingRate": "450.00",
"billingCurrency": "USD",
"country": "US",
"metadata": { "externalId": "CRM-4471" }
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}
response = requests.patch(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'PATCH',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
name: 'Acme / Series B Financing',
clientId: 'cli_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6',
description: 'Master services agreement with Acme for the 2026 platform rollout.',
instructions: 'House paper. Cap liability at 12 months of fees; never accept uncapped indemnity.',
status: 'open',
practiceArea: 'commercial',
matterType: 'financing',
caseNumber: '2026-CV-0117',
responsibleAttorneyName: 'Dana Whitfield',
openDate: '2026-08-19',
closeDate: '2026-08-19',
billingType: 'hourly',
billingRate: '450.00',
billingCurrency: 'USD',
country: 'US',
metadata: {externalId: 'CRM-4471'}
})
};
fetch('https://api.vaquill.ai/workspace/v1/matters/{matterId}', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://api.vaquill.ai/workspace/v1/matters/{matterId}"
payload := strings.NewReader("{\n \"name\": \"Acme / Series B Financing\",\n \"clientId\": \"cli_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6\",\n \"description\": \"Master services agreement with Acme for the 2026 platform rollout.\",\n \"instructions\": \"House paper. Cap liability at 12 months of fees; never accept uncapped indemnity.\",\n \"status\": \"open\",\n \"practiceArea\": \"commercial\",\n \"matterType\": \"financing\",\n \"caseNumber\": \"2026-CV-0117\",\n \"responsibleAttorneyName\": \"Dana Whitfield\",\n \"openDate\": \"2026-08-19\",\n \"closeDate\": \"2026-08-19\",\n \"billingType\": \"hourly\",\n \"billingRate\": \"450.00\",\n \"billingCurrency\": \"USD\",\n \"country\": \"US\",\n \"metadata\": {\n \"externalId\": \"CRM-4471\"\n }\n}")
req, _ := http.NewRequest("PATCH", url, payload)
req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}{
"id": "mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
"name": "Acme / Series B Financing",
"clientId": "cli_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
"description": "Master services agreement with Acme for the 2026 platform rollout.",
"instructions": "House paper. Cap liability at 12 months of fees; never accept uncapped indemnity.",
"status": "open",
"practiceArea": "commercial",
"matterType": "financing",
"caseNumber": "2026-CV-0117",
"responsibleAttorneyName": "Dana Whitfield",
"openDate": "2026-08-19",
"closeDate": "2026-08-19",
"billingType": "hourly",
"billingRate": "450.00",
"billingCurrency": "USD",
"country": "US",
"metadata": {
"externalId": "CRM-4471"
},
"isDefault": false,
"createdAt": "2026-08-19T14:32:10Z",
"updatedAt": "2026-08-19T14:32:10Z"
}{
"type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
"title": "Insufficient scope",
"status": 403,
"detail": "This credential carries matters:read. This operation needs matters:write.",
"instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
"requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}{
"type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
"title": "Insufficient scope",
"status": 403,
"detail": "This credential carries matters:read. This operation needs matters:write.",
"instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
"requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}{
"type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
"title": "Insufficient scope",
"status": 403,
"detail": "This credential carries matters:read. This operation needs matters:write.",
"instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
"requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}{
"type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
"title": "Insufficient scope",
"status": 403,
"detail": "This credential carries matters:read. This operation needs matters:write.",
"instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
"errors": [
{
"location": "<string>",
"message": "<string>",
"type": "<string>"
}
],
"requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}{
"type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
"title": "Insufficient scope",
"status": 403,
"detail": "This credential carries matters:read. This operation needs matters:write.",
"instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
"requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}{
"type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
"title": "Insufficient scope",
"status": 403,
"detail": "This credential carries matters:read. This operation needs matters:write.",
"instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
"requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}{
"type": "https://vaquill.ai/docs/workspace-api/errors/insufficient-scope",
"title": "Insufficient scope",
"status": 403,
"detail": "This credential carries matters:read. This operation needs matters:write.",
"instance": "/workspace/v1/matters/mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6",
"requestId": "req_5f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
}Authorizations
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
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.
Body
A partial update. Absent leaves alone; explicit null clears.
New display name. Cannot be set to null; omit it to leave the name alone.
1 - 100"Acme / Series B Financing"
cli_ identifier to refile the matter under, or null to unfile it. Must belong to your organization.
"cli_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
New description, or null to clear it.
5000"Master services agreement with Acme for the 2026 platform rollout."
New standing instructions, or null to clear them.
10000"House paper. Cap liability at 12 months of fees; never accept uncapped indemnity."
New lifecycle status, or null to clear it.
open, pending, closed "open"
New practice area, or null to clear it.
100"commercial"
New matter type, or null to clear it.
50"financing"
New case reference, or null to clear it.
100"2026-CV-0117"
New responsible attorney name, or null to clear it.
255"Dana Whitfield"
New open date, or null to clear it.
"2026-08-19"
New close date, or null to clear it. Setting one does not change status.
"2026-08-19"
New billing arrangement, or null to clear it.
hourly, flat_fee, contingency, pro_bono "hourly"
New billing rate, or null to clear it.
x >= 0"450.00"
New ISO 4217 currency code, or null to clear it.
^[A-Z]{3}$"USD"
New ISO 3166-1 alpha-2 country code, or null to clear it.
^[A-Z]{2}$"US"
Replacement metadata object, or null to clear it. Not merged with what is stored.
Response
Successful Response
A matter as this API publishes it.
Public identifier, mat_ followed by 32 hex characters. This is the value that goes in every matter-nested path.
"mat_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
The matter's display name.
"Acme / Series B Financing"
cli_ identifier of the client this matter belongs to, if one was set.
"cli_9f2c8b1e4a7d43c9b6e0f1a2c3d4e5f6"
Free-text description of the matter.
"Master services agreement with Acme for the 2026 platform rollout."
Standing instructions the customer wants applied to AI work on this matter. Carried into drafting and review prompts.
"House paper. Cap liability at 12 months of fees; never accept uncapped indemnity."
Lifecycle status. Usually open, pending or closed, but published as a plain string because production holds values no UI offers. Do not branch on it without a fallback.
"open"
Practice area, for example employment or real_estate. Free text.
"commercial"
Customer's own sub-classification of the matter. Free text.
"financing"
Docket or internal case reference.
"2026-CV-0117"
Name of the attorney responsible for the matter. The underlying user id is deliberately not published.
"Dana Whitfield"
Date the matter opened (YYYY-MM-DD).
"2026-08-19"
Date the matter closed (YYYY-MM-DD). Absent while it is open.
"2026-08-19"
Billing arrangement, normally one of hourly, flat_fee, contingency or pro_bono. Published as a plain string.
"hourly"
Billing rate in billingCurrency. Rendered as a JSON STRING, not a number, so the value stays exact.
^(?!^[-+.]*$)[+-]?0*\d*\.?\d*$"450.00"
ISO 4217 currency code for billingRate, for example USD.
"USD"
ISO 3166-1 alpha-2 country code, for example US. Unlike a client's country, this is a validated code.
"US"
Arbitrary JSON the customer stores against the matter. Vaquill never reads it.
True for the one matter minted at signup that unfiled work lands in. Read-only: exactly one exists per organization and this API cannot create or move it.
false
When the matter was created (RFC 3339).
"2026-08-19T14:32:10Z"
When the matter was last modified (RFC 3339).
"2026-08-19T14:32:10Z"
Was this page helpful?