Matters

What a matter is

A matter is the case or file a firm bills its work against. If your product serves law firms, matters let a firm answer one question for every dollar of AI cost: which case does this belong to? Once usage is tied to matters, a firm can pull a per-matter cost record it can hand a client or an auditor. Anything no matter claims stays visible in an Unassigned bucket, so nothing gets lost. You can manage matters on the Law tab in the dashboard, from your own code with the endpoints below, or in plain English through the MCP tools. All three do the same work against the same numbers.

How usage attaches to a matter

Every usage event lands on at most one matter. There are three ways it can get there, and when more than one applies, the strongest wins:

Manual assignment (strongest). Someone puts the event on a matter by hand, in the dashboard or through the assign endpoint below. A manual choice always wins, and it’s never overwritten by tags or rules later.
A tag on the event. When you record a usage event, add the matter’s own case number as metadata.matterId. If a matter with that exact number exists, the event attaches to it. The tag is matched against the matter’s number (the matterNumber you set), not its UUID.
A routing rule (weakest). A rule says “events for this agent code, this customer, or this signal go to this matter.” Rules fill in the events you didn’t tag.

If none of the three apply, the event stays Unassigned until you assign it or a rule sweeps it up.

Tagging at record time is the cleanest path. When your agent already knows the case it’s working on, send metadata.matterId with the usage event (see Usage Events). The event lands on the right matter the moment it’s recorded, with nothing to clean up later. An unknown tag is never dropped and never creates a matter on its own. The event simply falls through to the rules, and to Unassigned if no rule matches.

Actual cost, never an estimate

Every cost figure on a matter is the sum of that matter’s real usage-event costs. It’s never a guess. When an event’s cost isn’t resolved yet (its model isn’t in the pricing table), that event adds 0 to the total and is counted separately in an eventsMissingCost field. A nonzero eventsMissingCost means the true cost is higher than the number shown, and it tells you exactly how many events to fix first. See Usage Events for how to resolve an unpriced model.

Who can manage matters

Every endpoint on this page needs a secret key that belongs to an owner, admin, finance, or legal user. Any other key gets a 403 Forbidden naming the role it needs. A publishable key (mf_pk_...) is refused.

The legal key

A legal key is a secret key scoped for exactly this surface, so a firm can hand it to its own agent without handing over the books. An owner or admin mints one under Build → API keys. A legal key can reach:

Every endpoint on this page.
The usage-recording surface: record events, /v1/verify, its own key info, and read-only Spend Controls.

Everything else answers 403 Forbidden: customers, invoices, usage events, analytics, pricing, and portal sessions. That limit is always on and enforced on the server.

Matters

List matters

GET /v1/matters

Returns your matters, each with its all-time actual AI cost and event count.

Query param	Type	Required	Notes
`page`	number	No	Page number. Defaults to `1`.
`limit`	number	No	Results per page (1-100). Defaults to `10`.

Response (200 OK):

{
  "results": [
    {
      "id": "a1b2c3d4-0000-0000-0000-000000000000",
      "matterNumber": "2026-0142",
      "name": "Acme v. Widgets",
      "clientName": "Acme Corp",
      "status": "open",
      "responsibleUserId": null,
      "createdAt": "2026-09-01T00:00:00.000Z",
      "updatedAt": "2026-09-01T00:00:00.000Z",
      "actualCost": 46.0,
      "eventCount": 14,
      "eventsMissingCost": 0
    }
  ],
  "page": 1,
  "limit": 10,
  "totalPages": 1,
  "totalResults": 1
}

Create a matter

POST /v1/matters

Request body:

{
  "matterNumber": "2026-0142",
  "name": "Acme v. Widgets",
  "clientName": "Acme Corp"
}

Field	Type	Required	Notes
`matterNumber`	string	Yes	The firm’s own case number, unique in your organization. This is the value events tag with `metadata.matterId`.
`name`	string	Yes	The matter name, such as the case caption.
`clientName`	string	Yes	The client this matter is billed to.
`status`	string	No	`open` or `closed`. Defaults to `open`.
`responsibleUserId`	string	No	The responsible timekeeper, by user UUID.

Response (201 Created): the created matter.

{
  "id": "a1b2c3d4-0000-0000-0000-000000000000",
  "matterNumber": "2026-0142",
  "name": "Acme v. Widgets",
  "clientName": "Acme Corp",
  "status": "open",
  "responsibleUserId": null,
  "createdAt": "2026-09-01T00:00:00.000Z",
  "updatedAt": "2026-09-01T00:00:00.000Z"
}

Common errors:

409 Conflict: a matter with that matterNumber already exists in your organization.

Get one matter

GET /v1/matters/{id}

Returns the matter, its all-time cost and event count, and its 100 most recent events. The full record lives on the audit endpoint below; eventsCap tells you the cutoff. Response (200 OK):

