Messages & Content

Messages are stored in Matrix, the source of truth for all chat content. sphere-chat synchronizes messages into read-optimized projections served through sphere-core, enabling search, filtering, and analytics without querying Matrix directly.

These endpoints return projections (read models) of messages, not the live Matrix data. Projections are updated by background workers (projector:messages). There may be a brief delay between when a message is sent via Matrix and when it appears in these projections.

The message projection model

Each message projection represents a denormalized view of a Matrix event, enriched with metadata for efficient querying.

Properties

Name
id
Type
string
Description
Unique UUID identifier for the message projection.
Name
matrix_event_id
Type
string
Description
The original Matrix event ID (e.g., $event123:your-sphere.example.com).
Name
conversation_id
Type
string
Description
UUID of the conversation this message belongs to.
Name
sender_user_id
Type
string
Description
UUID of the user who sent the message.
Name
message_type
Type
string
Description
The Matrix message type: m.text, m.image, m.file, m.audio, or m.video.
Name
preview
Type
string | null
Description
A plaintext preview of the message content. null for end-to-end encrypted (E2EE) messages.
Name
sent_at
Type
timestamp
Description
ISO 8601 timestamp of when the message was sent.
Name
has_attachment
Type
boolean
Description
Whether the message includes a file attachment.
Name
is_encrypted
Type
boolean
Description
Whether the message is end-to-end encrypted. When true, preview is null.
Name
file_metadata
Type
object | null
Description
Attachment details when has_attachment is true. Contains filename, mime_type, size, and mxc_uri.
Name
thread_metadata
Type
object | null
Description
Thread information when the message is part of a thread. Contains is_thread_reply and thread_root_event_id.

GET/core/api/v1/messages

List message projections

Retrieve a paginated list of message projections. Use query parameters to filter by conversation, message type, attachment presence, and more. Results are ordered by sent_at descending (newest first).

Optional attributes

Name
conversation_id
Type
string
Description
Filter messages by conversation UUID.
Name
message_type
Type
string
Description
Filter by message type: m.text, m.image, m.file, m.audio, or m.video.
Name
has_attachment
Type
boolean
Description
Filter messages that have (true) or do not have (false) attachments.
Name
cursor
Type
string
Description
Cursor for pagination.
Name
limit
Type
integer
Description
Number of messages to return per page. Default is 50, maximum is 100.

Request

GET

/core/api/v1/messages

curl -G https://your-sphere.example.com/core/api/v1/messages \
  -H "Authorization: Bearer {token}" \
  -d conversation_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -d message_type=m.text \
  -d limit=20

Response

{
  "data": [
    {
      "id": "msg-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
      "matrix_event_id": "$evt_abc123:your-sphere.example.com",
      "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "sender_user_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
      "message_type": "m.text",
      "preview": "Hey team, the deployment is ready for review.",
      "sent_at": "2026-02-24T14:35:00Z",
      "has_attachment": false,
      "is_encrypted": false,
      "file_metadata": null,
      "thread_metadata": null
    },
    {
      "id": "msg-2b3c4d5e-6f7a-8901-bcde-f12345678901",
      "matrix_event_id": "$evt_def456:your-sphere.example.com",
      "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "sender_user_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
      "message_type": "m.text",
      "preview": "Looks good, merging now.",
      "sent_at": "2026-02-24T14:32:00Z",
      "has_attachment": false,
      "is_encrypted": false,
      "file_metadata": null,
      "thread_metadata": {
        "is_thread_reply": true,
        "thread_root_event_id": "$evt_abc123:your-sphere.example.com"
      }
    }
  ]
}

GET/core/api/v1/messages/{id}

Get message projection

Retrieve a single message projection by its UUID. Returns the full message details including file metadata and thread information.

URL parameters

Name
id
Type
string
Description
The UUID of the message projection to retrieve.

Request

GET

/core/api/v1/messages/{id}

curl https://your-sphere.example.com/core/api/v1/messages/msg-1a2b3c4d-5e6f-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer {token}"

Response

{
  "data": {
    "id": "msg-1a2b3c4d-5e6f-7890-abcd-ef1234567890",
    "matrix_event_id": "$evt_abc123:your-sphere.example.com",
    "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "sender_user_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
    "message_type": "m.file",
    "preview": "Shared a file: architecture-diagram.pdf",
    "sent_at": "2026-02-24T14:35:00Z",
    "has_attachment": true,
    "is_encrypted": false,
    "file_metadata": {
      "filename": "architecture-diagram.pdf",
      "mime_type": "application/pdf",
      "size": 2048576,
      "mxc_uri": "mxc://your-sphere.example.com/AbCdEfGhIjKlMnOp"
    },
    "thread_metadata": null
  }
}

GET/core/api/v1/messages/stats

Get message statistics

Retrieve aggregate message statistics for a conversation. Returns counts by message type, attachment information, and thread activity. Useful for dashboards and analytics.

Optional attributes

Name
conversation_id
Type
string
Description
The UUID of the conversation to get statistics for. Required.

Request

GET

/core/api/v1/messages/stats

curl -G https://your-sphere.example.com/core/api/v1/messages/stats \
  -H "Authorization: Bearer {token}" \
  -d conversation_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890

Response

{
  "data": {
    "conversation_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "total_messages": 1247,
    "by_type": {
      "m.text": 1050,
      "m.image": 89,
      "m.file": 72,
      "m.audio": 24,
      "m.video": 12
    },
    "attachments_count": 197,
    "encrypted_count": 0,
    "threads_count": 45,
    "period": {
      "first_message_at": "2026-01-15T10:32:00Z",
      "last_message_at": "2026-02-24T14:35:00Z"
    }
  }
}