openapi: 3.1.1
info:
  title: OKMQ API
  description: OKMQ is a message queue service that provides reliable message delivery with support for various retry strategies, topics, and message acknowledgment patterns.
  version: 1.0.0
  contact:
    name: OKMQ Support
    url: https://okmq.net

servers:
  - url: https://api.okmq.net

security:
  - apiKey: []

components:
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: Authorization

  schemas:
    Account:
      type: object
      properties:
        created:
          type: string
          format: date-time
          description: When the account was created
        id:
          type: string
          format: uuid
          description: Unique identifier for the account
        email:
          type: string
          format: email
          description: Email address associated with the account
        max_mb:
          type: integer
          format: int32
          description: Maximum storage in MB allowed for this account
        max_bytes_used:
          type: integer
          format: int64
          description: Maximum bytes used by this account
        max_channels:
          type: integer
          format: int32
          description: Maximum number of queues allowed for this account
        max_concurrency:
          type: integer
          format: int32
          description: Maximum number of concurrent consumers allowed for this account
        max_messages:
          type: integer
          format: int32
          description: Maximum number of messages allowed for this account
        queues:
          type: array
          items:
            type: string
          description: List of queue names associated with this account
        streams:
          type: array
          items:
            type: string
          description: List of stream names associated with this account
        total_bytes:
          type: integer
          format: int64
          description: Total bytes consumed by all messages in this account
        total_messages:
          type: integer
          format: int64
          description: Total number of messages in this account
      required:
        - created
        - id
        - email
        - max_mb
        - max_bytes_used
        - max_channels
        - max_concurrency
        - max_messages
        - queues
        - streams
        - total_bytes
        - total_messages

    AckStatus:
      type: object
      properties:
        id:
          type: string
          description: Message ID to acknowledge or nack
        ack:
          type: boolean
          description: True to acknowledge, false to nack
        delivery_time:
          type: string
          format: date-time
          description: New delivery time for nacked messages
        delete:
          type: boolean
          description: True to delete the message when acked, false to keep it in the queue
      required:
        - id
        - ack

    ConsumeStreamMessage:
      type: object
      properties:
        id:
          type: string
          description: Unique message identifier
        body:
          type: string
          description: Message payload
        offset:
          type: integer
          format: int64
          description: Message offset in the stream

    CreateQueueRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 50
          description: Name of the queue
        auto_ack:
          type: boolean
          default: false
          description: Whether messages are automatically acknowledged
        auto_delete:
          type: boolean
          default: false
          description: When true, acknowledged messages are automatically deleted
        lock_duration:
          type: integer
          minimum: 1
          default: 30
          description: Lock duration in seconds
        max_delivery_attempts:
          type: integer
          minimum: 1
          default: 1
          description: Maximum number of delivery attempts
        preserve_failed:
          type: boolean
          default: false
          description: When true, failed messages are not deleted by TTL cleanup
        preserve_pending:
          type: boolean
          default: false
          description: When true, pending/processing/scheduled messages are not deleted by TTL cleanup
        ttl:
          type: integer
          minimum: 0
          description: Time to live in seconds
        retry_strategy:
          $ref: '#/components/schemas/RetryStrategy'
        topics:
          type: array
          items:
            type: string
          maxItems: 10
          description: List of topics this queue subscribes to
      required:
        - name

    CreateStreamRequest:
      type: object
      properties:
        name:
          type: string
          maxLength: 50
          description: Name of the stream
        auto_delete:
          type: boolean
          default: false
          description: When true, committed messages are automatically deleted
        ttl:
          type: integer
          minimum: 0
          description: Time to live in seconds
      required:
        - name

    UpdateQueueRequest:
      type: object
      description: Request to update all queue settings. All fields are required - this replaces all settings on the queue.
      properties:
        auto_ack:
          type: boolean
          description: Whether messages are automatically acknowledged
        auto_delete:
          type: boolean
          description: When true, acknowledged messages are automatically deleted
        lock_duration:
          type: integer
          minimum: 1
          maximum: 86400
          description: Lock duration in seconds (max 24 hours)
        max_delivery_attempts:
          type: integer
          minimum: 1
          maximum: 100
          description: Maximum number of delivery attempts
        preserve_failed:
          type: boolean
          description: When true, failed messages are not deleted by TTL cleanup
        preserve_pending:
          type: boolean
          description: When true, pending/processing/scheduled messages are not deleted by TTL cleanup
        retry_strategy:
          $ref: '#/components/schemas/RetryStrategy'
        topics:
          type: array
          items:
            type: string
          maxItems: 10
          description: List of topics this queue subscribes to
        ttl:
          type: integer
          minimum: 0
          maximum: 31536000
          description: Time to live in seconds. Use 0 for no TTL (messages never expire). Max 1 year.
      required:
        - auto_ack
        - auto_delete
        - lock_duration
        - max_delivery_attempts
        - preserve_failed
        - preserve_pending
        - retry_strategy
        - topics
        - ttl

    UpdateStreamRequest:
      type: object
      description: Request to update all stream settings. All fields are required - this replaces all settings on the stream.
      properties:
        auto_delete:
          type: boolean
          description: When true, committed messages are automatically deleted
        ttl:
          type: integer
          minimum: 0
          maximum: 31536000
          description: Time to live in seconds. Use 0 for no TTL (messages never expire). Max 1 year.
      required:
        - auto_delete
        - ttl

    DeleteMessagesRequest:
      type: object
      properties:
        ids:
          type: array
          items:
            type: string
          maxItems: 100
          description: Array of specific message IDs to delete (max 100)
      required:
        - ids

    DequeueMessage:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the message
        body:
          type: string
          description: Message payload
        delivery_time:
          type: string
          format: date-time
          description: When the message should be delivered
        delivery_attempt:
          type: integer
          description: Current delivery attempt number
        locked_until:
          type: string
          format: date-time
          description: When the message lock expires
        tag:
          type: string
          description: Optional tag for message filtering

    EnqueueMessage:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the message
        body:
          type: string
          description: Message payload
        delivery_time:
          type: string
          format: date-time
          description: When the message should be delivered
        tag:
          type: string
          description: Optional tag for message filtering
      required:
        - id
        - body

    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message

    Message:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the message
        body:
          type: string
          description: Message payload
        auto_ack:
          type: boolean
          description: Whether this message uses auto-acknowledgment
        acked:
          type: string
          format: date-time
          description: When the message was acknowledged (null if not acknowledged)
        created:
          type: string
          format: date-time
          description: When the message was created
        delivery_attempt:
          type: integer
          description: Current delivery attempt number
        delivery_time:
          type: string
          format: date-time
          description: When the message should be delivered
        locked_until:
          type: string
          format: date-time
          description: When the message lock expires
        lock_duration:
          type: integer
          description: Lock duration in seconds
        max_delivery_attempts:
          type: integer
          description: Maximum delivery attempts for this message
        ttl:
          type: string
          format: date-time
          description: When the message expires
        tag:
          type: string
          description: Optional tag for message filtering
        updated:
          type: string
          format: date-time
          description: When the message was last updated

    ProduceStreamMessage:
      type: object
      properties:
        id:
          type: string
          maxLength: 50
          description: Unique message identifier for deduplication
        body:
          type: string
          description: Message payload
      required:
        - id
        - body

    Queue:
      type: object
      properties:
        auto_ack:
          type: boolean
          description: Whether messages are automatically acknowledged
        auto_delete:
          type: boolean
          description: When true, acknowledged messages are automatically deleted
        created:
          type: string
          format: date-time
          description: When the queue was created
        lock_duration:
          type: integer
          description: Lock duration in seconds
        max_delivery_attempts:
          type: integer
          description: Maximum number of delivery attempts
        name:
          type: string
          description: Name of the queue
        preserve_failed:
          type: boolean
          description: When true, failed messages are not deleted by TTL cleanup
        preserve_pending:
          type: boolean
          description: When true, pending/processing/scheduled messages are not deleted by TTL cleanup
        retry_strategy:
          $ref: '#/components/schemas/RetryStrategy'
        topics:
          type: array
          items:
            type: string
          description: List of topics this queue subscribes to
        ttl:
          type: integer
          description: Time to live duration in seconds

    QueueStats:
      type: object
      properties:
        acked:
          type: integer
          format: int64
          description: Number of acknowledged messages
        failed:
          type: integer
          format: int64
          description: Number of failed messages (exceeded max delivery attempts)
        scheduled:
          type: integer
          format: int64
          description: Number of scheduled messages (delivery time in future)
        processing:
          type: integer
          format: int64
          description: Number of messages currently being processed (locked)
        pending:
          type: integer
          format: int64
          description: Number of pending messages ready for delivery
        total:
          type: integer
          format: int64
          description: Total number of messages
      required:
        - acked
        - failed
        - scheduled
        - processing
        - pending
        - total

    ResetFailedRequest:
      type: object
      properties:
        ids:
          type: array
          items:
            type: string
          maxItems: 100
          description: Optional array of specific message IDs to reset (max 100)

    RetryStrategy:
      type: object
      properties:
        type:
          type: string
          description: The type of retry strategy (e.g., exponential, linear, fixed, none)
        base_delay:
          type: integer
          minimum: 1
          description: Base delay in seconds
        max_delay:
          type: integer
          minimum: 1
          description: Maximum delay in seconds (for exponential/linear)
        multiplier:
          type: number
          minimum: 1.0
          description: Multiplier for exponential backoff
      required:
        - type

    Stream:
      type: object
      properties:
        auto_delete:
          type: boolean
          description: When true, committed messages are automatically deleted
        created:
          type: string
          format: date-time
          description: When the stream was created
        message_count:
          type: integer
          format: int64
          description: Number of messages in the stream
        ttl:
          type: integer
          description: Time to live in seconds
        offset:
          type: integer
          format: int64
          description: Current committed offset for the stream

    StreamCommitRequest:
      type: object
      properties:
        offset:
          type: integer
          format: int64
          description: Offset to commit
      required:
        - offset

