#API Overview

Firmiana implements the Matrix Client-Server API specification.

#Base URL

http://localhost:8899/_matrix/client/v3

#Authentication

Most endpoints require a bearer token in the Authorization header:

Authorization: Bearer syt_xxxxxxxxxxxxxxxxxxxxx

Endpoints marked with @Secured(IS_ANONYMOUS) do not require authentication (e.g., login, register, versions).

#Request Format

• Content-Type: application/json
• Request body: JSON
• IDs are case-sensitive strings (e.g., @alice:localhost, !room:localhost, $event:localhost)

#Response Format

Successful responses return JSON with HTTP 200.

Error responses follow the Matrix error format:

{
  "errcode": "M_NOT_FOUND",
  "error": "Room not found"
}

#Common Error Codes

#Rate Limiting

Requests are rate-limited per IP address:

• Default: 100 requests per 60-second window
• Exceeded: HTTP 429 with Retry-After header

#Versioning

Check supported versions:

GET /_matrix/client/versions

Firmiana supports: v1.1, v1.2, v1.3, v1.4, v1.5, v1.6

#Pagination

Many list endpoints support pagination via from and to stream tokens:

GET /messages?from=t123&to=t456&dir=b&limit=50

• dir=b — Backwards (newer events first)
• dir=f — Forwards (older events first)
• limit — Maximum number of events (default 50, max 100)