Interactive API documentation is available at:

Most /api/v1/* endpoints require Authorization: Bearer <token>. Two exceptions: GET /api/v1/features is public, and the one-time /api/v1/exports/download/{ticket} URL carries its own credential. GET /api/status and POST /api/login are also public.

Authentication EndpointsCopy Anchor Link

• POST /api/login — Authenticate and receive a JWT token
• POST /api/auth/mfa/verify — Complete a login that requires TOTP

Tokens are stateless JWTs; there is no server-side logout endpoint. Discard the token client-side (or revoke the API token that issued it).

API Token ManagementCopy Anchor Link

• GET /api/v1/access-token-list — List all API tokens
• POST /api/v1/access-token — Create a new API token
• DELETE /api/v1/access-token/{token} — Revoke an API token

License (Pro)Copy Anchor Link

• GET /api/v1/license/status — Active status, edition, account limit and usage
• GET /api/v1/license/machine-id — This deployment's machine ID
• POST /api/v1/license/upload — Install a license (system:root)
• GET /api/v1/features — Active edition and feature flags

See Licensing & Trials.

MetricsCopy Anchor Link

• GET /api/v1/metrics — Prometheus text exposition (requires system:metrics)

See Monitoring & Metrics.

Compliance & Audit (Pro/Enterprise)Copy Anchor Link

Full request and response schemas are in the interactive API documentation, and each area is described in Audit Log & Integrity, Dual Control, Legal Hold, GDPR Erasure Requests, and SIEM Forwarding.

Account ManagementCopy Anchor Link

• GET /api/v1/accounts — List all accounts
• POST /api/v1/account — Create an account
• GET /api/v1/account/:account_id — Get account details
• POST /api/v1/account/:account_id — Update account configuration (retention fields rejected)
• POST /api/v1/account/:account_id/retention — Change retention policy (root only; weakening changes may queue for approval)
• DELETE /api/v1/account/:account_id — Remove an account
• POST /api/v1/accounts/:account_id/start-download — Start manual download
• POST /api/v1/accounts/:account_id/cancel-download — Cancel download

Search & MessagesCopy Anchor Link

• POST /api/v1/search-messages — Full-text search across messages
• POST /api/v1/search-attachment — Search attachments
• GET /api/v1/message-content/:account_id/:envelope_id — Get a message with parsed content
• GET /api/v1/download-message/:account_id/:envelope_id — Download raw EML
• GET /api/v1/download-attachment/:account_id/:envelope_id — Download an attachment
• GET /api/v1/get-thread-messages/:account_id — Reconstruct a thread
• GET /api/v1/all-contacts — Aggregated contacts
• POST /api/v1/delete-messages — Delete explicitly listed messages. Body: { "<account_id>": ["<envelope_id>", …] } — the key is the account ID, not the mailbox ID; each value is the envelope id UUID returned by search-messages
• POST /api/v1/restore-messages/:account_id — Push archived messages back to their source IMAP server (not an undo of deletion)

Batch deletionCopy Anchor Link

Deletion is permanent (there is no trash). The job enumerates the filter once, when it starts, and deletes that point-in-time set in batches of 500; mail arriving afterwards is not touched. Deleted messages are recorded as tombstones, so a later gap-fill or full re-sync does not bring them back. A second job cannot run while one is in progress.

With dual control enabled for message.delete, the request queues instead of starting a job, and records the exact frozen id set (not the filter) that the approver signs.

Preview fields, the per-account permission split, job statuses, tombstones, legal hold and recovery limits are described in Batch Deletion.

SortingCopy Anchor Link

POST /api/v1/search-messages accepts an optional sort_by (and desc boolean):

Behavior details:

• The API default is DATE, but when the query carries a full-text term and no sort is requested, the server defaults to RELEVANCE — a date-descending default would bury the best match under the newest mail.
• RELEVANCE is always descending (higher score = more relevant); the desc flag is ignored for it.
• An explicit RELEVANCE with no text term in the query falls back to DATE — there is no score to order by.

TagsCopy Anchor Link

• POST /api/v1/update-tags — Add or remove tags on messages
• GET /api/v1/all-tags — All tags with document counts

Saved SearchesCopy Anchor Link

• GET/POST /api/v1/saved-searches — List / create
• PATCH/DELETE /api/v1/saved-searches/:id — Rename / delete one

Import & ExportCopy Anchor Link

• POST /api/v1/import — Import raw EML (Base64-encoded payload)
• POST /api/v1/upload-import — WebUI file upload path
• POST /api/v1/exports/preview — Preview an export's scope (saved search or ad-hoc filter)
• POST /api/v1/exports — Start an export job (MBOX of messages, or a ZIP of attachments)
• GET /api/v1/exports — List export jobs
• GET /api/v1/exports/:job_id — Export status
• POST /api/v1/exports/:job_id/cancel — Cancel a running job
• DELETE /api/v1/exports/:job_id — Delete a job and its artifact
• GET /api/v1/exports/:job_id/download — Download the artifact
• POST /api/v1/exports/:job_id/download-ticket — One-time, 60-second download URL
• POST /api/v1/exports/:job_id/verify — Verify the artifact (Pro)

preview and create take either saved_search_id or an ad-hoc filter ({"email": …} / {"attachment": …}), plus an optional label and format ("Mbox" or "Attachments"). See Import & Export.

For the complete API reference with request/response schemas, visit the interactive API documentation on your Bichon instance.