openapi: 3.1.0
info:
  title: Queuebeam API
  version: 1.0.0
  description: Durable asynchronous HTTP, webhook, callback, email and Slack operations.
servers:
  - url: https://api.queuebeam.cloud
security:
  - ApiKey: []
paths:
  /health/{token}:
    get:
      operationId: getQueueHealthcheck
      summary: Return tenant queue health from a generated public URL
      security: []
      parameters:
        - name: token
          in: path
          required: true
          schema: {type: string, pattern: '^qbhc_[A-Za-z0-9]{48}$'}
      responses:
        '200':
          description: Queue and failure counts are below their configured thresholds.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/HealthcheckResponse'}
        '503':
          description: A configured threshold has been reached or the tenant is suspended.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/HealthcheckResponse'}
        '404':
          description: Healthcheck token does not exist.
  /api/v1/operations:
    post:
      operationId: acceptOperation
      summary: Persist and queue an outbound operation
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OperationRequest'
      responses:
        '202':
          description: Durably accepted; delivery has not necessarily completed.
          headers:
            X-Queuebeam-Quota-Limit: {$ref: '#/components/headers/QuotaLimit'}
            X-Queuebeam-Quota-Used: {$ref: '#/components/headers/QuotaUsed'}
            X-Queuebeam-Quota-Remaining: {$ref: '#/components/headers/QuotaRemaining'}
            X-Queuebeam-Quota-Resets-At: {$ref: '#/components/headers/QuotaResetsAt'}
          content:
            application/json:
              schema: {$ref: '#/components/schemas/AcceptedResponse'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '429': {$ref: '#/components/responses/RateLimited'}
        '402': {$ref: '#/components/responses/QuotaExceeded'}
        '422': {$ref: '#/components/responses/ValidationError'}
  /api/v1/operations/{operation}:
    parameters:
      - $ref: '#/components/parameters/OperationId'
    get:
      operationId: getOperation
      summary: Fetch a project-scoped operation
      responses:
        '200':
          description: Operation state and attempt summary.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/OperationResponse'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '429': {$ref: '#/components/responses/RateLimited'}
        '404': {$ref: '#/components/responses/NotFound'}
  /api/v1/operations/{operation}/cancel:
    parameters:
      - $ref: '#/components/parameters/OperationId'
    post:
      operationId: cancelOperation
      summary: Cancel an operation that has not started
      responses:
        '200':
          description: Operation cancelled.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/OperationResponse'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '429': {$ref: '#/components/responses/RateLimited'}
        '422': {$ref: '#/components/responses/ValidationError'}
  /api/v1/operations/{operation}/retry:
    parameters:
      - $ref: '#/components/parameters/OperationId'
    post:
      operationId: retryOperation
      summary: Create a related operation from a failed operation
      responses:
        '202':
          description: Retry accepted as a new operation.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/AcceptedResponse'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '429': {$ref: '#/components/responses/RateLimited'}
        '422': {$ref: '#/components/responses/ValidationError'}
  /api/v1/operations/{operation}/replay:
    parameters:
      - $ref: '#/components/parameters/OperationId'
    post:
      operationId: replayOperation
      summary: Create a related operation from an existing operation
      responses:
        '202':
          description: Replay accepted as a new operation.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/AcceptedResponse'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '429': {$ref: '#/components/responses/RateLimited'}
        '422': {$ref: '#/components/responses/ValidationError'}
  /api/v1/operations/{operation}/ai-analyses:
    parameters:
      - $ref: '#/components/parameters/OperationId'
    post:
      operationId: requestFailureAnalysis
      summary: Queue a sanitized, read-only failure analysis
      responses:
        '202':
          description: Analysis queued.
        '401': {$ref: '#/components/responses/Unauthorized'}
        '429': {$ref: '#/components/responses/RateLimited'}
        '422': {$ref: '#/components/responses/ValidationError'}
  /api/v1/quota:
    get:
      operationId: getQuota
      summary: Return current monthly quota usage
      responses:
        '200':
          description: Quota snapshot.
          content:
            application/json:
              schema: {$ref: '#/components/schemas/QuotaResponse'}
        '401': {$ref: '#/components/responses/Unauthorized'}
        '429': {$ref: '#/components/responses/RateLimited'}
components:
  securitySchemes:
    ApiKey:
      type: http
      scheme: bearer
      bearerFormat: Queuebeam API key
  parameters:
    OperationId:
      name: operation
      in: path
      required: true
      schema: {type: string, format: uuid}
  headers:
    QuotaLimit: {schema: {type: integer}}
    QuotaUsed: {schema: {type: integer}}
    QuotaRemaining: {schema: {type: integer}}
    QuotaResetsAt: {schema: {type: string, format: date-time}}
  responses:
    Unauthorized:
      description: Missing, invalid, revoked, suspended or unverified API key.
      content:
        application/json:
          schema: {$ref: '#/components/schemas/Error'}
    QuotaExceeded:
      description: Monthly quota exhausted; no operation was persisted.
      content:
        application/json:
          schema: {$ref: '#/components/schemas/Error'}
    RateLimited:
      description: Too many requests for this IP address or API credential.
      content:
        application/json:
          schema: {$ref: '#/components/schemas/Error'}
    ValidationError:
      description: Invalid operation or invalid state transition.
      content:
        application/json:
          schema: {$ref: '#/components/schemas/Error'}
    NotFound:
      description: Operation does not exist in the API key project.
      content:
        application/json:
          schema: {$ref: '#/components/schemas/Error'}
  schemas:
    OperationRequest:
      type: object
      required: [type]
      properties:
        type: {type: string, enum: [http, webhook, callback, email, slack]}
        target: {type: object, additionalProperties: true}
        destination: {type: string, description: Named destination or direct URL for Slack.}
        payload: {description: Encrypted operation payload}
        headers: {type: object, additionalProperties: {type: string}}
        metas: {type: object, additionalProperties: true}
        idempotency_key: {type: string, maxLength: 255}
        max_attempts: {type: integer, minimum: 1, maximum: 20, default: 5}
        run_at: {type: string, format: date-time}
    AcceptedResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          required: [accepted, operation_id, status, quota]
          properties:
            accepted: {type: boolean, const: true}
            operation_id: {type: string, format: uuid}
            status: {$ref: '#/components/schemas/OperationStatus'}
            run_at: {type: [string, 'null'], format: date-time}
            idempotency_hit: {type: boolean}
            quota: {$ref: '#/components/schemas/Quota'}
    OperationResponse:
      type: object
      required: [data]
      properties:
        data:
          type: object
          additionalProperties: true
    QuotaResponse:
      type: object
      properties:
        data: {$ref: '#/components/schemas/Quota'}
    Quota:
      type: object
      required: [limit, used, remaining, unlimited, resets_at]
      properties:
        limit: {type: integer}
        used: {type: integer}
        remaining: {type: integer}
        unlimited: {type: boolean}
        resets_at: {type: string, format: date-time}
    OperationStatus:
      type: string
      enum: [received, scheduled, queued, processing, retry_scheduled, succeeded, dead_letter, cancelled]
    HealthcheckResponse:
      type: object
      required: [status, data]
      properties:
        status: {type: string, enum: [ok, error]}
        data:
          type: object
          required: [queued_jobs, failed_jobs, queued_error_threshold, failed_error_threshold, checked_at]
          properties:
            queued_jobs: {type: integer, minimum: 0}
            failed_jobs: {type: integer, minimum: 0}
            queued_error_threshold: {type: integer, minimum: 1}
            failed_error_threshold: {type: integer, minimum: 1}
            checked_at: {type: string, format: date-time}
    Error:
      type: object
      required: [error]
      properties:
        error: {type: string}