Skip to content
Chatto v0.5.0

API Overview

Chatto exposes a protobuf-first integration API over ConnectRPC at /api/connect. Use it for bots, integrations, admin tooling, and alternate clients that need the same public contract as the bundled web app.

ConnectRPC lets the same generated protobuf service work with the Connect, gRPC, and gRPC-Web protocols. For simple debugging you can also call unary RPCs as JSON over HTTP.

Every ConnectRPC service method is mounted below /api/connect:

https://chat.example.com/api/connect/<fully-qualified-service>/<method>

Replace chat.example.com with the host of the Chatto server you want to interact with.

For example, public server discovery is:

POST /api/connect/chatto.discovery.v1.ServerDiscoveryService/GetServer

chatto.discovery.v1 server discovery is unauthenticated. Most other documented ConnectRPC services require an Authorization: Bearer <token> header or a browser session when called by the bundled web client.

Open this URL to get the public server discovery JSON. No authentication or query parameters are required:

https://chat.example.com/.well-known/chatto

This URL returns the same response as ServerDiscoveryService.GetServer. It supports cross-origin reads and ETag revalidation with If-None-Match.

ConnectRPC methods that support GET also accept an omitted message parameter for an empty request when encoding=json or encoding=proto and no compression parameter is set:

https://chat.example.com/api/connect/chatto.discovery.v1.ServerDiscoveryService/GetServer?connect=v1&encoding=json

For request fields, supply the encoded message parameter. Required fields and authentication rules still apply. Methods that do not support GET still require POST.

Resource Update* methods use update_mask to select editable fields. Unselected fields stay unchanged. A selected field without a value resets to its default or absence, subject to validation. Selected lists replace the previous list, including with an empty list.

In JSON, use a comma-separated camelCase string: {"updateMask":"timezone,shareTimezone","timezone":null,"shareTimezone":false}. Generated clients use snake_case paths in FieldMask.paths. An omitted mask selects populated fields; an explicit empty mask is invalid. Prefer explicit paths to *, which selects all editable fields. See the update migration guide for reset rules and command renames.

ServerDiscoveryService.GetServer is public so clients can discover branding, registration state, and login providers before a user signs in.

chatto.auth.v1 external-identity confirmation calls are public but require short-lived capability tokens produced by the browser auth flow. See External Login Providers for login-provider discovery and sign-in configuration.

Most chatto.api.v1 calls require an authenticated user. Non-browser clients should send Authorization: Bearer <token>; browser clients can use the active Chatto session.

chatto.admin.v1 calls require authentication. Mutating calls and sensitive reads require the relevant server permission; a few catalog/layout reads are intentionally available to any authenticated user so clients can render assigned roles and sidebar layout. See Permissions & Roles for the permission model.

The API is split by who uses each part and how clients connect to it.

chatto.discovery.v1

  • Transport: ConnectRPC unary RPCs.
  • Covers: Pre-authentication bootstrap, such as server metadata and login discovery.
  • Contract: Public discovery API for clients that do not have a normal Chatto session yet.

chatto.auth.v1

  • Transport: ConnectRPC unary RPCs.
  • Covers: Public external-identity confirmation steps backed by short-lived capability tokens.
  • Contract: Narrow auth-flow API for the bundled client and compatible login integrations.

chatto.api.v1

  • Transport: ConnectRPC unary RPCs.
  • Covers: Normal authenticated client and integration behavior: profile reads, room navigation, messages, reactions, notifications, calls, attachments, and preferences.
  • Contract: Public client API for integrations, bots, alternate clients, and the bundled web app.

chatto.admin.v1

  • Transport: ConnectRPC unary RPCs.
  • Covers: Server administration: settings, room layout, members, roles, permissions, diagnostics, and audit reads.
  • Contract: Public administrative API for tools used by server owners and administrators. Calls require authentication; mutating calls and sensitive reads require the relevant permission.

chatto.realtime.v1

  • Transport: WebSocket protobuf frames at /api/realtime.
  • Covers: Realtime event delivery and client synchronization.
  • Contract: Public realtime wire protocol. It is documented separately because it is not a ConnectRPC service.

This split makes it clear which calls are for ordinary client behavior, which calls are administrative, and which protocol handles live updates.

