openapi.yaml

components:
  schemas:
    dto.CheckRoomHTTPRequest:
      properties:
        creator:
          type: string
        is_direct:
          type: boolean
        members:
          items:
            type: string
          type: array
      required:
        - creator
        - members
        - is_direct
      type: object
    dto.CheckRoomHTTPResponse:
      properties:
        alkemio_room_id:
          type: string
        allow:
          type: boolean
        reason:
          type: string
      required:
        - allow
      type: object
    dto.DMWebhookPayload:
      properties:
        invitee:
          type: string
        inviter:
          type: string
      required:
        - inviter
        - invitee
      type: object
    http.MediaUploadResult:
      properties:
        contentUri:
          type: string
        mediaId:
          type: string
      required:
        - contentUri
        - mediaId
      type: object
  securitySchemes:
    apiKeyAuth:
      in: header
      name: Authorization
      type: apiKey
info:
  contact:
    email: info@alkem.io
    name: Alkemio
    url: https://alkem.io
  description: |
    Matrix Adapter service for the Alkemio platform. Bridges the Alkemio Server
    and Matrix Homeserver using mautrix-go and RabbitMQ. Provides AppService
    transaction handling, room creation check endpoints, and health probes.
  license:
    name: EUPL-1.2
    url: https://opensource.org/licenses/EUPL-1.2
  title: Alkemio Matrix Adapter
  version: 1.0.0
openapi: 3.1.1
paths:
  /_matrix/app/alkemio/check-room:
    post:
      operationId: CheckRoomHandler.handleCheckRoom
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.CheckRoomHTTPRequest'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/dto.CheckRoomHTTPResponse'
          description: OK
        "400":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Unauthorized
        "500":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Internal Server Error
        "504":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Gateway Timeout
      security:
        - apiKeyAuth: []
  /_matrix/app/alkemio/dm-request:
    post:
      operationId: DMWebhookHandler.handleDMRequest
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/dto.DMWebhookPayload'
        required: true
      responses:
        "200":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: OK
        "400":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Bad Request
        "401":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Unauthorized
        "500":
          content:
            application/json:
              schema:
                additionalProperties:
                  type: string
                type: object
          description: Internal Server Error
      security:
        - apiKeyAuth: []
      summary: handleDMRequest processes DM request webhooks from Synapse.
  /health/live:
    get:
      operationId: app.go:76:40
      responses:
        "200":
          content:
            application/json:
              schema:
                type: string
          description: OK
  /health/ready:
    get:
      operationId: app.go:80:41
      responses:
        "200":
          content:
            application/json:
              schema:
                type: string
          description: OK
  /rest/messaging/media/upload:
    post:
      operationId: MediaUploadHandler.handleUpload
      summary: Upload an original attachment stream to Synapse without publishing an event.
      description: |
        Authenticated gateway route for room-neutral browser uploads. The gateway strips
        client actor headers and forwards its resolved actor identity. The request body
        is original bytes, never JSON or multipart. Content-Type is required and
        must contain the original MIME type. Content-Length is exact and required,
        including for a zero-byte file. A body that is not an image streams through
        unchanged. A JPEG, PNG or WebP body, recognised from its bytes, is read whole and
        stored without its location, device and time metadata, with the content type and
        length of the rewritten bytes; of its Exif data only the orientation tag is kept.
        A corrupt image is refused with 400 invalid_media; an image the memory budget cannot take
        in time with 503 upload_busy and Retry-After; an image body that stalls with 408
        upload_timeout. The stream is not retried. Success is 201 only after the
        synchronous Synapse media provider has stored the upload.
      parameters:
        - in: header
          name: X-Alkemio-Actor-Id
          required: true
          description: Gateway-resolved non-guest Alkemio actor UUID; never supplied by the browser.
          schema:
            type: string
            format: uuid
        - in: query
          name: filename
          required: true
          description: Nonempty UTF-8 filename encoded as an ordinary query parameter; controls are rejected.
          schema:
            type: string
        - in: header
          name: Content-Length
          required: true
          description: Exact number of original bytes, including zero; bounded by MaxAttachmentBytes.
          schema:
            type: integer
            format: int64
            minimum: 0
      requestBody:
        required: true
        description: Raw original bytes; Content-Type declares their MIME type.
        content:
          '*/*':
            schema:
              type: string
              format: binary
      responses:
        "201":
          description: Synapse upload completed, without publishing a message event.
          content:
            application/json:
              schema:
                type: object
                required: [contentUri, mediaId]
                properties:
                  contentUri:
                    type: string
                    description: Local homeserver mxc URI of the completed upload.
                  mediaId:
                    type: string
                    description: Media identifier embedded in contentUri.
        "400":
          description: Invalid request metadata or media.
          content:
            application/json:
              schema:
                type: object
                required: [error]
                properties:
                  error:
                    type: string
                    enum: [invalid_display_name, invalid_content_type, invalid_media]
        "401":
          description: Gateway actor identity is absent, invalid, anonymous or a guest.
          content:
            application/json:
              schema:
                type: object
                required: [error]
                properties:
                  error:
                    type: string
                    enum: [invalid_actor]
        "408":
          description: Upload was canceled, or an image body stopped arriving (slower than 32 KiB/s) and was cut off.
          content:
            application/json:
              schema:
                type: object
                required: [error]
                properties:
                  error:
                    type: string
                    enum: [upload_canceled, upload_timeout]
        "411":
          description: Content-Length is required.
          content:
            application/json:
              schema:
                type: object
                required: [error]
                properties:
                  error:
                    type: string
                    enum: [length_required]
        "413":
          description: Media exceeds the upload byte limit.
          content:
            application/json:
              schema:
                type: object
                required: [error]
                properties:
                  error:
                    type: string
                    enum: [media_too_large]
        "502":
          description: Synapse rejected the upload or its upload request failed.
          content:
            application/json:
              schema:
                type: object
                required: [error]
                properties:
                  error:
                    type: string
                    enum: [upstream_rejected, upstream_upload_failed]
        "503":
          description: Too many images are being processed, or the actor already has two images in flight; nothing was uploaded. Retry after the Retry-After interval.
          headers:
            Retry-After:
              description: Seconds to wait before retrying.
              schema:
                type: integer
          content:
            application/json:
              schema:
                type: object
                required: [error]
                properties:
                  error:
                    type: string
                    enum: [upload_busy]
        "504":
          description: Upload timed out.
          content:
            application/json:
              schema:
                type: object
                required: [error]
                properties:
                  error:
                    type: string
                    enum: [upload_timeout]