swagger.yaml

definitions:
  smsgateway.Device:
    properties:
      createdAt:
        description: Created at (read only)
        example: "2020-01-01T00:00:00Z"
        type: string
      deletedAt:
        description: Deleted at (read only)
        example: "2020-01-01T00:00:00Z"
        type: string
      id:
        description: ID
        example: PyDmBQZZXYmyxMwED8Fzy
        type: string
      lastSeen:
        description: Last seen at (read only)
        example: "2020-01-01T00:00:00Z"
        type: string
      name:
        description: Name
        example: My Device
        type: string
      updatedAt:
        description: Updated at (read only)
        example: "2020-01-01T00:00:00Z"
        type: string
    type: object
  smsgateway.ErrorResponse:
    properties:
      code:
        description: Error code
        type: integer
      data:
        description: Error context
      message:
        description: Error message
        example: An error occurred
        type: string
    type: object
  smsgateway.HealthCheck:
    properties:
      description:
        description: A human-readable description of the check.
        type: string
      observedUnit:
        description: Unit of measurement for the observed value.
        type: string
      observedValue:
        description: Observed value of the check.
        type: integer
      status:
        allOf:
        - $ref: '#/definitions/smsgateway.HealthStatus'
        description: |-
          Status of the check.
          It can be one of the following values: "pass", "warn", or "fail".
    type: object
  smsgateway.HealthChecks:
    additionalProperties:
      $ref: '#/definitions/smsgateway.HealthCheck'
    type: object
  smsgateway.HealthResponse:
    properties:
      checks:
        allOf:
        - $ref: '#/definitions/smsgateway.HealthChecks'
        description: A map of check names to their respective details.
      releaseId:
        description: |-
          Release ID of the application.
          It is used to identify the version of the application.
        type: integer
      status:
        allOf:
        - $ref: '#/definitions/smsgateway.HealthStatus'
        description: |-
          Overall status of the application.
          It can be one of the following values: "pass", "warn", or "fail".
      version:
        description: Version of the application.
        type: string
    type: object
  smsgateway.HealthStatus:
    enum:
    - pass
    - warn
    - fail
    type: string
    x-enum-varnames:
    - HealthStatusPass
    - HealthStatusWarn
    - HealthStatusFail
  smsgateway.LogEntry:
    properties:
      context:
        additionalProperties:
          type: string
        description: Additional context information related to the log entry, typically
          including data relevant to the log event.
        type: object
      createdAt:
        description: The timestamp when this log entry was created.
        type: string
      id:
        description: A unique identifier for the log entry.
        type: integer
      message:
        description: A message describing the log event.
        type: string
      module:
        description: The module or component of the system that generated the log
          entry.
        type: string
      priority:
        allOf:
        - $ref: '#/definitions/smsgateway.LogEntryPriority'
        description: The priority level of the log entry.
    type: object
  smsgateway.LogEntryPriority:
    enum:
    - DEBUG
    - INFO
    - WARN
    - ERROR
    type: string
    x-enum-varnames:
    - LogEntryPriorityDebug
    - LogEntryPriorityInfo
    - LogEntryPriorityWarn
    - LogEntryPriorityError
  smsgateway.Message:
    properties:
      id:
        description: ID (if not set - will be generated)
        example: PyDmBQZZXYmyxMwED8Fzy
        maxLength: 36
        type: string
      isEncrypted:
        description: Is encrypted
        example: true
        type: boolean
      message:
        description: Content
        example: Hello World!
        maxLength: 65535
        type: string
      phoneNumbers:
        description: Recipients (phone numbers)
        example:
        - "79990001234"
        items:
          type: string
        maxItems: 100
        minItems: 1
        type: array
      simNumber:
        description: SIM card number (1-3), if not set - default SIM will be used
        example: 1
        maximum: 3
        type: integer
      ttl:
        description: Time to live in seconds (conflicts with `validUntil`)
        example: 86400
        minimum: 5
        type: integer
      validUntil:
        description: Valid until (conflicts with `ttl`)
        example: "2020-01-01T00:00:00Z"
        type: string
      withDeliveryReport:
        description: With delivery report
        example: true
        type: boolean
    required:
    - message
    - phoneNumbers
    type: object
  smsgateway.MessageState:
    properties:
      id:
        description: Message ID
        example: PyDmBQZZXYmyxMwED8Fzy
        maxLength: 36
        type: string
      isEncrypted:
        description: Encrypted
        example: false
        type: boolean
      isHashed:
        description: Hashed
        example: false
        type: boolean
      recipients:
        description: Recipients states
        items:
          $ref: '#/definitions/smsgateway.RecipientState'
        minItems: 1
        type: array
      state:
        allOf:
        - $ref: '#/definitions/smsgateway.ProcessingState'
        description: State
        example: Pending
      states:
        additionalProperties:
          type: string
        description: History of states
        type: object
    required:
    - recipients
    - state
    type: object
  smsgateway.MessagesExportRequest:
    properties:
      deviceId:
        description: DeviceID is the ID of the device to export messages for.
        example: PyDmBQZZXYmyxMwED8Fzy
        maxLength: 21
        type: string
      since:
        description: Since is the start of the time range to export.
        example: "2024-01-01T00:00:00Z"
        type: string
      until:
        description: Until is the end of the time range to export.
        example: "2024-01-01T23:59:59Z"
        type: string
    required:
    - deviceId
    - since
    - until
    type: object
  smsgateway.MobileChangePasswordRequest:
    properties:
      currentPassword:
        description: Current password
        example: cp2pydvxd2zwpx
        type: string
      newPassword:
        description: New password, at least 14 characters
        example: cp2pydvxd2zwpx
        minLength: 14
        type: string
    required:
    - currentPassword
    - newPassword
    type: object
  smsgateway.MobileDeviceResponse:
    properties:
      device:
        allOf:
        - $ref: '#/definitions/smsgateway.Device'
        description: Device information, empty if device is not registered on the
          server
      externalIp:
        description: External IP
        type: string
    type: object
  smsgateway.MobileRegisterRequest:
    properties:
      name:
        description: Device name
        example: Android Phone
        maxLength: 128
        type: string
      pushToken:
        description: FCM token
        example: gHz-T6NezDlOfllr7F-Be
        maxLength: 256
        type: string
    type: object
  smsgateway.MobileRegisterResponse:
    properties:
      id:
        description: New device ID
        example: QslD_GefqiYV6RQXdkM6V
        type: string
      login:
        description: User login
        example: VQ4GII
        type: string
      password:
        description: User password, empty for existing user
        example: cp2pydvxd2zwpx
        type: string
      token:
        description: Device access token
        example: bP0ZdK6rC6hCYZSjzmqhQ
        type: string
    type: object
  smsgateway.MobileUpdateRequest:
    properties:
      id:
        description: ID
        example: QslD_GefqiYV6RQXdkM6V
        type: string
      pushToken:
        description: FCM token
        example: gHz-T6NezDlOfllr7F-Be
        maxLength: 256
        type: string
    type: object
  smsgateway.ProcessingState:
    enum:
    - Pending
    - Processed
    - Sent
    - Delivered
    - Failed
    type: string
    x-enum-comments:
      ProcessingStateDelivered: Delivered
      ProcessingStateFailed: Failed
      ProcessingStatePending: Pending
      ProcessingStateProcessed: Processed (received by device)
      ProcessingStateSent: Sent
    x-enum-varnames:
    - ProcessingStatePending
    - ProcessingStateProcessed
    - ProcessingStateSent
    - ProcessingStateDelivered
    - ProcessingStateFailed
  smsgateway.PushEventType:
    enum:
    - MessageEnqueued
    - WebhooksUpdated
    - MessagesExportRequested
    type: string
    x-enum-varnames:
    - PushMessageEnqueued
    - PushWebhooksUpdated
    - PushMessagesExportRequested
  smsgateway.PushNotification:
    properties:
      data:
        additionalProperties:
          type: string
        description: The additional data associated with the event.
        type: object
      event:
        allOf:
        - $ref: '#/definitions/smsgateway.PushEventType'
        default: MessageEnqueued
        description: The type of event.
        enum:
        - MessageEnqueued
        - WebhooksUpdated
        - MessagesExportRequested
        example: MessageEnqueued
      token:
        description: The token of the device that receives the notification.
        example: PyDmBQZZXYmyxMwED8Fzy
        type: string
    required:
    - token
    type: object
  smsgateway.RecipientState:
    properties:
      error:
        description: Error (for `Failed` state)
        example: timeout
        type: string
      phoneNumber:
        description: Phone number or first 16 symbols of SHA256 hash
        example: "79990001234"
        maxLength: 128
        minLength: 1
        type: string
      state:
        allOf:
        - $ref: '#/definitions/smsgateway.ProcessingState'
        description: State
        example: Pending
    required:
    - phoneNumber
    - state
    type: object
  smsgateway.Webhook:
    properties:
      event:
        allOf:
        - $ref: '#/definitions/smsgateway.WebhookEvent'
        description: The type of event the webhook is triggered for.
        example: sms:received
      id:
        description: The unique identifier of the webhook.
        example: 123e4567-e89b-12d3-a456-426614174000
        maxLength: 36
        type: string
      url:
        description: The URL the webhook will be sent to.
        example: https://example.com/webhook
        type: string
    required:
    - event
    - url
    type: object
  smsgateway.WebhookEvent:
    enum:
    - sms:received
    - sms:sent
    - sms:delivered
    - sms:failed
    - system:ping
    type: string
    x-enum-varnames:
    - WebhookEventSmsReceived
    - WebhookEventSmsSent
    - WebhookEventSmsDelivered
    - WebhookEventSmsFailed
    - WebhookEventSystemPing