paths:
  /account:
    get:
      summary: Get account information
      description: Retrieve account details including quotas and usage statistics
      tags:
        - Account Management
      responses:
        '200':
          description: Account information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Account'
        '401':
          description: Unauthorized
        '500':
          description: Internal server error

  /queues:
    get:
      summary: List all queues
      description: Retrieve a list of all queues for the authenticated account
      tags:
        - Queue Management
      responses:
        '200':
          description: List of queues
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Queue'
        '401':
          description: Unauthorized
        '500':
          description: Internal server error

    post:
      summary: Create a queue
      description: Create a new message queue
      tags:
        - Queue Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateQueueRequest'
      responses:
        '201':
          description: Queue created successfully
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '409':
          description: Queue already exists
        '500':
          description: Internal server error

  /queues/{queue}:
    parameters:
      - name: queue
        in: path
        required: true
        schema:
          type: string
        description: Name of the queue

    get:
      summary: Get queue details
      description: Retrieve details about a specific queue
      tags:
        - Queue Management
      parameters:
        - name: tag
          in: query
          schema:
            type: string
          description: Optional tag filter
      responses:
        '200':
          description: Queue details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Queue'
        '401':
          description: Unauthorized
        '404':
          description: Queue not found
        '500':
          description: Internal server error

    patch:
      summary: Update queue settings
      description: Update settings on an existing queue. Only provided fields will be updated. Settings are applied to new messages only - existing messages retain their original settings.
      tags:
        - Queue Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateQueueRequest'
      responses:
        '204':
          description: Queue settings updated successfully
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '404':
          description: Queue not found
        '500':
          description: Internal server error

    delete:
      summary: Delete a queue
      description: Delete a queue and all its messages
      tags:
        - Queue Management
      responses:
        '204':
          description: Queue deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Queue not found
        '500':
          description: Internal server error

  /queues/{queue}/stats:
    parameters:
      - name: queue
        in: path
        required: true
        schema:
          type: string
        description: Name of the queue

    get:
      summary: Get queue statistics
      description: Retrieve message count statistics for a queue, broken down by message state
      tags:
        - Queue Management
      parameters:
        - name: tag
          in: query
          schema:
            type: string
          description: Optional tag filter to get stats for messages with a specific tag
      responses:
        '200':
          description: Queue statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueStats'
        '401':
          description: Unauthorized
        '500':
          description: Internal server error

  /queues/{queue}/messages:
    parameters:
      - name: queue
        in: path
        required: true
        schema:
          type: string
        description: Name of the queue

    get:
      summary: Read messages from queue
      description: Read messages from a queue. Supports polling for new messages.
      tags:
        - Queue Operations
      parameters:
        - name: tag
          in: query
          schema:
            type: string
          description: Filter messages by tag
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          description: Maximum number of messages to return
        - name: peek
          in: query
          schema:
            type: boolean
            default: false
          description: Peek at messages without locking them
        - name: type
          in: query
          schema:
            type: string
            enum: [all, acked, failed, pending, processing, scheduled]
            default: all
          description: Filter messages by state (only applies when peek=true)
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
            default: 0
          description: Number of messages to skip for pagination (only applies when peek=true)
      responses:
        '200':
          description: Messages retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DequeueMessage'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '404':
          description: Queue or message not found
        '500':
          description: Internal server error

    post:
      summary: Enqueue messages
      description: Add messages to the queue
      tags:
        - Queue Operations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/EnqueueMessage'
              maxItems: 100
      responses:
        '204':
          description: Messages enqueued successfully
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '404':
          description: Queue not found
        '413':
          description: Message too large
        '500':
          description: Internal server error

    delete:
      summary: Delete messages from queue
      description: Delete messages from a queue. Supports two modes - bulk delete by type/tag (query parameters) or specific messages by IDs (JSON body)
      tags:
        - Queue Operations
      parameters:
        - name: type
          in: query
          schema:
            type: string
            enum: [all, acked, failed, pending, processing, scheduled]
            default: all
          description: Type of messages to delete (ignored if request body is provided)
        - name: tag
          in: query
          schema:
            type: string
          description: Filter messages by tag (ignored if request body is provided)
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DeleteMessagesRequest'
        description: Optional JSON body to delete specific messages by IDs
      responses:
        '204':
          description: Messages deleted successfully
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '404':
          description: Queue not found
        '500':
          description: Internal server error

  /queues/{queue}/messages/{id}:
    parameters:
      - name: queue
        in: path
        required: true
        schema:
          type: string
        description: Name of the queue
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Unique identifier of the message

    get:
      summary: Get a specific message
      description: Peek a specific message from a queue by its ID
      tags:
        - Queue Operations
      responses:
        '200':
          description: Message retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Message'
        '401':
          description: Unauthorized
        '404':
          description: Queue or message not found
        '500':
          description: Internal server error

    delete:
      summary: Delete a specific message
      description: Delete a specific message from the queue by its ID
      tags:
        - Queue Operations
      responses:
        '204':
          description: Message deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Queue or message not found
        '500':
          description: Internal server error

  /queues/{queue}/ack:
    parameters:
      - name: queue
        in: path
        required: true
        schema:
          type: string
        description: Name of the queue

    post:
      summary: Acknowledge or nack messages
      description: Acknowledge successful processing or nack failed messages
      tags:
        - Queue Operations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/AckStatus'
              maxItems: 100
      responses:
        '204':
          description: Messages acknowledged/nacked successfully
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '500':
          description: Internal server error

  /queues/{queue}/resetfailed:
    parameters:
      - name: queue
        in: path
        required: true
        schema:
          type: string
        description: Name of the queue

    post:
      summary: Reset failed messages
      description: Reset failed messages back to waiting state, optionally filtering by tag or specific message IDs
      tags:
        - Queue Operations
      parameters:
        - name: tag
          in: query
          schema:
            type: string
          description: Optional tag filter to reset only messages with this tag
      requestBody:
        required: false
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ResetFailedRequest'
      responses:
        '204':
          description: Failed messages reset successfully
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '404':
          description: Queue not found
        '500':
          description: Internal server error

  /topics/{topic}/messages:
    parameters:
      - name: topic
        in: path
        required: true
        schema:
          type: string
        description: Name of the topic

    post:
      summary: Publish messages to topic
      description: Publish messages to a topic, which will be distributed to subscribed queues
      tags:
        - Queue Operations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/EnqueueMessage'
              maxItems: 100
      responses:
        '204':
          description: Messages published successfully
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '404':
          description: Topic not found
        '500':
          description: Internal server error

  /streams:
    get:
      summary: List all streams
      description: Retrieve a list of all streams for the authenticated account
      tags:
        - Stream Management
      responses:
        '200':
          description: List of streams
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Stream'
        '401':
          description: Unauthorized
        '500':
          description: Internal server error

    post:
      summary: Create a stream
      description: Create a new stream for message streaming
      tags:
        - Stream Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateStreamRequest'
      responses:
        '201':
          description: Stream created successfully
        '400':
          description: Invalid request payload or stream limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '409':
          description: Stream already exists
        '500':
          description: Internal server error

  /streams/{stream}:
    parameters:
      - name: stream
        in: path
        required: true
        schema:
          type: string
        description: Name of the stream

    get:
      summary: Get stream details
      description: Retrieve details about a specific stream
      tags:
        - Stream Management
      responses:
        '200':
          description: Stream details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Stream'
        '401':
          description: Unauthorized
        '404':
          description: Stream not found
        '500':
          description: Internal server error

    patch:
      summary: Update stream settings
      description: Update settings on an existing stream. Only provided fields will be updated. Settings are applied to new messages only - existing messages retain their original settings.
      tags:
        - Stream Management
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateStreamRequest'
      responses:
        '204':
          description: Stream settings updated successfully
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '404':
          description: Stream not found
        '500':
          description: Internal server error

    delete:
      summary: Delete a stream
      description: Delete a stream and all its messages
      tags:
        - Stream Management
      responses:
        '204':
          description: Stream deleted successfully
        '401':
          description: Unauthorized
        '404':
          description: Stream not found
        '500':
          description: Internal server error

  /streams/{stream}/messages:
    parameters:
      - name: stream
        in: path
        required: true
        schema:
          type: string
        description: Name of the stream

    post:
      summary: Produce messages to stream
      description: Add messages to the stream
      tags:
        - Stream Operations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                $ref: '#/components/schemas/ProduceStreamMessage'
              maxItems: 1000
      responses:
        '204':
          description: Messages produced successfully
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '404':
          description: Stream not found
        '413':
          description: Message too large or quota exceeded
        '500':
          description: Internal server error

    delete:
      summary: Delete messages from stream
      description: Delete messages from a stream
      tags:
        - Stream Operations
      parameters:
        - name: offset
          in: query
          schema:
            type: integer
            minimum: 0
          required: false
          description: Optional offset to delete messages up to (exclusive). If not provided, all messages in the stream will be deleted.
      responses:
        '204':
          description: Messages deleted successfully
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '404':
          description: Stream not found
        '500':
          description: Internal server error

    get:
      summary: Consume messages from stream
      description: Read messages from the stream. Uses single consumer model with committed offset tracking. Supports long polling for new messages.
      tags:
        - Stream Operations
      parameters:
        - name: limit
          in: query
          schema:
            type: integer
            minimum: 1
            maximum: 1000
            default: 10
          description: Maximum number of messages to return
      responses:
        '200':
          description: Messages retrieved successfully
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ConsumeStreamMessage'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '404':
          description: Stream not found
        '500':
          description: Internal server error

  /streams/{stream}/commit:
    parameters:
      - name: stream
        in: path
        required: true
        schema:
          type: string
        description: Name of the stream

    post:
      summary: Commit stream offset
      description: Commit the current offset for the stream (single consumer model)
      tags:
        - Stream Operations
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StreamCommitRequest'
      responses:
        '204':
          description: Offset committed successfully
        '400':
          description: Invalid request payload
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
        '404':
          description: Stream not found
        '500':
          description: Internal server error