Compliance API

The compliance API gives your organization's own security, legal and compliance team the records Strata keeps: who your members are, how your organization is set up, and every conversation with its messages and files. Pull them into your archive, eDiscovery platform or SIEM, and erase a conversation or a file when a request or an incident calls for it.

Activity (who did what, when) comes from the audit trail at GET /v1/audit. The compliance API is the content half beside it.

#Two scopes: reading and deleting

No role holds View member chats at first; an admin who holds Manage member-chat oversight switch grants it in a role of its own (Granting View member chats). They are separate on purpose: a key that reads your conversations can never erase one. Give each its own key, and give a deletion key only to the system or person that handles erasure requests. An admin cannot grant a scope for something they could not do themselves; trying returns 403 with the code COMPLIANCE_SCOPE_REQUIRES_PERMISSION. See API keys.

#Conversations need member chat oversight

Reading conversations and their files follows the same rule as an admin reading them in Strata: your organization's Member chat oversight switch must be on (Organization› then Data and privacy). When it is off, those calls return 403 with the type oversight_off. The directory and the settings do not depend on it.

#Everything is scoped to the key's organization

Every call reads the organization the API key belongs to and nothing else. An id from another organization is 404, the same answer as an id that does not exist.

#Endpoints

#Listing conversations

GET /v1/compliance/conversations takes:

limit

Rows per page, up to 500 (default 100)

cursor

The next_cursor from the previous page. A cursor this API did not issue returns 400 invalid_cursor

user_id

One member's conversations only

since, until

Changed at or after since, and before until (ISO 8601)

include_deleted

true also lists conversations a member deleted

A member who deletes a chat only hides it: Strata keeps it until your organization's retention period removes it, so include_deleted=true shows what is still kept. Page with cursor until has_more is false. For a nightly pull, record the newest updated_at you stored and pass it as since next time.

GET /v1/compliance/users pages the same way, with limit and cursor.

#Reading a conversation

GET /v1/compliance/conversations/{conversation_id} returns the conversation and every message, including older ones Strata has moved to archive and cold storage. Each message carries its parent_message_id, so edited prompts and retried answers keep their branches. When older messages could not be read, the response says incomplete: true rather than passing part of a conversation off as all of it.

#Deleting

DELETE /v1/compliance/conversations/{conversation_id} erases the conversation, its messages (archived and cold copies included), its files and its shares. DELETE /v1/compliance/conversations/{conversation_id}/files/{file_id} erases one file.

• A legal hold stops it. When the member is under a legal hold, the delete is refused with 409 and the type legal_hold, naming the hold, and the refusal is recorded. Release the hold first.
• Files created by Analysis live in a separate store that this call cannot reach yet; that store's lifecycle rule removes them within 180 days.
• A delete cannot be undone.

#What the API records

Your audit trail shows every use of the compliance API, with the API key named the way the API keys page names it:

• reading a conversation, its file list or a file: member_chat.viewed, member_chat.files_viewed, member_chat.file_downloaded, the same rows an admin's reading writes;
• a list or directory pull: compliance.conversations_listed and compliance.directory_read, once per walk;
• deletes: compliance.conversation_deleted and compliance.file_deleted; a refusal under a hold: legal_hold.blocked.

#Errors

Errors are application/problem+json (Errors). The ones particular to this API:

#Related

• Audit trail (SIEM)
• API keys
• Legal holds