api.lawyer
Early access

API REFERENCE

Every route, from one manifest.

This reference is generated from the same routes manifest the service ships — path, method, and request/response examples as JSON. The base path is this host; requests and responses are application/json.

Matters

The Matter is the unit of legal work — one Client, one legal objective, advanced through the six Stage Verbs (intake, prepare, examine, review, sign, file) to a terminal outcome. Stage is derived from the append-only journal; terminal is forever.

POST/mattersMint a Matter and its Asset. A ratified matterType is required (400 otherwise) — jurisdiction derives from the Jurisdiction Rules table against the matter facts. The Asset carries lineage, docket, and a Deadline Ladder.
request
{
  "tenant": "acme-ip-tools",
  "mint": "patent.click",
  "consumerPattern": "B2H2A",
  "offer": "provisional",
  "listFeeUsd": 1200,
  "client": { "name": "Ada Inventor" },
  "asset": { "kind": "patent_application", "title": "Distributed ledger for credential attestation" },
  "rail": "patent",
  "matterType": "patent_provisional",
  "clientState": "TX",
  "adverseParties": [],
  "exposureUsd": 25000,
  "clientMandates": { "settlementFloor": 50000 },
  "tenantGuardrails": { "maxFeeUsd": 300 }
}
response
{
  "matter": {
    "id": "m_1",
    "stage": "intake",
    "status": "intake",
    "rail": "patent",
    "matterType": "patent_provisional",
    "jurisdiction": "*",
    "assetId": "a_1",
    "needsClientDirection": false
  }
}
GET/matters/:idThe Matter, its Asset, and the append-only journal of committed events.
response
{
  "matter": { "id": "m_1", "stage": "review", "status": "waiting_on_signer", "pendingGigId": "g_7" },
  "asset": { "id": "a_1", "kind": "patent_application", "lineage": ["m_1"] },
  "journal": [
    { "kind": "stage", "verb": "intake", "by": "gate", "note": "matter opened" },
    { "kind": "stage", "verb": "prepare", "by": "agent", "note": "…" }
  ]
}
POST/matters/:id/advanceOne turn of propose → gate → commit. If the next act is in the Reserved-Act Catalog, the service escalates instead: it posts a Gig to gigs.lawyer and the Matter waits on a Signer.
request
{
  // optional B2H2A override, merged over the agent's Proposal
  "merits": { "settlementUsd": 60000, "clientDirectionSeq": 1 }
}
response
{
  "matter": { "id": "m_1", "stage": "prepare", "status": "prepare" },
  "committed": { "advanceTo": "prepare", "by": "agent" }
}

// or, when the next act is reserved:
{
  "matter": { "id": "m_1", "status": "waiting_on_signer", "pendingGigId": "g_7" },
  "escalated": { "reservedAct": "sign", "gigId": "g_7" }
}
POST/matters/:id/gig-resultThe gigs.lawyer callback. 'attested' commits the reserved act with the Signer's Attestation; 'send_back' returns the Matter to prepare with defects journaled; 'declined' journals the memo and the Matter needs the Client's direction — a Declination is final.
request
{
  "gigId": "g_7",
  "outcome": "attested",
  "attestation": { "signedBy": "sg_1", "credentialRef": "uspto:71234", "artifactHash": "sha256:…" }
}
response
{ "matter": { "id": "m_1", "stage": "sign", "status": "sign" } }
POST/matters/:id/client-directionJournal the Client's instruction — the only event that reopens a Matter a Declination has stopped. Captured from the actual Client; a Tenant's agent cannot manufacture the Client's yes.
request
{ "instruction": "proceed with a narrowed claim set", "authorizes": { "settlementUsd": 60000 } }
response
{ "matter": { "id": "m_1", "status": "review", "needsClientDirection": false }, "directionSeq": 6 }
POST/matters/:id/consentJournal the Client's Consent — the captured informed-consent artifact (limited scope, tenant data access). Required before a B2A2D Matter advances past intake. Executed by the actual Client: any other actor is refused with 422 — a Tenant's agent cannot consent on the Client's behalf.
request
{ "actor": "client", "scope": "limited-scope engagement + tenant data access" }
response
{ "matter": { "id": "m_1", "stage": "intake", "consented": true }, "consentSeq": 1 }
GET/matters/:id/settlementThe two-rail Settlement, only on a fulfilled Matter. Patent rail: platform as provider — flat Legal Fee to the Signer, Product Fee to the Customer. State rail: the Signer is merchant of record for the Legal Fee (recorded, never platform revenue). Both carry the per-act insurance line.
response
{
  "settlement": {
    "rail": "patent",
    "merchantOfRecord": "platform",
    "productFeeToCustomerUsd": 1200,
    "legalFeeToSignerUsd": 300,
    "attestedActs": 2,
    "perActInsuranceUsd": 40,
    "insuranceTotalUsd": 80,
    "platformNetUsd": 820
  }
}
Orders

