Notes with evidence, over an API.

A design preview. The same engine our clinicians use — drafting, verification and compliance checks — is planned for EHR vendors and health-tech teams through REST, webhooks, an embeddable panel and SMART on FHIR. None of it is live yet; design partners help shape it.

Become a design partner Read the quickstart

Base URL: api.getmargent.com/v1
Format: JSON, multipart audio
Auth: Bearer key or OAuth 2.0
FHIR: R4 · US Core 6.1 · SMART v2

REST API

Quickstart: audio in, cited note out

Create a session from recorded audio, then fetch the draft. Every sentence comes back with its evidence (a transcript span, a chart reference, or the clinician) and a verification status. Drafts are never marked signed — signing happens in your product, by a clinician, and you tell us with POST /v1/notes/{id}/sign.

Create a session

# 1. Create a session from recorded audio (sandbox: fictional data only)
curl https://sandbox.api.getmargent.com/v1/sessions \
  -H "Authorization: Bearer $MARGENT_API_KEY" \
  -H "Idempotency-Key: 7f9c2b1e-visit-48213" \
  -F client_id=cl_8Hq2N4 \
  -F template=birp \
  -F cpt_hint=90837 \
  -F audio=@session.m4a

# 2. Fetch the draft with sentence-level evidence
curl https://sandbox.api.getmargent.com/v1/sessions/ses_3kd92/note?include=evidence,findings \
  -H "Authorization: Bearer $MARGENT_API_KEY"

Response

GET /v1/sessions/ses_3kd92/note

{
  "id": "note_9Vb1x",
  "session_id": "ses_3kd92",
  "status": "draft",            // never "signed" until a clinician signs
  "template": "birp",
  "sections": [
    {
      "key": "behavior",
      "sentences": [
        {
          "text": "Client reports missing three of five shifts this week.",
          "evidence": [{ "type": "transcript", "start_ms": 312400, "end_ms": 318900, "speaker": "client" }],
          "verification": { "status": "supported", "confidence": 0.96 }
        },
        {
          "text": "Current medication: sertraline 100 mg daily.",
          "evidence": [{ "type": "chart", "ref": "medication/med_22" }],
          "verification": { "status": "supported", "source": "chart" }
        }
      ]
    }
  ],
  "coding": { "suggested_cpt": "90837", "minutes": 55, "rationale": "55 face-to-face minutes ≥ 53" },
  "findings": [
    { "id": "fnd_71", "rule_id": "plan.goal_reference", "severity": "high",
      "message": "No treatment-plan goal referenced.", "fix": { "type": "edit", "preview": "…(Goal 1, Objective 1a)…" } }
  ]
}

Core endpoints

Method	Path	What it does
POST	/v1/sessions	Create a session from audio, a live stream, or a recap
GET	/v1/sessions/{id}/note	Draft or signed note with evidence and findings
POST	/v1/notes/{id}/checks	Run note checks on any note text, including ones written elsewhere
PATCH	/v1/notes/{id}	Apply clinician edits (attributed to the user)
POST	/v1/notes/{id}/sign	Record a clinician's signature made in your product
GET	/v1/clients/{id}/measures	PHQ-9, GAD-7, C-SSRS and other scores over time
POST	/v1/live/token	Short-lived token for browser or mobile streaming capture
GET	/v1/audit-events	Append-only audit log, filterable by actor and resource

POST /v1/notes/{id}/checks runs note checks on any note text — including notes written in your own editor — and returns findings with the rule, its source, and a suggested fix.

Events

Webhooks

Subscribe to events instead of polling. Deliveries are signed with HMAC-SHA256, retried with exponential backoff for 24 hours, and carry IDs only — fetch PHI with an authenticated call so it never sits in a webhook log.

session.transcribedAudio processed; audio deleted
note.readyDraft and verification complete
note.findings_changedNote-check issues added or resolved
note.signedA clinician signed (and co-signed, if required)
note.deliveredDelivered to the EHR and verified by read-back
note.delivery_failedDelivery failed, with a reason code
intake.escalatedThe calls & referrals assistant detected risk and warm-transferred
routine.approval_requestedA routine step is waiting for staff approval

Delivery

POST https://your-app.example.com/margent/webhooks
Margent-Signature: t=1793360400,v1=5f2b…c9e1
Content-Type: application/json

{
  "id": "evt_0Jq8",
  "type": "note.signed",
  "created": "2026-10-30T16:20:00Z",
  "data": { "note_id": "note_9Vb1x", "session_id": "ses_3kd92", "signed_by": "usr_41", "cosign_required": false }
}