host: api.sms-gate.app
info:
  contact:
    email: support@sms-gate.app
    name: SMSGate Support
  description: This API provides programmatic access to sending SMS messages on Android
    devices. Features include sending SMS, checking message status, device management,
    webhook configuration, and system health checks.
  title: SMS Gateway for Android™ API
  version: '{APP_VERSION}'
paths:
  /3rdparty/v1/devices:
    get:
      description: Returns list of registered devices
      produces:
      - application/json
      responses:
        "200":
          description: Device list
          schema:
            items:
              $ref: '#/definitions/smsgateway.Device'
            type: array
        "400":
          description: Invalid request
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
      security:
      - ApiAuth: []
      summary: List devices
      tags:
      - User
      - Devices
  /3rdparty/v1/devices/{id}:
    delete:
      description: Removes device
      parameters:
      - description: Device ID
        in: path
        name: id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "204":
          description: Successfully removed
        "400":
          description: Invalid request
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "404":
          description: Device not found
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
      security:
      - ApiAuth: []
      summary: Remove device
      tags:
      - User
      - Devices
  /3rdparty/v1/health:
    get:
      description: Checks if service is healthy
      produces:
      - application/json
      responses:
        "200":
          description: Health check result
          schema:
            $ref: '#/definitions/smsgateway.HealthResponse'
        "500":
          description: Service is unhealthy
          schema:
            $ref: '#/definitions/smsgateway.HealthResponse'
      summary: Health check
      tags:
      - System
  /3rdparty/v1/inbox/export:
    post:
      consumes:
      - application/json
      description: Initiates process of inbox messages export via webhooks. For each
        message the `sms:received` webhook will be triggered. The webhooks will be
        triggered without specific order.
      parameters:
      - description: Export inbox request
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/smsgateway.MessagesExportRequest'
      produces:
      - application/json
      responses:
        "202":
          description: Inbox export request accepted
          schema:
            type: object
        "400":
          description: Invalid request
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
      security:
      - ApiAuth: []
      summary: Request inbox messages export
      tags:
      - User
      - Messages
  /3rdparty/v1/logs:
    get:
      description: Retrieve a list of log entries within a specified time range.
      parameters:
      - description: The start of the time range for the logs to retrieve. Logs created
          after this timestamp will be included.
        format: date-time
        in: query
        name: from
        type: string
      - description: The end of the time range for the logs to retrieve. Logs created
          before this timestamp will be included.
        format: date-time
        in: query
        name: to
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Log entries
          schema:
            items:
              $ref: '#/definitions/smsgateway.LogEntry'
            type: array
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "501":
          description: Not implemented
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
      security:
      - ApiAuth: []
      summary: Get logs
      tags:
      - System
      - Logs
  /3rdparty/v1/messages:
    post:
      consumes:
      - application/json
      description: Enqueues message for sending. If multiple devices are registered,
        it will be sent via a random one
      parameters:
      - description: Skip phone validation
        in: query
        name: skipPhoneValidation
        type: boolean
      - description: Send message request
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/smsgateway.Message'
      produces:
      - application/json
      responses:
        "202":
          description: Message enqueued
          headers:
            Location:
              description: Get message state URL
              type: string
          schema:
            $ref: '#/definitions/smsgateway.MessageState'
        "400":
          description: Invalid request
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "409":
          description: Message with such ID already exists
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
      security:
      - ApiAuth: []
      summary: Enqueue message
      tags:
      - User
      - Messages
  /3rdparty/v1/messages/{id}:
    get:
      description: Returns message state by ID
      parameters:
      - description: Message ID
        in: path
        name: id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "200":
          description: Message state
          schema:
            $ref: '#/definitions/smsgateway.MessageState'
        "400":
          description: Invalid request
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
      security:
      - ApiAuth: []
      summary: Get message state
      tags:
      - User
      - Messages
  /3rdparty/v1/webhooks:
    get:
      description: Returns list of registered webhooks
      produces:
      - application/json
      responses:
        "200":
          description: Webhook list
          schema:
            items:
              $ref: '#/definitions/smsgateway.Webhook'
            type: array
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
      security:
      - ApiAuth: []
      summary: List webhooks
      tags:
      - User
      - Webhooks
    post:
      consumes:
      - application/json
      description: Registers webhook. If webhook with same ID already exists, it will
        be replaced
      parameters:
      - description: Webhook
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/smsgateway.Webhook'
      produces:
      - application/json
      responses:
        "201":
          description: Created
          schema:
            $ref: '#/definitions/smsgateway.Webhook'
        "400":
          description: Invalid request
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
      security:
      - ApiAuth: []
      summary: Register webhook
      tags:
      - User
      - Webhooks
  /3rdparty/v1/webhooks/{id}:
    delete:
      description: Deletes webhook
      parameters:
      - description: Webhook ID
        in: path
        name: id
        required: true
        type: string
      produces:
      - application/json
      responses:
        "204":
          description: Webhook deleted
          schema:
            type: object
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
      security:
      - ApiAuth: []
      summary: Delete webhook
      tags:
      - User
      - Webhooks
  /mobile/v1/device:
    get:
      description: Returns device information
      produces:
      - application/json
      responses:
        "200":
          description: Device information
          schema:
            $ref: '#/definitions/smsgateway.MobileDeviceResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
      summary: Get device information
      tags:
      - Device
    patch:
      consumes:
      - application/json
      description: Updates push token for device
      parameters:
      - description: Device update request
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/smsgateway.MobileUpdateRequest'
      responses:
        "204":
          description: Successfully updated
        "400":
          description: Invalid request
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "403":
          description: Forbidden (wrong device ID)
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
      security:
      - MobileToken: []
      summary: Update device
      tags:
      - Device
    post:
      consumes:
      - application/json
      description: Registers new device for new or existing user. Returns user credentials
        only for new users
      parameters:
      - description: Device registration request
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/smsgateway.MobileRegisterRequest'
      produces:
      - application/json
      responses:
        "201":
          description: Device registered
          schema:
            $ref: '#/definitions/smsgateway.MobileRegisterResponse'
        "400":
          description: Invalid request
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "401":
          description: Unauthorized (private mode only)
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "429":
          description: Too many requests
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
      security:
      - ApiAuth: []
      - ServerKey: []
      summary: Register device
      tags:
      - Device
  /mobile/v1/message:
    get:
      consumes:
      - application/json
      description: Returns list of pending messages
      produces:
      - application/json
      responses:
        "200":
          description: List of pending messages
          schema:
            items:
              $ref: '#/definitions/smsgateway.Message'
            type: array
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
      security:
      - MobileToken: []
      summary: Get messages for sending
      tags:
      - Device
      - Messages
    patch:
      consumes:
      - application/json
      description: Updates message state
      parameters:
      - description: New message state
        in: body
        name: request
        required: true
        schema:
          items:
            $ref: '#/definitions/smsgateway.MessageState'
          type: array
      produces:
      - application/json
      responses:
        "204":
          description: Successfully updated
        "400":
          description: Invalid request
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
      security:
      - MobileToken: []
      summary: Update message state
      tags:
      - Device
      - Messages
  /mobile/v1/user/password:
    patch:
      consumes:
      - application/json
      description: Changes the user's password
      parameters:
      - description: Password change request
        in: body
        name: request
        required: true
        schema:
          $ref: '#/definitions/smsgateway.MobileChangePasswordRequest'
      produces:
      - application/json
      responses:
        "204":
          description: Password changed successfully
        "400":
          description: Invalid request
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
      security:
      - MobileToken: []
      summary: Change password
      tags:
      - Device
  /mobile/v1/webhooks:
    get:
      description: Returns list of registered webhooks for device
      produces:
      - application/json
      responses:
        "200":
          description: Webhook list
          schema:
            items:
              $ref: '#/definitions/smsgateway.Webhook'
            type: array
        "401":
          description: Unauthorized
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
      security:
      - MobileToken: []
      summary: List webhooks
      tags:
      - Device
      - Webhooks
  /upstream/v1/push:
    post:
      consumes:
      - application/json
      description: Enqueues notifications for sending to devices
      parameters:
      - description: Push request
        in: body
        name: request
        required: true
        schema:
          items:
            $ref: '#/definitions/smsgateway.PushNotification'
          type: array
      produces:
      - application/json
      responses:
        "202":
          description: Notification enqueued
        "400":
          description: Invalid request
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "429":
          description: Too many requests
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
        "500":
          description: Internal server error
          schema:
            $ref: '#/definitions/smsgateway.ErrorResponse'
      summary: Send push notifications
      tags:
      - Upstream
schemes:
- https
securityDefinitions:
  ApiAuth:
    type: basic
  MobileToken:
    description: Mobile device token
    in: header
    name: Authorization
    type: apiKey
  ServerKey:
    description: Private server authentication
    in: header
    name: Authorization
    type: apiKey
swagger: "2.0"