The one-shot Mint surface: a Mint (patent.click) turns a purchase into a Matter and drives it until it waits on a Signer or terminates.

POST/ordersCreate a patent-rail Matter and advance it until waiting_on_signer or terminal.
request
{
  "mint": "patent.click",
  "offer": "provisional",
  "title": "Distributed ledger for credential attestation",
  "inventor": "Ada Inventor",
  "listFeeUsd": 99
}
response
{ "matterId": "m_2", "status": "waiting_on_signer" }
Deadline Ladder

Clock-driven safety machinery on the Asset — deterministic (an explicit tick drives the clock, never wall time), closed only by evidence, daily human acknowledgment inside the final week, and an enumerated terminal rung.

GET/deadlines/:assetIdThe ladder's state: days remaining, alarm (nominal | vacant), vacancy, the Monitoring Engagement holder, ack window, resolution — and on recurring obligations (franchise tax) the next occurrence and past-occurrence history.
response
{
  "assetId": "a_1",
  "daysUntilDeadline": 45,
  "alarm": "nominal",
  "vacant": false,
  "monitoring": { "assetId": "a_1", "signerId": "sg-1" },
  "ackRequiredToday": false,
  "terminalOutcomes": ["clientNotice", "extensionPurchase", "proSeHandoff", "outsideCounselHandoff"],
  "occurrences": [],
  "acks": [],
  "resolution": null
}
POST/deadlines/:assetId/ackA named human acknowledges today’s rung — required daily inside t-7..t-1.
request
{ "actor": "ops@tenant" }
response
{ "acked": true, "atDaysRemaining": 6 }
POST/deadlines/:assetId/tickAdvance the deterministic clock by N days; returns the rung events that fired.
request
{ "days": 15 }
response
{
  "daysUntilDeadline": 30,
  "alarm": "nominal",
  "events": [{ "rung": "notice", "atDaysRemaining": 30 }]
}
POST/deadlines/:assetId/monitorName who holds the Monitoring Engagement on this Asset — a Signer id, or 'platform' for open watch machinery. Naming an owner clears vacancy: dead air has a NAMED owner, never an anonymous one.
request
{ "signerId": "sg-1" }
response
{ "monitoring": { "assetId": "a_1", "signerId": "sg-1" }, "vacant": false, "alarm": "nominal" }
POST/deadlines/:assetId/satisfyClose the deadline by evidence — the receipt. On a one-shot ladder this resolves it forever; on a RECURRING obligation (DE franchise tax) it resolves the current occurrence and rolls nextOccurrence forward one cadence — the obligation never closes this way, it recurs.
request
{ "evidenceRef": "de/franchise-tax/receipt/2027" }
response
{
  "assetId": "a_1",
  "recurEveryDays": 365,
  "nextOccurrenceInDays": 365,
  "occurrences": [{ "kind": "satisfied", "evidenceRef": "de/franchise-tax/receipt/2027" }],
  "resolution": null
}
POST/deadlines/:assetId/resolveChoose the enumerated terminal-rung outcome at t-0 — clientNotice, extensionPurchase, proSeHandoff, or outsideCounselHandoff. Nothing else is a legal answer to t-0; 409 off the terminal rung. On a recurring obligation this is the ONLY permanent closure — a handoff ending the platform’s watch.
request
{ "outcome": "outsideCounselHandoff" }
response
{ "resolved": { "kind": "terminal_rung", "outcome": "outsideCounselHandoff" } }

How the service refuses

Refusals are typed and worded: 404 for a Matter or Asset that does not exist, 409 when the Matter is waiting_on_signer, terminal, or stopped by a Declination, 422 when the Gate refuses a Proposal (mechanics, merits, or a missing Attestation), and 502 when gigs.lawyer refuses a Gig post. The Gate speaks only to refuse — a 2xx is the journal committing.