Docs / Obsidian Suite / Reference

REST API

The REST API lets your PSA or helpdesk tools and your own scripts read statistics, search messages, release or delete quarantined mail, manage allow and block lists, and send secure messages.

Tokens

API tokens are issued by Larström Technologies: contact us with what the token is for. A token is scoped to your organization: it only sees and changes your organization's mail and lists. We give you the token once; only a hash of it is stored, so keep it safe. Its name appears in your audit log as api:<name> for every change it makes. Ask us to revoke a token you no longer need, or one that may have leaked; that takes effect immediately.

Calling the API

The base URL is https://portal.obsidiansuite.net/api/v1. Send the token as a bearer header. All responses are JSON.

curl -H "Authorization: Bearer obs_xxxxxxxx" "https://portal.obsidiansuite.net/api/v1/stats?hours=24"

The machine-readable schema is at https://portal.obsidiansuite.net/api/openapi.json.

Errors return {"error": "..."} with status 400 (bad request), 401 (missing or invalid token), 403 (outside the token's scope) or 404 (not found, or not in your organization).

Endpoints

GET /api/v1/health

The service version and whether the virus scanner answers.

GET /api/v1/stats

Message counts per verdict. Parameter hours (default 24, up to 90 days).

{"hours": 24, "by_verdict": {"clean": 812, "spam": 40, "phish": 2}}

GET /api/v1/messages

Search messages. Parameters:

Each message has id, received_at, direction, from, mail_from, subject, score, verdict, action, reason, message_id, recipients (each with its status) and ai (the AI verdict, when the model reviewed it). Newest first.

GET /api/v1/messages/{id}

One message, with details: every scan stage's data.

POST /api/v1/messages/{id}/release

Releases to every quarantined recipient, or only to those in an optional JSON body {"rcpts": ["[email protected]"]}. Returns {"ok": true, "info": "..."}.

POST /api/v1/messages/{id}/delete

Deletes the message from quarantine. Returns {"ok": true, "info": "..."}.

POST /api/v1/lists

Adds an allow or block entry to your organization's list:

{"kind": "block", "pattern": "@bad.example", "note": "ticket 1234"}

kind is allow or block. pattern takes the list entry formats. Returns {"ok": true, "info": "..."}.

Secure messages

For a mail client that sends a message encrypted for any recipient. The client encrypts the message itself with AES-256-GCM and a new 256-bit key per message. The envelope is base64(iv[12] || ciphertext || tag[16]) with the additional authenticated data obsidian-secure-v1. The plaintext is JSON: {"v": 1, "subject", "from", "text", "html", "sent", "attachments": [{"name", "type", "data"}]} (attachment data in base64); a reply is {"v": 1, "from", "text", "sent"}.

POST /api/v1/secure-messages

{"sender": "[email protected]", "sender_name": "Your Name", "recipients": ["[email protected]"], "ciphertext": "<base64>", "expires_days": 30}

Up to 25 MB of encrypted data and 50 recipients; expires_days defaults to 30 and is limited by the service maximum. Returns the message's id, link, expires_at and status. Send the recipients the link with #k=<key> appended, the key encoded as base64url without padding (43 characters). The key never goes to the server.

GET /api/v1/secure-messages/{id}

Status: expires_at, revoked, opened (who opened it, when) and the number of replies.

GET /api/v1/secure-messages/{id}/replies

The recipients' answers, encrypted with the message's key: {"replies": [{"id", "from", "created_at", "ciphertext"}]}.

DELETE /api/v1/secure-messages/{id}

Withdraws the message: nobody can open it any more, and its data is deleted.