Bring your own AI. Automate your casework.

Connect a local AI assistant, build a custom workflow, or integrate your own software. The REST API and MCP server expose 199 application operations using the same account permissions and usage limits as the website.

Upload & organize

Add evidence and documents, create and move folders, edit descriptions, apply labels, and assign categories.

Prepare & collaborate

Manage cases, messages, hearings, contacts, tasks, preparation, sharing, and exports.

Stay in control

Create named tokens, select permissions, set an expiration or leave it open-ended, and revoke access at any time.

Give your AI the integration skill

Download a reusable skill with MCP setup instructions, casework guidance, and the local adapter for CourtBriefly and Custody Commander.

Download AI skill (.zip) · Installation and connection guide

Make your first request

  1. Sign in and open API tokens.
  2. Create a token with the permissions your integration needs. The “API token created” modal shows the full token with a Copy token button. Save it before closing; it is shown only once. The token list only shows a prefix. If you lose the full token, revoke it and create a replacement.
  3. Set your app URL and token as environment variables, then request your default case:
export CASE_COMMANDER_URL="https://app.courtbriefly.com"
# Set CASE_COMMANDER_API_TOKEN securely in your environment.
curl "$CASE_COMMANDER_URL/api/v1/case" \
  -H "Authorization: Bearer $CASE_COMMANDER_API_TOKEN"

This request requires case:read. Use the returned case ID in subsequent operations. Both app.courtbriefly.com and app.custodycommander.com support the API.

Upload, move, label

A token with evidence:write can upload a file and update its labels and folder:

curl "$CASE_COMMANDER_URL/api/v1/evidence" \
  -H "Authorization: Bearer $CASE_COMMANDER_API_TOKEN" \
  -F "caseId=YOUR_CASE_ID" -F "files=@./receipt.pdf"

curl -X PATCH "$CASE_COMMANDER_URL/api/v1/evidence/YOUR_EVIDENCE_ID" \
  -H "Authorization: Bearer $CASE_COMMANDER_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"folderId":"YOUR_FOLDER_ID","tagNames":["expenses"],"description":"School receipt"}'

Use folders:write to create folders and issues:write to manage categories. Assign category IDs with issueIds; assign cases and hearings with courtCaseIds and hearingIds. Setting folderId to null moves an item out of its folder. Audio/video uploads require the same recording-consent field as the site. See Swagger for operation details.

Permissions, contexts, and limits

  • Permissions are selected by area and action: evidence:read, evidence:write, documents:read, and more. Write access can include deletion. Full access (*) includes every present and future operation the account is authorized to use.
  • A token never grants access to another person’s private data or bypasses sharing, firm roles, archived-matter restrictions, paid features, storage limits, or AI allowances. Read permissions may return related data visible in that area of the app. Export permissions permit the corresponding exports.
  • API and MCP share 120 requests per minute per account across all tokens and server instances. A 429 response includes Retry-After. Existing app-specific limits also apply.
  • Local AI reasoning does not consume the app’s AI allowance. Calling an app AI extraction, analysis, drafting, transcription, mediation, or assistant operation uses its existing billing rules. The app meters AI operations and records provider tokens; integration tokens are credentials, not additional AI credits.
  • Pass X-Case-Context: ws:WORKSPACE_ID or matter:CASE_ID for an explicit context. Access is validated. With no header, contextual operations use your default workspace. Explicit caseId parameters select a case independently and still undergo access checks. A context header selects a view; it does not restrict a token to that workspace.
  • API requests are stateless. Workspace switching returns an active context value; send it on later requests. Cookies are not used for API authentication.
  • 400 means invalid input, 401 means missing/invalid/expired/revoked credentials, 402 means a plan or usage limit, 403 means insufficient permission, and 404 means an unavailable resource. Do not automatically retry mutations after a timeout: first check whether the action completed.

Request and document limits

