Signal Messages API

openapi: 3.2.0
info:
  title: Signal Server Accounts Messages API
  description: The Signal Server API is the backend REST API that supports the Signal Private Messenger applications on Android, Desktop, and iOS. Built as a Dropwizard application, it provides REST controllers for account registration and management, message delivery, pre-key bundle distribution, device provisioning, profile management, and attachment handling. The server handles user registration via phone number verification, encrypted message routing, push notification delivery, and pre-key bundle management. While Signal does not offer an official public REST API for third-party use, the server source code is available for inspection and self-hosting. All communication is end-to-end encrypted using the Signal Protocol.
  version: '2.0'
  contact:
    name: Signal Support
    url: https://support.signal.org/
  termsOfService: https://signal.org/legal/
  license:
    name: AGPL-3.0
    url: https://github.com/signalapp/Signal-Server/blob/main/LICENSE
servers:
- url: https://chat.signal.org
  description: Signal Production Server
security:
- basicAuth: []
tags:
- name: Messages
  description: Message sending and receiving endpoints for delivering encrypted messages between Signal users.
paths:
  /v1/messages/{destinationUuid}:
    put:
      operationId: sendMessage
      summary: Send an encrypted message
      description: Sends one or more encrypted messages to the specified destination account identified by UUID. Messages are encrypted using the Signal Protocol and include envelope metadata for delivery. The server routes messages to the recipient's devices.
      tags:
      - Messages
      parameters:
      - $ref: '#/components/parameters/destinationUuid'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IncomingMessageList'
      responses:
        '200':
          description: Messages accepted for delivery
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SendMessageResponse'
        '401':
          description: Authentication required
        '404':
          description: Destination account not found
        '409':
          description: Mismatched devices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MismatchedDevices'
        '410':
          description: Stale devices
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StaleDevices'
components:
  schemas:
    MismatchedDevices:
      type: object
      properties:
        missingDevices:
          type: array
          description: Device IDs that messages were not provided for.
          items:
            type: integer
            format: int64
        extraDevices:
          type: array
          description: Device IDs that messages were provided for but do not exist.
          items:
            type: integer
            format: int64
    StaleDevices:
      type: object
      properties:
        staleDevices:
          type: array
          description: Device IDs with stale registration IDs.
          items:
            type: integer
            format: int64
    IncomingMessageList:
      type: object
      required:
      - messages
      - timestamp
      properties:
        messages:
          type: array
          description: The list of encrypted message envelopes, one per destination device.
          items:
            $ref: '#/components/schemas/IncomingMessage'
        timestamp:
          type: integer
          format: int64
          description: The client timestamp in milliseconds.
        online:
          type: boolean
          description: Whether to only deliver to online devices (skip push notifications for offline devices).
        urgent:
          type: boolean
          description: Whether the message is urgent and should trigger immediate push notification delivery.
    SendMessageResponse:
      type: object
      properties:
        needsSync:
          type: boolean
          description: Whether the sender has other devices that need to be synced with this message.
    IncomingMessage:
      type: object
      required:
      - type
      - destinationDeviceId
      - content
      properties:
        type:
          type: integer
          description: The message envelope type. 1 for ciphertext, 3 for prekey message, 6 for plaintext content, 7 for unidentified sender.
          enum:
          - 1
          - 3
          - 6
          - 7
        destinationDeviceId:
          type: integer
          format: int64
          description: The target device identifier on the destination account.
        destinationRegistrationId:
          type: integer
          description: The expected registration ID of the target device.
        content:
          type: string
          description: The Base64-encoded encrypted message content.
  parameters:
    destinationUuid:
      name: destinationUuid
      in: path
      required: true
      description: The UUID of the destination account.
      schema:
        type: string
        format: uuid
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic authentication using the account UUID (or phone number) and password. The password is established during account registration.
    bearerAuth:
      type: http
      scheme: bearer
      description: Bearer token authentication used for certain provisioning and registration flows.
externalDocs:
  description: Signal Server Source Code
  url: https://github.com/signalapp/Signal-Server