verify-signature.ts

import crypto from "node:crypto"

export function verifyMargentSignature(rawBody: string, header: string, secret: string) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=") as [string, string]))
  const age = Math.abs(Date.now() / 1000 - Number(parts.t))
  if (age > 300) return false // reject replays older than 5 minutes

  const expected = crypto.createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest("hex")
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1 ?? ""))
}

Standards

SMART on FHIR launch and write-back

Margent registers as a SMART App Launch v2 app. Launched from your EHR, it receives patient and encounter context, reads the problems, care plan, medications and observations it needs to tie the note to treatment plan goals, and — after a clinician signs — writes a DocumentReference using conditional create so retries never duplicate a note.

EHR launch → authorize → write-back

# 1. Your EHR launches Margent with a launch token
GET https://app.getmargent.com/smart/launch?iss=https://fhir.your-ehr.example/r4&launch=xyz123

# 2. Margent requests authorization (SMART App Launch v2, PKCE)
GET https://fhir.your-ehr.example/oauth2/authorize
  ?response_type=code
  &client_id=margent-smart
  &redirect_uri=https://app.getmargent.com/smart/callback
  &launch=xyz123
  &scope=launch openid fhirUser patient/Patient.rs patient/Condition.rs
         patient/CarePlan.rs patient/MedicationRequest.rs patient/Observation.rs
         user/DocumentReference.c
  &state=…&code_challenge=…&code_challenge_method=S256
  &aud=https://fhir.your-ehr.example/r4

# 3. After signing, Margent writes the note back (conditional create = idempotent)
POST https://fhir.your-ehr.example/r4/DocumentReference
If-None-Exist: identifier=https://getmargent.com/note|note_9Vb1x

As designed, notes from 42 CFR Part 2 programs will carry the 42CFRPart2 security label and the redisclosure notice.

DocumentReference (US Core)

{
  "resourceType": "DocumentReference",
  "status": "current",
  "docStatus": "final",
  "identifier": [{ "system": "https://getmargent.com/note", "value": "note_9Vb1x" }],
  "type": { "coding": [{ "system": "http://loinc.org", "code": "11506-3", "display": "Progress note" }] },
  "subject": { "reference": "Patient/123" },
  "context": { "encounter": [{ "reference": "Encounter/456" }] },
  "author": [{ "reference": "Practitioner/789" }],
  "meta": { "security": [{ "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode", "code": "42CFRPart2" }] },
  "content": [{ "attachment": { "contentType": "text/plain", "data": "QmVoYXZpb3I6IENsaWVudC…" } }]
}

Embed the review panel

Partners who want the evidence-linked review experience without building it can drop in our web component. It renders in your page, follows your light or dark theme, meets WCAG 2.2 AA, and hands the signed note back to your code.

index.html

<!-- Drop-in note review panel for partner EHRs -->
<script src="https://cdn.getmargent.com/embed/v1.js" defer></script>

<margent-note-review
  session="ses_3kd92"
  token="{{ short_lived_embed_token }}"
  theme="auto"
  on-signed="handleSigned">
</margent-note-review>

<script>
  function handleSigned(event) {
    // event.detail: { noteId, sections, cpt, minutes } — map into your own fields
    saveToChart(event.detail)
  }
</script>

Authentication and PHI

Keys and OAuth
Server keys for back-end calls; OAuth 2.0 client credentials with scopes such as notes:read and checks:write for partners. Keys are shown once and can be rotated without downtime.
Idempotency
Send an Idempotency-Key on every POST. Repeats within 24 hours return the original result instead of creating a second session.
No PHI in transit logs
Webhooks carry IDs only. Request and error logs are scrubbed of PHI before storage.
BAA first
Production keys are issued after a BAA (and QSOA for Part 2 data) is in place. The sandbox holds fictional data only.

Rate limits

Tier	Requests	Burst	Uploads
Sandbox	60 / min	10 / s	200 MB, 2 h audio
Production	600 / min	50 / s	1 GB, 6 h audio
Partner	Custom	Custom	Custom

Every response includes RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. A 429 includes Retry-After in seconds. Limits apply per organization, not per key.

Planned

Sandbox

Planned alongside the API: a copy seeded with fictional clients, sessions and treatment plans, including a CBT session with a deliberately unsupported sentence so you can see verification work. Until then, the live demo app runs the same engine on fictional data. No PHI allowed.

Join the design partners See the product it powers