The website and REST API accept at most 32 MiB per multipart request, 25 MiB per file, and 30 files. JSON bodies are limited to 4 MiB. For larger evidence recordings, use a direct upload: POST /uploads runs every upload check and returns one upload URL per file; PUT each file's bytes to its URL, then file them with POST /evidence (or POST /documents/upload) and the JSON body { caseId, uploads: [{ token, path }] }. Evidence videos and audio may be up to 200 MiB this way; every other file stays at 25 MiB. Files are stored byte for byte either way. MCP additionally limits the encoded request to 24 MiB and each decoded file to 16 MiB. Document extraction runs in isolated workers with a 15-second deadline, a 128 MiB V8 old-generation budget, at most 64 MiB of archive expansion, 2,000 archive entries, 500 PDF pages, and 2 million extracted characters. Split larger uploads into smaller requests. A 413 response means a request or processing limit was exceeded; a 429 response means processors are busy. These limits supplement existing plan, storage, permission and AI limits.

Cookie-authenticated writes require a same-origin Origin or Referer. API/MCP bearer authentication is checked independently and does not require browser cookies. Client-supplied middleware path, method and identity headers never establish authority.

Usage and limits

GET /api/v1/billing/usage (billing:read, MCP tool get_billing_usage) returns every usage limit on the account, the same list as the app's Usage & limits page. ai has the AI credits included in the current window (window is month, trial, pass or lifetime), what is left, extra credits (bought or bonus, never expire), refillsAt, the AI speed limit and what this window's credits were used for (byKind). ai.boost is the Double AI perk when it applies (a free thank-you that doubles a Full Suite subscriber's monthly credits; it can change or end): multiplier, baseAllowance, allowance and grantedAt, or null. limits has one row per limit (ai_included, ai_extra, ai_speed, storage, evidence_items, court_cases, tools, exports, court_documents, file_size, files_per_upload, api_requests, and workspaces / ai_unverified when they apply), each with used, limit (null = unlimited), a plain-English value and a status of ok, low or out. offers and compare list the plans that raise the limits; in the Android app they are empty. It is read-only and never starts a purchase.

Authenticator setup

POST /api/v1/account/security with {"action":"setup","password":"CURRENT_PASSWORD"}, or call MCP tool post_account_security with the same JSON body. Requires account:write. The response includes a manual secret and an otpauth:// uri. Render the URI as a QR code locally, as the security page does; never send it to an external QR service or log it. Apple Passwords and other TOTP authenticator apps can scan it or use the manual key. Setup expires after ten minutes. Complete setup with action: "enable", the current password, and the generated code; save the returned single-use recovery codes immediately.

All application operations, one interface

The Swagger reference and MCP tools share the same operation catalog. Account security operations still require password/MFA confirmation where the site does. GET /account/terms (MCP get_account_terms) returns the Terms for the account’s saved residence, including the North Carolina addendum when applicable. Pass residenceState to preview another state. The response includes accountResidenceState (null when unset). Present the returned text and obtain explicit acceptance before using POST /account/terms (MCP post_account_terms). Send the version and the state the person reviewed, or omit the state when their residence is unset and they reviewed the general Terms. The built-in assistant requires full access because it can perform actions across areas. Signup, password reset, browser login/logout, anonymous analytics, and payment-provider callbacks retain their dedicated authentication flows; they are not personal-token operations.

Existing tokens with specific permissions keep those permissions as features grow. Full-access tokens also cover new features. Regenerate your integration from the OpenAPI document when upgrading clients.

AI model

All text and image AI features use xAI Grok 4.7 (grok-4.7), including assistant chat, drafting, message analysis, evidence extraction and mediation. The website, versioned API and MCP use the same service, permissions and usage limits.

Photos, screenshots and scanned PDFs uploaded to Documents have no text until they are read: POST /api/v1/documents/DOCUMENT_ID/extract with {"ai":true} (MCP post_documents_by_id_extract) reads one with the same AI reading and usage metering as evidence extraction (one extract operation; a plan with Evidence) and makes the result the document's text, marked AI generated until reviewed. Without ai it runs the free deterministic extraction. When the document's text was edited after upload the response is 409 text_edited and nothing is charged; send {"ai":true,"replace":true} only after the user agrees (the earlier text stays in history). Speech transcription and voice synthesis use their dedicated audio providers. Provider credentials remain server-side.

Assistant actions and document history

The assistant carries out explicitly requested edits without a second approval. Before reading sources, it identifies allowed actions, changed fields and target records from user requests, using previous user messages only to resolve follow-up details. Retrieved content cannot add permissions. Name records in edit requests; missing or ambiguous targets require clarification. Source-derived factual accuracy still needs review. The assistant cannot attest to verified facts or filing completion.

Deleting a document, evidence item, court case, hearing, to-do, timeline entry or contact through the assistant creates a ten-minute confirmation proposal. The built-in assistant cannot confirm it. API/MCP clients use POST /api/v1/assistant/deletions (caseId, kind: document, evidence, court_case, hearing, todo, timeline_event or contact, id), present the returned label and detail, and call POST /api/v1/assistant/deletions/PROPOSAL_ID/confirm with {"confirmed":true} only after the user confirms. Both operations require full-access token scope, existing permission to delete that record (court cases and hearings: the workspace owner), and a writable matter. Confirmation is single-use and rejects changed records. The confirmed record goes to Recently deleted (below). Direct DELETE endpoints keep their permission rules; external integrations remain responsible for obtaining user confirmation.

Document title, body and record-note changes automatically save the previous text, including assistant edits and re-extraction. History begins with edits made after this release. GET /api/v1/documents/DOCUMENT_ID/versions lists previous versions; pass versionId to read one snapshot or before=nextCursor for older pages. POST to the same path with versionId and expectedUpdatedAt restores a version and saves the displaced text. A 409 means the document changed: reload before retrying. PATCH /documents also accepts expectedUpdatedAt for conflict protection. Restoring preserves attachments/sharing and clears signatures and review. Historical text requires edit permission, even for GET, and consumes the existing matter payer’s storage quota. Versions are removed when their document is deleted.

MCP tools: get_documents_by_id_versions, post_documents_by_id_versions, post_assistant_deletions, and post_assistant_deletions_by_id_confirm. Use documents:read for history reads and documents:write for restore, in addition to document edit permission. Chat responses contain pendingDeletions for confirmation controls; never pass these controls back into model context as approvals.

Hearing prep

GET /api/v1/hearings/{id}/prep returns one hearing's checklist: the 9 standard steps with their due dates, every to-do linked to the hearing, what is still open elsewhere (no time or place, evidence without an exhibit number, binders not printed, missing records, unserved filings, open questions), a summary (left, daysLeft) and the day card notes. Add summary=1 for the counts only. POST the same path with {"action":"add-steps"} (optional steps) to add the standard steps as to-dos, or save-notes with the revision from GET. GET /api/v1/hearings/{id}/day-card returns the private day card PDF. These use hearings:read / hearings:write; to-dos, evidence and preparation items are included or changed only when the token also has todos, evidence or preparation scope.

Saved assistant chats

Every assistant turn (POST /api/v1/assistant/chat) is saved to the caller's account: their message and the answer, with the model, tools used, records found or changed and any safety flag. Send the same conversationId (8-64 letters, digits, - or _) with each turn of one conversation; without it the first message identifies the chat. GET /api/v1/assistant/chats lists the caller's chats (optional caseId, before = the previous page's next, limit up to 50), GET /api/v1/assistant/chats/CHAT_ID reads one, and DELETE on either path deletes one chat or all of them (optional caseId). Deleted chats go to Recently deleted for 7 days, where only the person who deleted them can see or restore them. These require full-access token scope, like the chat itself. Only chats in workspaces the caller can still open are returned.

On Custody Commander our team may read chats from the last 90 days to improve the assistant, after phone numbers, email addresses, street addresses and full names are removed, unless the person turns that off. It applies only to workspaces the person owns, only after the app showed them its notice (send reviewNotice: "shown" with the message if your client shows the same notice), and never to CourtBriefly. Each message's staffCanRead says whether it applies today. GET/PATCH /api/v1/account/assistant-chats (account:read / account:write) reads and changes the choice: review (false keeps every chat private, including earlier ones) and noticeSeen. MCP tools: get_assistant_chats, get_assistant_chats_by_id, delete_assistant_chats, delete_assistant_chats_by_id, get_account_assistant_chats and patch_account_assistant_chats.

Recently deleted (7-day restore)

Every delete, from the app, the API, MCP or a confirmed assistant deletion, goes to Recently deleted for 7 days: evidence, documents, folders, court cases, hearings, to-dos, timeline entries, contacts, conversations and message imports, preparation records and shared-expense receipts. The copy holds what was deleted with the record (a court case's hearings and goals, a folder's items, a document's files and versions) and the links that were cleared (documents filed under a deleted court case). DELETE responses now include trashId and restorableUntil.

GET /api/v1/trash?caseId=WORKSPACE_ID (trash:read, MCP get_trash) lists the workspace's items (all of them for the owner and full-access members, only the caller's own deletions for anyone else) with kind, label, detail, deletedAt, expiresAt, daysLeft, canRestore and canDeleteNow, plus receipts the caller removed from shared expense logs. POST /api/v1/trash/TRASH_ID/restore (trash:write, MCP post_trash_by_id_restore) puts the same records back with the same ids and re-links them where nothing was linked since; it answers 409 when a newer record uses the same name or number or when what it belongs to was deleted afterwards (restore that first), 410 after 7 days, and 403 in a closed or archived matter. DELETE /api/v1/trash/TRASH_ID (trash:write, MCP delete_trash_by_id) lets the workspace owner delete an item for good right away. After 7 days, or after Delete now, the stored files are removed as before. Legal holds refuse deletes (423) and keep expired items until released.

Deadlines, reminders and hearing readiness

GET /api/v1/upcoming?caseId=WORKSPACE_ID (upcoming:read) returns the countdown agenda: scheduled hearings with days until each, whether each is marked ready and when the next reminder goes out; overdue and upcoming deadlines, reminders and to-dos; undated to-dos; and items completed in the last 14 days. Days are counted in the user's notification time zone. Mark a hearing prepared with PATCH /api/v1/hearings?id=HEARING_ID and {"ready":true}; that stops “you still need to prepare” reminders for it, and false turns them back on.

To-dos accept kind (task, deadline or reminder), dueTime (HH:MM), reminderDays (days before the due date; replaces the user's defaults for that item) and followUpDays (if still open after the due date, one follow-up to-do is added). POST /api/v1/deadlines (deadlines:write) adds a deadline from a template that does the date arithmetic with the user's planning timing: subpoena and discovery_serve take a hearingId; discovery_responses_due and discovery_respond take anchorDate, the date served. Send preview: true to compute without saving. GET /api/v1/deadlines lists the templates with the timing each uses. The timing is the user's setting, not a statement of any court's rules.

Reminder timing lives in rules on GET/PUT /api/v1/notifications/preferences (notifications:read / notifications:write): reminderHour, hearing days and hours, prep on/off and days, deadline and todo days plus overdueDays, reminder days, timedLeadMinutes and the template timing. A partial update merges field by field; resetRules: true restores the defaults. MCP tools: get_upcoming, get_deadlines, post_deadlines, patch_hearings, post_todos, patch_todos, get_notifications_preferences and put_notifications_preferences. Push and email reminders only say that there is a reminder; details are shown after sign-in.

Printing the to-do list

GET /api/v1/todos/print?caseId=WORKSPACE_ID&range=next-week (todos:read, MCP tool get_todos_print) returns a PDF checklist with an empty box to tick by pen for each to-do: overdue items first, then one section per due day, then items with no due date, then blank rows to write new items in. range is today, this-week (default), next-week, next-7, this-month, next-month, next-30, all or custom; from and to (YYYY-MM-DD) set custom dates. Weeks start on Sunday unless weekStart=mon. today sets the person's own date; otherwise it is today in their notification time zone. Switches, each 1 or 0: overdue (default 1), undated (default 1 for all, else 0), completed (default 0; printed with a ticked box), details (default 1). blank is 0–30 write-in rows (default 6); download=1 asks the browser to save rather than open it. Add courtCaseId for one court file. Like the evidence exports, every page carries the brand header (shield, name and website) and the “Prepared with” footer with page numbers; branding=0 leaves the brand out of the pages and the PDF metadata (default on, every plan; x-export-branding reports on or off). It prints the same to-dos GET /api/v1/todos returns for that token; the x-item-count response header gives the number printed.

Organization checklist

GET /api/v1/progress?caseId=WORKSPACE_ID (progress:read, MCP tool get_progress) returns the owner's organization checklist: twelve items in one fixed order, each with done, optional progress and the app href where it is done; counts and meter; the next court date as its own hearing field; nextStep (the next unfinished item); milestones reached; and activity.daysThisMonth. It counts records only, never their content. It is a personal organizing list, not legal advice, and says nothing about how a court will decide. Only the case owner can read it; collaborators get 403. Milestone moments are shown and recorded by the app itself, never through tokens. The weekly summary email (weeklyDigest on /api/v1/notifications/preferences) can be turned off with a token, but only the account holder can turn it on, in the app.

Welcome-back status report

GET /api/v1/briefing?caseId=WORKSPACE_ID (briefing:read, MCP tool get_briefing) returns the status report the assistant chat opens with after a sign-in: firstName; strength (the owner's case file strength score, level, levelLabel, verdict, goalsSet, short goals, trend and the top focus gaps; null for helpers on someone else's case); hearing (the next scheduled court date with daysUntil and ready); todos (overdue, dueToday, next7 and up to three overdue or due-today titles); tips (what to do next, best first: pick a goal when none is set, get ready for a court date within 14 days, overdue to-dos, then strength gaps, each with title, why, steps and an in-app action); message (the chat text in markdown, its reply buttons and local, the answers to those buttons); and teaser. Optional reason (signin or return) and awayDays only change the greeting. It costs no AI action, counts the person's own records only, never weighs who is right and isn't legal advice. Shared-expense counts are never included through tokens.

Case file strength

GET /api/v1/strength?caseId=WORKSPACE_ID (strength:read, MCP tool get_strength) returns the owner's case file strength. Each court case has its own score and its own goals (it counts the records linked to that case plus the records linked to no case): cases lists every court case with its courtCaseId, score, level, verdict and goalsSet, and overall is the average across them (what the app's sidebar shows; the whole file when there is no court case yet). The rest is one case's full report (pick it with courtCaseId; the first case when omitted; an unknown one returns 404): a 0-100 score and level (not_started, thin, building, solid, strong) for how complete, recent and detailed their own records are, a one-line verdict, eight areas (messages, evidence, details, timeline, topics, court, people, presentation) each with score, weight, summary, facts, gaps (a sentence and the app href to fix it) and basis (how it is counted), the record topics for the person's goals, strengths, the three focus gaps and a weekly trend. Every full call scores the cases again from the records as they are now (the app's Rescore button is this call) and returns computedAt, when that score was worked out. Add summary=1 for just the overall score, level, verdict and trend plus each case's score. PUT /api/v1/strength (strength:write, MCP tool put_strength) saves one court case's goals (courtCaseId; omit it to save the whole file's goals, used when there is no court case yet): outcomes (up to 3 goal codes from that case's goalMenu, the goals for its kind of case, such as change_order or support_collect), customGoals (“something else” in their own words, keyed by the goalMenu group, e.g. {"child_support":"…"}, up to 300 characters each; each new answer is read by the AI into record topics for that case for one metered AI action, or by keywords at no cost when AI isn't available; "" removes that answer) and skippedTopics; the response adds readings. It measures the person's own records only: it never weighs who is right, isn't legal advice and can't predict a ruling. Facts can name the owner's own saved contacts. Shared-expense counts are never included through tokens. Only the case owner can read or change it; collaborators get 403. GET /api/v1/progress items now also carry facts and nudge, plus a strength brief (the overall, with caseCount).

Case workspaces and case context

The website groups Evidence, Binders, Preparation, To Dos, Timeline and Documents under /cases/COURT_CASE_ID. The API still uses caseId for the parent workspace and courtCaseId for one court file. Discover court files with GET /api/v1/court-cases?caseId=WORKSPACE_ID or MCP get_court_cases. Pass courtCaseId to evidence, documents, to-do and timeline list/create operations to match the case view. Assign evidence to several cases with PATCH /api/v1/evidence/ID and courtCaseIds; this preserves one original.

Message import accepts multipart courtCaseId. Message lists, threads, conversation search and message-log exports accept it as a query parameter; thread rename/delete, bulk operations and analysis accept it in the JSON body. This keeps identical participants in separate cases isolated for those operations. Omit the parameter for the full workspace, including older unassigned messages. The same fields are exposed by the corresponding MCP tools, including post_messages_import, get_messages_threads and post_messages_analyze. Case assignment is checked against accessible court files; existing message permissions, attestation, storage limits, export entitlements and AI metering continue to apply.

Preparation and binder records retain their courtCaseId in the existing preparation service. Filter returned collections by that field; evidence options expose courtCases and message options expose courtCaseId. For a scoped task import, POST preparation with the current revision and {"type":"import-todos","courtCaseId":"COURT_CASE_ID"} as the action. Backups remain workspace-wide. Assistant chat accepts optional courtCaseId as current-case context; full-access token scope and every existing mutation check remain required.

Sharing and account tabs reorganize existing operations: sharing/inbox, account/security, account, billing/status, billing/portal and AI usage. Global To Dos and Timeline remain available without courtCaseId. Case navigation does not change token scopes or account permissions.

Billing: trials, cancelling and refunds

GET /api/v1/billing/status (billing:read) returns trial (with card, cancelAtPeriodEnd and firstCharge for a card-on-file trial), trialOffer (whether the account can still start its one trial) and each subscription's id, refundEligible and refundEndsAt. POST /api/v1/billing/cancel (billing:write) takes {"action":"cancel","subscriptionId":"…","reason":"unused"} or {"action":"resume"}; cancelling during a trial is never charged, a paid plan stops at the end of its period, and reason is optional. POST /api/v1/billing/refund with {"subscriptionId":"…"} refunds a trial's first charge within 7 days of it and cancels the plan. A trial itself starts only in Stripe Checkout (POST /api/v1/billing/checkout with trial: true and the terms shown to the person); integrations never take a card.

Case Bundle, Case Closed, hardship access and attorney notes

GET /api/v1/export/case-bundle?caseId=ID (export:read) lists the parts of the owner's complete Case Bundle; download each with /api/v1/export/case-bundle/download?caseId=ID&tier=free|case_closed&part=records|exhibits-N|originals-N. tier=case_closed answers 402 unless the paid Case Closed purchase is on that case. GET and POST /api/v1/case-closed (case-closed:read/write) read the state and close or reopen a case; a closed case refuses every change until it is reopened. Other exports: /api/v1/export/timeline?caseId=ID&format=pdf|docx&branding=on|off (see Timeline print export), /api/v1/export/handoff?caseId=ID, /api/v1/export/message-log?…&format=pdf, and an optional bates object on POST /api/v1/export/court-packet.

GET /api/v1/hardship and POST {"action":"redeem","code":"…"} (hardship:read/write) read or redeem a hardship referral code for the token's own account. Attorney notes (attorney-notes:read/write) return only notes the token's user may read: their own, their firm team's shared notes, and, for the case owner, released notes. Code administration is staff-only and is not available to tokens.

Timeline filters

The timeline supports independent multi-select pills for years, months, and entry types. GET /api/v1/timeline and MCP tool get_timeline accept the same comma-separated query filters: kinds (event, evidence, keydate, hearing), years (four-digit years), months (01–12) and tags (tag names), plus from and to (YYYY-MM-DD, inclusive). Values within a filter use OR (an entry matches when it has any listed tag); filters combine with AND. Omitted filters show all values; an empty string selects none. Invalid values return 400. Existing case permissions and the timeline:read scope apply.

{
  "query": {
    "caseId": "YOUR_CASE_ID",
    "kinds": "event,hearing",
    "years": "2025,2026",
    "months": "01,09"
  }
}

Pass this query object to MCP get_timeline, or use its fields as URL query parameters for the versioned API.

Timeline print export

GET /api/v1/export/timeline?caseId=YOUR_CASE_ID&format=pdf (export:read, MCP tool get_export_timeline) returns the timeline laid out like the Timeline page for black-and-white printing: a summary and a linked index of every entry with page numbers first, then months, days and one card per entry. format=docx returns the same layout as an editable Word file. It accepts the same courtCaseId, kinds, years, months, tags, from and to filters as GET /api/v1/timeline (omit from and to for all time), plus q (search text). branding=on|off (default on) adds or removes the brand header and footer; only a paid plan can turn it off. Free-plan and trial copies are always branded and carry a light diagonal brand watermark with DRAFT or TRIAL. The x-export-branding, x-export-watermark and x-export-branding-locked response headers report what was applied.

Timeline editing and tags

Each entry from GET /api/v1/timeline carries tags (lowercase names) and canEdit. PATCH /api/v1/timeline (timeline:write, MCP tool patch_timeline) edits one entry in place with kind and id plus the fields that kind has: an event takes date, time, dateApproximate, title, detail and courtCaseId; evidence takes date (its event date), dateApproximate and title (its description); a key date takes date, time, title, keyDateKind (hearing, deadline, filing, other) and courtCaseId; a hearing takes date, title (its purpose), time, location, room, status and courtCaseId. tagNames replaces the entry's tags; tags are the case's shared list (the same one evidence uses), created when new and stored lowercase. POST /api/v1/timeline also accepts tagNames and time. Times are optional everywhere: 24-hour HH:MM, or ""/null to clear; the date stays required. Each entry from GET carries time (null when none), and the list is oldest first with untimed entries first on their day. A hearing's title still ends in “· HH:MM” for older clients; use purpose and time instead. A field another kind uses returns 400; edit permission on that entry is required and a closed or archived case refuses.

{
  "kind": "hearing",
  "id": "HEARING_ID",
  "date": "2026-12-03",
  "time": "09:00",
  "room": "Courtroom 4B",
  "tagNames": [
    "custody",
    "review"
  ]
}

Timeline formatting

Timeline titles and details support Markdown, including headings, bold, italic, strikethrough, lists, links, quotes, code, and tables. Single line breaks and blank-line paragraphs display in the timeline. Raw HTML is displayed as text. POST /api/v1/timeline or call MCP tool post_timeline with a JSON body containing caseId, date, title, and optional detail. Use JSON newline escapes in strings. Requires timeline:write. GET /api/v1/timeline?caseId=YOUR_CASE_ID or MCP tool get_timeline returns the stored Markdown text with timeline:read.

{
  "caseId": "YOUR_CASE_ID",
  "date": "2026-09-25",
  "title": "**Documents filed**",
  "detail": "Filed today.\nConfirmation received.\n\n- Motion\n- Supporting exhibits"
}
API & MCP developer documentation