Chatto exposes unauthenticated gRPC-compatible reflection for the public ConnectRPC API:

/api/connect/grpc.reflection.v1.ServerReflection/ServerReflectionInfo
/api/connect/grpc.reflection.v1alpha.ServerReflection/ServerReflectionInfo

Reflection lets tools resolve service and message descriptors without a local copy of the .proto files. Chatto limits reflection to public descriptors plus required imports.

Because Chatto mounts ConnectRPC under /api/connect, use tools that accept a full Connect URL, such as buf curl. gRPC tools that only dial services at the host root need a proxy or path rewrite.

The Connect protocol accepts JSON for unary requests, which makes ServerDiscoveryService.GetServer easy to test with ordinary HTTP tools:

Terminal window
curl -X POST \
-H "Content-Type: application/json" \
-H "Connect-Protocol-Version: 1" \
-d '{}' \
https://chat.example.com/api/connect/chatto.discovery.v1.ServerDiscoveryService/GetServer

Use the short-lived access token from a renewable bearer session for external clients. Persist and rotate its refresh credential as described in Using the Chatto API. This example calls ViewerService.GetViewer.

Terminal window
curl -X POST \
-H "Content-Type: application/json" \
-H "Connect-Protocol-Version: 1" \
-H "Authorization: Bearer $CHATTO_TOKEN" \
-d '{}' \
https://chat.example.com/api/connect/chatto.api.v1.ViewerService/GetViewer

Reflection-backed protobuf call with buf curl

Section titled “Reflection-backed protobuf call with buf curl”

buf curl uses protobuf schemas and can speak the Connect, gRPC, or gRPC-Web protocols. It accepts request data as protobuf JSON for CLI ergonomics, then uses reflection to resolve the request and response types. This example calls ServerDiscoveryService.GetServer over the Connect protocol:

Terminal window
buf curl --protocol connect \
-d '{}' \
https://chat.example.com/api/connect/chatto.discovery.v1.ServerDiscoveryService/GetServer

For a local plaintext server, use HTTP/2 prior knowledge. You can also switch to gRPC protobuf framing with --protocol grpc:

Terminal window
buf curl --http2-prior-knowledge \
--protocol grpc \
-d '{}' \
http://localhost:4000/api/connect/chatto.discovery.v1.ServerDiscoveryService/GetServer

Add -v to see the reflection request before the actual RPC. The first request resolves the schema through /api/connect/grpc.reflection.v1.ServerReflection/ServerReflectionInfo; the second request calls your target service.

Generated clients and buf curl are usually easier, but unary Connect calls can also use raw protobuf wire bytes. Send Content-Type: application/proto; the request body is the serialized protobuf request message, and the response body is the serialized protobuf response message.

ServerDiscoveryService.GetServer has an empty request message, so an empty binary body is valid:

Terminal window
curl -X POST \
-H "Content-Type: application/proto" \
--data-binary "" \
--output get-server.bin \
https://chat.example.com/api/connect/chatto.discovery.v1.ServerDiscoveryService/GetServer

get-server.bin contains a protobuf-encoded GetServerResponse. Decode it with generated code or a protobuf tool that has the Chatto schema.

Generated clients use /api/connect as their base URL. The client appends the service and method path. Set useBinaryFormat: true when you want the Connect-Web client to send and receive binary protobuf instead of JSON.

import { createClient } from "@connectrpc/connect";
import { createConnectTransport } from "@connectrpc/connect-web";
import { ServerDiscoveryService } from "./gen/chatto/discovery/v1/server_connect";
const transport = createConnectTransport({
baseUrl: "https://chat.example.com/api/connect",
useBinaryFormat: true,
});
const discovery = createClient(ServerDiscoveryService, transport);
const server = await discovery.getServer({});

For authenticated calls, pass request headers through the generated client call options:

const viewer = await viewerClient.getViewer({}, {
headers: { Authorization: `Bearer ${token}` },
});

Commands that only acknowledge success return a named empty response ({} in JSON). Use RPC completion to detect success. Fields that report an actual change, state, or count remain part of the response.

Successful unary JSON calls return the protobuf response message as JSON. Field names use protobuf JSON casing, such as publicProfile and directRegistrationEnabled.

Use the ProtoJSON mapping when you read or write JSON directly:

Protobuf typeJSON representation
64-bit integerDecimal string, such as "123".
32-bit integerNumber, such as 123.
google.protobuf.TimestampRFC 3339 string, such as "2026-09-10T12:00:00Z".
EnumSymbolic protobuf name; unknown numeric values can appear as numbers.
bytesBase64 string.
google.protobuf.FieldMaskComma-separated paths in lower camel case, such as "displayName,avatarAssetId".

For example, PageInfo.total_count appears as "totalCount": "123". Do not convert arbitrary 64-bit values to JavaScript Number; use BigInt or keep the decimal string to preserve precision.

Default values without explicit presence are normally omitted. A present optional field can contain its default value, including false. JSON null means unset on input; it does not by itself request a stored-field reset. Update endpoints use updateMask to select fields to set or reset. Follow the endpoint documentation for reset behavior.

ProtoJSON integrations that need to tolerate future additive oneof variants must configure their decoder to ignore unknown fields. In particular, Notifications 2.0 may add new NotificationSignal variants; strict generated JSON clients must be regenerated before receiving such a variant. Binary protobuf is recommended when forward-compatible unknown-field retention is required.

Successful binary protobuf calls return the serialized protobuf response message with Content-Type: application/proto.

Failed calls return Connect errors with stable codes. Common codes include:

  • unauthenticated - the call needs a signed-in user or bearer token.
  • permission_denied - the user is authenticated but lacks the required permission.
  • not_found - a singular lookup target does not exist.
  • invalid_argument - the request message failed validation, including an unknown permission identifier.
  • failed_precondition - the operation is blocked by current state, such as the username-change cooldown.
  • unimplemented - the serving version does not understand a requested resource variant.

Generated clients expose those codes through their Connect client error helpers. Plain HTTP tools receive a Connect error response with an HTTP status mapped from the Connect code.

Package names such as chatto.auth.v1, chatto.discovery.v1, chatto.api.v1, and chatto.admin.v1 identify the current protobuf wire namespaces that clients integrate with.

Chatto is still pre-1.0, so any release may change the public API in ways that require client changes. The v1 suffix is part of the current wire name, not a compatibility guarantee. Pin an exact server version, test integrations against the exact upgrade candidate, and read API Compatibility before upgrading.

Use ServerDiscoveryService.GetServer to inspect the server release, then apply an explicit table of releases your integration supports. If you call the API directly, ignore unknown fields and enum values when possible. Treat documented error codes and permission requirements as part of the experimental integration contract.

The realtime protocol is versioned separately as chatto.realtime.v1 because it is a WebSocket protocol rather than a ConnectRPC service.

Use the service pages below for request and response fields. Shared messages and enums are collected in Shared Types And Enums.

  • AssetService - Room-scoped asset metadata and signed URL read RPCs.
  • AssetUploadService - Chunked room-scoped attachment upload RPCs.
  • PermissionService - Read-only effective permissions for bot and human accounts.
  • BotService - Bot account lifecycle and API-key management RPCs.
  • MessageService - Message creation, editing, deletion, composer link-preview, reaction, and attachment RPCs.
  • MessageSearchService - Authorized full-text message search and provider availability RPCs.
  • MyAccountService - Self-service account, profile, presence, status, external identity, and settings RPCs for the authenticated user.
  • NotificationService - Exact notification occurrence listing, read, and deletion RPCs.
  • NotificationPolicyService - Server, room-group, and room notification delivery policy RPCs for the authenticated viewer.
  • PushNotificationService - Web Push subscription RPCs.
  • RoleService - Authenticated role catalog read RPCs.
  • RoomDirectoryService - Room navigation, room group, and room viewer-state RPCs.
  • RoomService - Room lifecycle, timeline, read-state, membership, direct-message, typing indicator, and moderation RPCs.
  • RoomInvitationService - Invitations to channel rooms.
  • ServerService - Authenticated server MOTD and runtime configuration RPCs.
  • ThreadService - Thread timeline, read-state, follow, and followed-thread listing RPCs.
  • UserService - Authenticated server-wide user directory RPCs.
  • ViewerService - Authenticated viewer profile, preferences, and capability RPCs.
  • VoiceCallService - Voice and video call state and token RPCs.