{
  "matter": {
    "id": "a1b2c3d4-0000-0000-0000-000000000000",
    "matterNumber": "2026-0142",
    "name": "Acme v. Widgets",
    "clientName": "Acme Corp",
    "status": "open",
    "responsibleUserId": null,
    "createdAt": "2026-09-01T00:00:00.000Z",
    "updatedAt": "2026-09-01T00:00:00.000Z"
  },
  "actualCost": 46.0,
  "eventCount": 14,
  "eventsMissingCost": 0,
  "events": [
    {
      "eventId": "e1000000-0000-0000-0000-000000000000",
      "usageDate": "2026-09-05T12:00:00.000Z",
      "agentName": "Research Bot",
      "signalName": "documents_reviewed",
      "quantity": 1,
      "usageCost": 5.0,
      "source": "tag"
    }
  ],
  "eventsCap": 100
}

An event’s usageCost is null when its cost isn’t resolved yet. source is tag, rule, manual, or null. Common errors:

404 Not Found: no matter with that ID in your organization.

Update a matter

PATCH /v1/matters/{id}

Only the fields you send change. Send responsibleUserId: null to clear the responsible timekeeper. Closing a matter (status: "closed") is a label only. It doesn’t stop anything at record time. Response (200 OK): the updated matter, same shape as create. Common errors:

404 Not Found: no matter with that ID in your organization.
409 Conflict: the new matterNumber is already used by another matter.

Delete a matter

DELETE /v1/matters/{id}

Deleting a matter doesn’t delete its usage events. They survive and return to Unassigned, where a rule or a manual assignment can pick them up again. The matter’s routing rules are deleted with it. The response counts both. Response (200 OK):

{
  "deleted": true,
  "eventsReturnedToUnassigned": 14,
  "routingRulesDeleted": 2
}

Common errors:

404 Not Found: no matter with that ID in your organization.

Unassigned events

List unassigned events

GET /v1/matters/unassigned

Returns the usage events no matter has claimed. totalResults is the true all-time count of unassigned events (it’s never limited to the page or a date window), and totalCost is the cost of the whole unassigned set.

Query param	Type	Required	Notes
`page`	number	No	Page number. Defaults to `1`.
`limit`	number	No	Results per page (1-100). Defaults to `10`.

Response (200 OK):

{
  "results": [
    {
      "eventId": "e2000000-0000-0000-0000-000000000000",
      "usageDate": "2026-09-06T09:30:00.000Z",
      "agentName": "Intake Bot",
      "signalName": "messages",
      "quantity": 3,
      "usageCost": 0.75,
      "source": null
    }
  ],
  "page": 1,
  "limit": 10,
  "totalPages": 3,
  "totalResults": 25,
  "totalCost": 25.0,
  "eventsMissingCost": 0
}

Assign an event to a matter

POST /v1/matters/assign

Puts one usage event on a matter by hand, or pulls it off. A manual assignment outranks a tag or a rule, and a manual unassignment is never swept back up by the apply-rules pass. Request body:

{
  "eventId": "e2000000-0000-0000-0000-000000000000",
  "matterId": "a1b2c3d4-0000-0000-0000-000000000000"
}

Field	Type	Required	Notes
`eventId`	string	Yes	The usage event to move, by UUID.
`matterId`	string	Yes	The target matter’s UUID, or `null` to unassign the event.

Response (201 Created):

{
  "assigned": true,
  "eventId": "e2000000-0000-0000-0000-000000000000",
  "matterId": "a1b2c3d4-0000-0000-0000-000000000000",
  "source": "manual"
}

Common errors:

404 Not Found: the event or the target matter isn’t in your organization.

Routing rules

A routing rule attaches events to a matter automatically. A rule matches an event when every matcher it sets matches: agentCode exactly, customerExternalId exactly, and signalPattern as a case-insensitive substring of the signal name. A rule needs at least one matcher. Rules run in evaluation order: lowest priority first, and older rules before newer ones on a tie. The first rule that matches wins.

List routing rules

GET /v1/matter-rules

Returns your rules in the exact order they’re evaluated at record time and when you apply them.

Query param	Type	Required	Notes
`page`	number	No	Page number. Defaults to `1`.
`limit`	number	No	Results per page (1-100). Defaults to `10`.

Response (200 OK):

{
  "results": [
    {
      "id": "r1000000-0000-0000-0000-000000000000",
      "matterId": "a1b2c3d4-0000-0000-0000-000000000000",
      "matterNumber": "2026-0142",
      "matterName": "Acme v. Widgets",
      "priority": 100,
      "agentCode": "research-bot",
      "customerExternalId": null,
      "signalPattern": null
    }
  ],
  "page": 1,
  "limit": 10,
  "totalPages": 1,
  "totalResults": 1
}

Create a routing rule

POST /v1/matter-rules

Request body:

{
  "matterId": "a1b2c3d4-0000-0000-0000-000000000000",
  "agentCode": "research-bot"
}

Field	Type	Required	Notes
`matterId`	string	Yes	The matter this rule assigns events to, by UUID.
`priority`	number	No	Lower runs first. Defaults to `100`.
`agentCode`	string	No	Match this exact agent code.
`customerExternalId`	string	No	Match this exact customer external ID.
`signalPattern`	string	No	Match this text anywhere in the signal name (case-insensitive).

