Expert Chat API

The Expert Chat endpoint is the primary interface to the Secberus agents. It accepts a conversation and streams back a grounded, GRC-focused response built by the orchestrator. Use it for compliance questions, cross-framework synthesis, document validation, and to trigger workflows via slash commands.

POST /v1/expert
Property Value
Auth authorization: YOUR_API_KEY (required)
Content-Type application/json
Response text/event-stream (Server-Sent Events)

Request Body

Field Type Required Description
messages array[ExpertMessage] Yes Full conversation history. The last message must have role user.
frameworks array[string] No Framework IDs to scope context retrieval. Detected automatically if omitted.
document_ids array[string] No Uploaded document IDs to include as context (from the Documents API).

ExpertMessage Object

Field Type Required Description
role string Yes user or assistant
content string Yes Message text

Conversation history is passed in full on every call — the endpoint is stateless. To continue a conversation, append the assistant's previous reply (as a assistant message) and the new user message, then resend the whole array.

Streaming Response

The endpoint responds with a 200 OK and an SSE stream of tokens as the agent generates them. Each event carries a chunk of the answer; concatenate them in order to reconstruct the full response.

POST /v1/expert  →  200 OK
Content-Type: text/event-stream

data: Your access-control policy
data:  satisfies PCI DSS v4 requirement
data:  8.3.6 (minimum password length)…

With curl, use -N to disable buffering and see tokens arrive live:

curl -N -X POST https://compliance.secberus.ai/v1/expert \
  -H "authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "messages": [ { "role": "user", "content": "What does PCI DSS require for MFA?" } ] }'

Because the response is an event stream, set your HTTP client to read incrementally rather than waiting for a complete body. Most SSE and fetch-streaming libraries handle this for you.

Examples

Single question

curl -N -X POST https://compliance.secberus.ai/v1/expert \
  -H "authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "What MFA requirements must I satisfy under PCI DSS v4?" }
    ],
    "frameworks": ["pci_dss_v4"]
  }'

Cross-framework synthesis

Scope to two frameworks and the orchestrator will reconcile their requirements into a combined answer:

curl -N -X POST https://compliance.secberus.ai/v1/expert \
  -H "authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "What MFA requirements must a combined PCI DSS v4 and NIST 800-53 control satisfy?" }
    ],
    "frameworks": ["pci_dss_v4", "nist_800_53_r5"]
  }'

Validate an uploaded document

Reference a document from your corpus to have the agent check it against framework controls:

curl -N -X POST https://compliance.secberus.ai/v1/expert \
  -H "authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "Does my uploaded policy meet PCI DSS password requirements?" }
    ],
    "frameworks": ["pci_dss_v4"],
    "document_ids": ["doc_01h9z…"]
  }'

Multi-turn conversation

Resend the full history, including the assistant's prior turn:

curl -N -X POST https://compliance.secberus.ai/v1/expert \
  -H "authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "messages": [
      { "role": "user", "content": "What does PCI DSS require for password length?" },
      { "role": "assistant", "content": "PCI DSS v4 requirement 8.3.6 requires a minimum of 12 characters…" },
      { "role": "user", "content": "How does that compare to NIST 800-63B?" }
    ],
    "frameworks": ["pci_dss_v4", "nist_800_53_r5"]
  }'

Slash commands

If the last user message begins with /, it is interpreted as a structured workflow command rather than a free-form question. For example, /policy-coverage --frameworks pci_dss_v4 runs the coverage workflow and streams a per-control report. See Workflows for the full command reference, and list available commands with GET /v1/slash-commands.

Grounding behavior

  • Retrieval-first. The agent retrieves relevant control text and document passages before answering, and cites the framework and control IDs it used.
  • Automatic framework detection. If you omit frameworks, the orchestrator infers the relevant ones from your question.
  • Scoped to GRC. Questions outside governance, risk, and compliance are declined rather than answered from general knowledge.

Error Responses

Errors are returned (before the stream starts) in RFC 7807 format:

{
  "requestid": "req-abc123",
  "http_status": 400,
  "title": "Bad Request",
  "detail": "messages must not be empty; last message must have role \"user\""
}
Status Description
400 Bad Request — malformed body, empty messages, or last message not user
403 Forbidden — invalid or missing API key
500 Internal Server Error — contact support if persistent
Quick Start Policy Coverage