API log

When an agent calls the API and something goes wrong, the answer alone rarely says why. The API log keeps one row per authenticated call: the request id, the method, the path, the status, the duration, the key id and the SDK recognised from the User-Agent. Reading it needs audit_read, which a member never holds, so the log is an owner and admin surface.

Read it

curl -s https://api.mueslimail.com/v0/logs?limit=20 \
  -H "Authorization: Bearer ***"

Filters: key_id, method, status, sdk, after and before (RFC 3339, before exclusive, which is how you page). GET /v0/logs/{log} returns the same row with ip, user_agent and the two redacted bodies. A row of another organization is 404, never 403.

What is redacted, and how you can tell

• A credential field (authorization, secret, api_key, token, password, cookie) becomes {"redacted": "credential"}.
• A mail field (subject, text, html, raw, attachment content) becomes {"redacted": "mail_content", "bytes": N, "content_type": "...", "sha256": "..."}.
• A header outside the allowlist (accept, content-type, idempotency-key, user-agent, x-mai-api-version, x-request-id) is not kept at all, and its name is listed when it was a credential header.
• Anything that looks like a token, a whsec_ signing secret or a bearer value is masked even inside a free text field.
• redactions names every removal, as header:authorization, mail_content:html or credential:secret: the list is the proof, not the promise.
• A response body that is not JSON or markdown is not stored at all; bytes and sha256 still describe it.

SDK and version

The User-Agent of our own SDKs carries the name and the version (aimulti-node/1.2.0, aimulti-go/v1). The log normalises it into sdk and sdk_version, compares it with the newest version this deployment knows and sets sdk_update_available with a sentence a person can act on. Nothing is fetched from outside: MAI_SDK_LATEST (node=1.3.0,go=1.1.0) is what the comparison uses, so shipping a new client does not need a new API release. The same notice arrives as the X-Mai-Sdk-Update header on the call itself, so an integrator sees it without opening the console.

Copy for an assistant

GET /v0/logs/{log}/export answers text/markdown: the shape of the call, the redacted bodies and an explicit list of what the log does not contain. It is a copy a person pastes where they work, not an integration: nothing is sent to a third party and no external service is called.

Retention

Seven days, enforced by the retention job: the row is deleted by age and not by request. The table is in the same purge job and the same weekly restore drill as every other table, so the published window is a fact and not a target.