API Reference
Sentinel exposes a tenant REST API and a secure AI connector (Model Context Protocol). The connector is the supported way for an external AI client to work with a matter's documents; the REST API primarily serves Sentinel's own web app and service clients.
This reference covers authentication, API‑key management, the public health endpoints, the connector tool catalog, and a representative set of REST endpoints.
Base URL. In production, Sentinel's web UI (a static site) and its API are on different hosts. Call the tenant API host, not the web‑app host. Your tenant's API base URL is available from your administrator. All API paths below are under
/api.
Authentication
Every /api/* request must be authenticated. Two schemes are supported.
Bearer JWT (browser sessions)
Authorization: Bearer <jwt>
Short‑lived (15‑minute) JSON Web Tokens issued by Sentinel's control plane when a user signs in. Used by the web app. These carry the user's identity, role, and tenant.
API key (service‑to‑service)
Authorization: ApiKey sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Long‑lived, revocable keys for programmatic and service clients. Key facts:
- Format:
sk_live_followed by 32 hex characters (40 characters total, 128 bits of entropy). - Only a SHA‑256 hash of the key is stored. The raw key is shown once at creation and is never recoverable afterward.
- A short prefix (e.g.
sk_live_a1b2) is stored for display so you can identify a key without seeing the secret. - Keys are revocable per‑row; revocation takes effect immediately. Keys may carry an optional expiry.
- A key inherits a role (no higher than the creator's), and that role bounds what the key can do.
For OAuth‑based clients (such as an enterprise Claude marketplace connector), an
OAuth client_credentials flow issues an API key that is then presented as a
bearer token (Authorization: Bearer sk_live_...).
Key management is session‑only
API‑key management endpoints accept only a Bearer JWT — an API key cannot create or revoke keys. This prevents a leaked key from minting more keys.
API‑key management endpoints
| Method | Path | Auth | Purpose |
|---|---|---|---|
POST |
/api/api-keys |
JWT only | Create a key (name, optional role ≤ caller's, optional expiresInDays). Returns the raw key once. |
GET |
/api/api-keys |
JWT only | List keys (admins: all tenant keys; others: own). Returns public fields only — never raw keys. |
DELETE |
/api/api-keys/:id |
JWT only | Revoke a key (owner or admin). Idempotent. |
Creating, listing, and revoking keys is also available in the app at the API Keys admin page (see Administration → API keys).
Public endpoints (no auth)
| Method | Path | Returns |
|---|---|---|
GET |
/api/version |
{ service, commit, buildTime } — the running build. |
GET |
/api/health |
Health status (including DB), plus the same build identifiers. |
These are handy for verifying exactly what's deployed.
The Sentinel connector (MCP)
The connector lets a compatible AI client operate on a matter through a defined tool set. It speaks the Model Context Protocol, so the client discovers each tool's input schema automatically. Key properties:
- Authentication — the connector authenticates with an API key (above).
- Access control — every tool enforces the same matter‑access rules as the app. Read tools require read access to the matter; write tools require full access.
- Auditing — every tool call writes an audit record: which tool, by whom, with what arguments, the result size, the duration, and any error.
Read tools
| Tool | Purpose |
|---|---|
list_matters |
List the matters the caller can access (cases and deals). |
get_matter |
Get a single matter's details (title, status, priority, type, description). |
get_matter_summary |
An AI executive summary of a matter. |
search_documents |
Search a matter's documents. mode is required: keyword, semantic, hybrid, or visual. Optional filters: custodianName, senderEmail, documentType. Returns ranked hits with snippets. |
get_document_text |
Full extracted text + metadata for a document, with a viewer link. |
get_case_timeline |
The matter's chronology of events with risk levels. |
get_focus_issues |
High‑priority issues/contradictions tracked on the matter. |
get_detected_issues |
AI‑detected risks and inconsistencies. |
get_privilege_log |
Privileged / work‑product documents recorded for the matter. |
get_email_threads |
Email conversations grouped by thread. |
get_thread_messages |
Messages within a single email thread. |
list_recorded_statements |
Recorded video/audio statements (e.g. interviews) for a matter. |
get_recorded_statement |
A single recorded statement's transcript and metadata. |
search_recorded_statements |
Search across recorded‑statement transcripts. |
verify_citations |
Validate document references in a draft against the matter's documents. |
Write tools
Write tools require full access to the matter.
| Tool | Purpose |
|---|---|
tag_documents |
Add or remove tags on a set of documents. |
tag_documents_by_query |
Tag documents matching a search query. |
code_documents |
Assign or clear a review code on a set of documents. |
code_documents_by_query |
Code documents matching a search query. |
create_finding |
Create a notebook entry (note, theory, legal issue, contradiction, etc.) with optional linked evidence. |
add_to_focus_issue |
Append analysis to an existing focus issue. |
The connector's tool set (used by external clients) is related to but distinct from Emma's in‑app tools (which also include navigation and review‑UI actions). See Emma.
Representative REST endpoints
Beyond the endpoints above, the tenant API backs the web app across matters, documents, search, productions, administration, and integrations. A representative selection:
| Area | Example endpoints |
|---|---|
| Matters | GET /api/matters, GET /api/matters/:matterId, document sub‑routes under a matter |
| Tenant settings | GET /api/tenant-settings, PUT /api/tenant-settings (admin) |
| Users & access | GET/POST /api/users, password/2FA reset, matter team assignment (admin) |
| Audit | GET /api/audit-logs (admin) |
| Data‑room sharing | guest‑share verification and email‑link endpoints |
| Court import | GET /api/court-import/providers, GET /api/court-import/search, bulk‑create |
| Mailbox sync | GET /api/sentinel-sync/status, monitored‑user authorization |
These first‑party endpoints exist primarily to serve Sentinel's own client and may evolve. For a stable, supported integration, prefer the connector and the API‑key auth above. If you need a documented contract for a specific REST endpoint, contact Sentinel.
Conventions
- Access denials. Routes keyed on a single resource ID return 404 when access is denied (rather than 403), so resource IDs can't be enumerated. List endpoints filter results to what you can access rather than failing the whole call.
- Roles. Your role (and, for keys, the key's inherited role) bounds what you can do; many admin endpoints require the admin role.
- Write access. Mutating a matter requires full access to that matter.