Coming soon · Private pilotProposed v1 surface

Chat API preview

A static review surface for the planned Chat contract: scoped sessions, conversations, membership, messages, read state, safety workflows, realtime events, and retry semantics.

Contract notice: every route, schema, field, status, and tool on this page is a proposed private-pilot contract subject to change. This is not an interactive production API reference and does not indicate general availability.

Contract shape

Explicit tenant scope, predictable resources, recoverable delivery.

The proposed surface uses resource-oriented HTTP for application clients, a matching Connect/gRPC domain contract for backend clients, and WebSocket event delivery for responsive product interfaces. Durable history remains the recovery source of truth.

Authentication

Scoped session token

Authorization

Tenant + membership + policy

Retry safety

Idempotency key

Realtime

Recoverable WebSocket

Proposed request rules

Authorization

Bearer tokens are scoped to tenant, environment, principal, and allowed actions.

Tenant context

The tenant is derived from validated credentials; callers do not switch it with a free-form header.

Idempotency

Create and mutation retries use an Idempotency-Key and domain-specific client identifier where applicable.

Pagination

Lists use opaque cursors. Message history also exposes conversation sequence for recovery.

Field updates

PATCH requests name intended fields so omitted values are not confused with deletion.

Traceability

Responses and errors include a request identifier suitable for operational correlation.

Proposed private-pilot routes

Sessions

Exchange trusted application context for narrowly scoped Chat access.

POST/v1/chat/sessions

Create a chat session

Requests tenant, user, environment, and action scopes from a trusted application boundary.

POST/v1/chat/realtime-tickets

Create a realtime ticket

Issues a short-lived, single-purpose ticket for a permitted WebSocket connection.

Proposed private-pilot routes

Conversations

Create and retrieve tenant-scoped direct, group, and channel conversations.

POST/v1/conversations

Create a conversation

Creates a conversation with kind, initial members, policy, and optional product metadata.

GET/v1/conversations

List conversations

Returns conversations visible to the current principal using cursor pagination and filters.

GET/v1/conversations/{conversation_id}

Get a conversation

Returns the permitted conversation projection, membership, and current sequence state.

PATCH/v1/conversations/{conversation_id}

Update a conversation

Updates allowed metadata or settings after membership and Authz checks.

Proposed private-pilot routes

Members

Manage membership, roles, mute state, and participant lifecycle.

POST/v1/conversations/{conversation_id}/members

Add a member

Adds a user when the caller can manage membership in the conversation.

PATCH/v1/conversations/{conversation_id}/members/{user_id}

Update a member

Changes allowed role, mute, or notification state with explicit field selection.

DELETE/v1/conversations/{conversation_id}/members/{user_id}

Remove a member

Ends membership while retaining the durable conversation history required by policy.

Proposed private-pilot routes

Messages

Publish, page, edit, soft-delete, reply to, and react to durable messages.

POST/v1/conversations/{conversation_id}/messages

Publish a message

Accepts retry-safe message content, reply context, and validated attachment references.

GET/v1/conversations/{conversation_id}/messages

List message history

Returns durable history before or after a sequence cursor for paging and recovery.

PATCH/v1/messages/{message_id}

Edit a message

Applies an allowed content edit while preserving revision metadata.

DELETE/v1/messages/{message_id}

Soft-delete a message

Removes visible content according to role and policy without erasing required operational history.

POST/v1/messages/{message_id}:react

Set a reaction

Adds or removes the principal’s reaction with idempotent semantics.

Proposed private-pilot routes

Read state and search

Synchronize product state and locate content inside the caller’s permitted scope.

PUT/v1/conversations/{conversation_id}/read-state

Advance read state

Moves the principal’s last-read sequence forward without allowing a stale client to move it backward.

GET/v1/messages:search

Search messages

Searches only conversations and fields visible to the current tenant-scoped principal.

Proposed private-pilot routes

Safety and moderation

Report content and apply policy-controlled moderation actions with an audit boundary.

POST/v1/messages/{message_id}:report

Report a message

Records a structured user report for product-defined moderation handling.

POST/v1/conversations/{conversation_id}:moderate

Apply a moderation action

Performs an allowed hide, remove, mute, block, or membership action with policy and audit context.

Message example

Acknowledge durable state, then distribute the event.

The target publish contract makes client retries explicit. A successful response represents a committed message and outbox entry; realtime and downstream processing follow through asynchronous delivery.

Publish message requestJSON · proposed private-pilot contract

{
  "client_message_id": "client_message_9c12",
  "text": "Release checklist is ready",
  "reply_to_message_id": null,
  "attachment_ids": ["media_01J..."]
}

Publish message responseJSON · proposed private-pilot contract

{
  "message": {
    "id": "msg_01J...",
    "conversation_id": "conv_product",
    "sequence": 1842,
    "sender_id": "user_42",
    "text": "Release checklist is ready",
    "created_at": "2026-07-16T10:24:00Z"
  }
}

Realtime events

The proposed WebSocket stream delivers tenant-scoped events after a client exchanges its chat session for a realtime ticket. Clients deduplicate by event identity, apply per-conversation sequence, and recover missing ranges through the history endpoint.

Realtime event envelopeJSON · proposed private-pilot contract

{
  "event_id": "evt_01J...",
  "type": "chat.message.created.v1",
  "tenant_id": "tenant_acme",
  "conversation_id": "conv_product",
  "sequence": 1842,
  "occurred_at": "2026-07-16T10:24:00Z",
  "payload": {
    "message_id": "msg_01J...",
    "sender_id": "user_42"
  }
}

Durable event families

conversation, membership, message, reaction, read state, and moderation changes

Ephemeral event families

typing, presence, connection hints, and transient delivery signals

Ordering

monotonic sequence inside a conversation; no global event order

Delivery

at-least-once with event-id deduplication and durable-history recovery

Errors and retries

Errors use machine-readable codes and an explicit retry hint. Clients should retry only retryable failures, preserve the idempotency key, and use bounded backoff. Authorization failures are not converted into empty successful responses.

Error envelopeJSON · proposed private-pilot contract

{
  "error": {
    "code": "conversation_access_denied",
    "message": "The principal cannot perform this action.",
    "request_id": "req_01J...",
    "retryable": false,
    "details": []
  }
}

Proposed error handling categories
Category	Client behavior
Validation	Correct the request; do not retry unchanged.
Authentication	Refresh the valid application or chat session.
Authorization	Stop and surface the denied action without probing adjacent resources.
Conflict	Refresh durable state and reconcile the intended update.
Rate or capacity	Honor server guidance and retry with bounded backoff when marked retryable.

Governed agent boundary

Agent tools are served through Agent Gateway—not directly from Chat.

There is no proposed unrestricted Chat MCP endpoint. The private-pilot tool catalog is mediated by Agent Gateway so tenant and environment scope, tool allowlists, read or write access, budgets, policy, expiry, revocation, approvals, and Audit Log events remain enforceable.

chat.list_conversationsRead

Lists conversations inside the agent’s explicit scope.

chat.get_messagesRead

Retrieves permitted durable history with a cursor.

chat.search_messagesRead

Searches only authorized tenant and conversation content.

chat.send_messageApproval required

Publishes the pilot write only after an approval decision.

Review Agent Gateway controls

Next step

Validate the contract against a real product workflow.

Private-pilot discussions start with your participant model, moderation boundary, attachment needs, client platforms, workload shape, recovery expectations, and customer-cloud constraints.

Request private-pilot access Read technical preview

Related services

Identity Authz Notifications Media

Related use cases

Consumer applications AI platforms Enterprise deployment