At least one of agentCode, customerExternalId, or signalPattern is required. Response (201 Created): the rule, including its matter’s number and name. Common errors:

400 Bad Request: no matcher was provided.
404 Not Found: the target matter isn’t in your organization.

Apply routing rules

POST /v1/matter-rules/apply

Sweeps your rules across events that are still Unassigned, in priority order. It touches only events with no matter and no attribution history, so it never overrides a tag, an earlier rule, or a manual choice. Response (201 Created):

{
  "assigned": 12
}

If the sweep stops partway, the response says how many events were assigned before it stopped. Run it again to finish the rest.

Update a routing rule

PATCH /v1/matter-rules/{id}

Only the fields you send change. Send a matcher as null to clear it. A rule must always keep at least one matcher. Response (200 OK): the updated rule. Common errors:

404 Not Found: no rule with that ID in your organization.

Delete a routing rule

DELETE /v1/matter-rules/{id}

Deleting a rule stops future matching only. Events the rule already assigned keep their matter. Response (200 OK):

{
  "deleted": true
}

Common errors:

404 Not Found: no rule with that ID in your organization.

The audit record

Export the matter audit

GET /v1/matters/audit

This is the record a firm shows a client or a carrier: the actual AI cost per matter over a window. The default summary view is one row per matter, plus an Unassigned row, plus organization totals. It reconciles exactly with the Law tab CSV export for the same window.

Query param	Type	Required	Notes
`start`	string	No	Window start, as `YYYY-MM-DD` (start of day UTC) or a full ISO timestamp. Defaults to 30 days back.
`end`	string	No	Window end, as `YYYY-MM-DD` (end of day UTC) or a full ISO timestamp. Capped at now. Defaults to now.
`format`	string	No	`summary` (default) or `detail`. `detail` adds one row per event.
`matterId`	string	No	Slice to one matter, by UUID. A sliced view has no Unassigned row and no organization totals.

Response (200 OK, summary):

{
  "periodStart": "2026-08-11T00:00:00.000Z",
  "periodEnd": "2026-09-10T23:59:59.999Z",
  "summary": [
    {
      "matterNumber": "2026-0142",
      "matterName": "Acme v. Widgets",
      "clientName": "Acme Corp",
      "cost": 21.0,
      "eventCount": 5,
      "eventsMissingCost": 0
    },
    {
      "matterNumber": null,
      "matterName": null,
      "clientName": null,
      "cost": 25.0,
      "eventCount": 9,
      "eventsMissingCost": 0
    }
  ],
  "totalCost": 46.0,
  "totalEvents": 14,
  "eventsMissingCost": 0
}

The row with a null matterNumber is the Unassigned row. It’s present whenever unassigned events fall in the window. When you pass format=detail, the response also carries a rows array, one entry per event, each with its matter, date, agent, signal, the models used, cost, quantity, and attribution source. Costs that aren’t resolved yet count as 0 in every total and are flagged in eventsMissingCost. They’re never invented, so the number you hand an auditor is honest.

A quick pattern

A firm that wants clean records from day one usually does this:

Create a matter for each open case, using the firm’s own case number as matterNumber.
Tag each usage event with metadata.matterId set to that case number, so events land on the right matter as they’re recorded.
Add a routing rule or two for the work that’s hard to tag at the source.
Check the Unassigned list now and then, and assign anything left over by hand.
Export the audit for a billing window when it’s time to bill.

Steps 1 through 4 keep the record accurate. Step 5 turns it into a number a client can trust.

Resources

Reference

Matters (for law firms)

Matters

What a matter is

How usage attaches to a matter

Actual cost, never an estimate

Who can manage matters

The legal key

Matters

List matters

Create a matter

Get one matter

Update a matter

Delete a matter

Unassigned events

List unassigned events

Assign an event to a matter

Routing rules

List routing rules

Create a routing rule

Apply routing rules

Update a routing rule

Delete a routing rule

The audit record

Export the matter audit

A quick pattern

​Matters

​What a matter is

​How usage attaches to a matter

​Actual cost, never an estimate

​Who can manage matters

​The legal key

​Matters

​List matters

​Create a matter

​Get one matter

​Update a matter

​Delete a matter

​Unassigned events

​List unassigned events

​Assign an event to a matter

​Routing rules

​List routing rules

​Create a routing rule

​Apply routing rules

​Update a routing rule

​Delete a routing rule

​The audit record

​Export the matter audit

​A quick pattern

Matters

What a matter is

How usage attaches to a matter

Actual cost, never an estimate

Who can manage matters

The legal key

Matters

List matters

Create a matter

Get one matter

Update a matter

Delete a matter

Unassigned events

List unassigned events

Assign an event to a matter

Routing rules

List routing rules

Create a routing rule

Apply routing rules

Update a routing rule

Delete a routing rule

The audit record

Export the matter audit

A quick pattern