openapi.yaml

openapi: 3.1.0
info:
  title: Spooled Cloud API
  description: |
    Production-ready webhook queue service API.

    Spooled Cloud provides a reliable, multi-tenant job queue system with:
    - Custom webhook ingestion (receive events from any source)
    - Job queue with retry logic and dead-letter queue
    - Worker coordination with heartbeat and lease management
    - Real-time job status updates via WebSocket/SSE
    - Workflow orchestration with job dependencies
    - Cron-based job scheduling
    - Stripe billing integration for subscription management

    ## Authentication

    All API endpoints (except health checks) require authentication via API key.
    Include your API key in the `Authorization` header:

    ```
    Authorization: Bearer sp_live_your_api_key_here
    ```

    ## Security

    - **Multi-tenant isolation**: All operations are scoped to your organization
    - **API key verification**: Keys verified using bcrypt with caching
    - **Webhook signatures**: HMAC-SHA256 with constant-time comparison
    - **Rate limiting**: Per-key limits with graceful degradation
    - **Input validation**: All inputs sanitized and size-limited
    - **SSRF protection**: Webhook URLs validated in production

    ## Rate Limiting

    Rate limits are applied per API key based on plan tier:
    - Free tier: 5 requests/second (burst: 10)
    - Starter tier: 25 requests/second (burst: 50)
    - Pro tier: 100 requests/second (burst: 200)
    - Enterprise: 500 requests/second (burst: 1000)

    Rate limit headers included in all responses:
    - `X-RateLimit-Limit`: Maximum requests per window
    - `X-RateLimit-Remaining`: Remaining requests in current window
    - `X-RateLimit-Reset`: Unix timestamp when the window resets

    ## Plan Limits

    Each plan tier has resource limits:
    - Jobs per day: Free (1,000), Starter (10,000), Pro (100,000), Enterprise (unlimited)
    - Active jobs: Free (10), Starter (500), Pro (5,000), Enterprise (unlimited)
    - Queues: Free (2), Starter (10), Pro (50), Enterprise (unlimited)
    - Workers: Free (1), Starter (5), Pro (25), Enterprise (unlimited)
    - Workflows: Free (disabled), Starter (5), Pro (50), Enterprise (unlimited)

  version: 1.0.0
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0
  contact:
    name: Spooled Cloud Support
    url: https://spooled.cloud/support
    email: support@spooled.cloud

servers:
  - url: https://api.spooled.cloud
    description: Production API
  - url: https://api.staging.spooled.cloud
    description: Staging API
  - url: http://localhost:8080
    description: Local development

tags:
  - name: Health
    description: Health check endpoints
  - name: Authentication
    description: JWT authentication and token management
  - name: Organizations
    description: Organization management
  - name: Jobs
    description: Job queue operations
  - name: Queues
    description: Queue configuration and statistics
  - name: Workers
    description: Worker registration and management
  - name: API Keys
    description: API key management
  - name: Webhooks
    description: Webhook ingestion endpoints
  - name: Workflows
    description: Workflow and job dependency management
  - name: Schedules
    description: Cron-based recurring job schedules
  - name: Outgoing Webhooks
    description: Configure webhooks for receiving notifications when events occur
  - name: Real-time
    description: WebSocket and Server-Sent Events for real-time updates
  - name: Billing
    description: Subscription and billing management via Stripe
  - name: Admin
    description: Platform administration (requires X-Admin-Key header)

paths:
  /health:
    get:
      tags: [Health]
      summary: Health check
      description: Returns the health status of the service and its dependencies
      operationId: healthCheck
      security: []
      responses:
        '200':
          description: Service is healthy
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HealthResponse'
              example:
                status: healthy
                version: '1.0.0'
                database: true
                cache: true

  /health/live:
    get:
      tags: [Health]
      summary: Liveness probe
      description: Kubernetes liveness probe - returns 200 if the service is running
      operationId: liveness
      security: []
      responses:
        '200':
          description: Service is alive

  /health/ready:
    get:
      tags: [Health]
      summary: Readiness probe
      description: Kubernetes readiness probe - returns 200 if the service can accept traffic
      operationId: readiness
      security: []
      responses:
        '200':
          description: Service is ready
        '503':
          description: Service is not ready

  /api/v1/dashboard:
    get:
      tags: [Dashboard]
      summary: Dashboard data
      description: |
        Returns comprehensive dashboard data including system info, job statistics,
        queue summaries, worker status, and recent activity.

        Requires authentication. Data is scoped to the authenticated organization.
      operationId: dashboardData
      security:
        - BearerAuth: []
        - ApiKeyAuth: []
      responses:
        '200':
          description: Dashboard data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DashboardData'

  /metrics:
    get:
      tags: [Health]
      summary: Prometheus metrics
      description: |
        Returns application metrics in Prometheus text format.

        Metrics include:
        - `spooled_jobs_enqueued_total`: Total jobs enqueued
        - `spooled_jobs_completed_total`: Total jobs completed
        - `spooled_jobs_failed_total`: Total jobs failed
        - `spooled_jobs_pending`: Current pending jobs
        - `spooled_jobs_processing`: Current processing jobs
        - `spooled_job_duration_seconds`: Job processing duration histogram
        - `spooled_workers_active`: Active workers
        - `spooled_api_requests_total`: Total API requests
      operationId: prometheusMetrics
      security: []
      responses:
        '200':
          description: Prometheus metrics
          content:
            text/plain:
              schema:
                type: string
              example: |
                # HELP spooled_jobs_enqueued_total Total jobs enqueued
                # TYPE spooled_jobs_enqueued_total counter
                spooled_jobs_enqueued_total 1234
                # HELP spooled_jobs_pending Number of pending jobs
                # TYPE spooled_jobs_pending gauge
                spooled_jobs_pending 42

  # Authentication Endpoints
  /api/v1/auth/login:
    post:
      tags: [Authentication]
      summary: Login with API key
      description: Exchange an API key for JWT access and refresh tokens
      operationId: login
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LoginRequest'
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LoginResponse'
        '401':
          description: Invalid credentials
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/auth/refresh:
    post:
      tags: [Authentication]
      summary: Refresh access token
      description: Exchange a valid refresh token for a new access token
      operationId: refreshToken
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RefreshTokenRequest'
      responses:
        '200':
          description: Token refreshed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RefreshTokenResponse'
        '401':
          description: Invalid or expired refresh token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/auth/logout:
    post:
      tags: [Authentication]
      summary: Logout
      description: Invalidate the current access token
      operationId: logout
      responses:
        '204':
          description: Logged out successfully
        '401':
          description: Not authenticated

  /api/v1/auth/me:
    get:
      tags: [Authentication]
      summary: Get current user info
      description: Returns information about the authenticated user from the JWT token
      operationId: getCurrentUser
      responses:
        '200':
          description: Current user info
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CurrentUserResponse'
        '401':
          description: Not authenticated

  /api/v1/auth/validate:
    post:
      tags: [Authentication]
      summary: Validate a token
      description: Check if a JWT token is valid and not blacklisted
      operationId: validateToken
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ValidateTokenRequest'
      responses:
        '200':
          description: Token validation result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidateTokenResponse'

  # Email-based Authentication
  /api/v1/auth/check-email:
    get:
      tags: [Authentication]
      summary: Check email availability
      description: Check if an email is already registered
      operationId: checkEmail
      security: []
      parameters:
        - name: email
          in: query
          required: true
          schema:
            type: string
            format: email
          description: Email address to check
      responses:
        '200':
          description: Email check result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckEmailResponse'

  /api/v1/auth/email/start:
    post:
      tags: [Authentication]
      summary: Start email login
      description: |
        Start the email-based login flow. Sends a verification code to the provided email.
        If the email is not associated with an existing organization, verification will
        return a short-lived signup token to complete registration.
      operationId: startEmailLogin
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/StartEmailLoginRequest'
      responses:
        '200':
          description: Verification code sent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StartEmailLoginResponse'
        '429':
          description: Too many requests - rate limited

  /api/v1/auth/email/verify:
    post:
      tags: [Authentication]
      summary: Verify email code
      description: Verify the code sent to the user's email and complete login
      operationId: verifyEmailCode
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/VerifyEmailRequest'
      responses:
        '200':
          description: Login successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VerifyEmailResponse'
        '400':
          description: Invalid or expired code
        '404':
          description: No pending verification found

  /api/v1/auth/signup/complete:
    post:
      tags: [Authentication]
      summary: Complete signup
      description: Complete the signup process by creating an organization
      operationId: completeSignup
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompleteSignupRequest'
      responses:
        '201':
          description: Signup completed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompleteSignupResponse'
        '400':
          description: Invalid token or organization name

  # Billing Endpoints
  /api/v1/billing/status:
    get:
      tags: [Billing]
      summary: Get billing status
      description: Get the current billing status for the organization
      operationId: getBillingStatus
      responses:
        '200':
          description: Billing status
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BillingStatus'

  /api/v1/billing/portal:
    post:
      tags: [Billing]
      summary: Create portal session
      description: Create a Stripe Customer Portal session for managing subscriptions
      operationId: createBillingPortal
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreatePortalRequest'
      responses:
        '200':
          description: Portal session URL
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreatePortalResponse'

  /api/v1/billing/webhook:
    post:
      tags: [Billing]
      summary: Stripe webhook
      description: |
        Webhook endpoint for Stripe events. Secured with STRIPE_BILLING_WEBHOOK_SECRET.
        Handles subscription lifecycle events.
      operationId: stripeWebhook
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Webhook processed
        '400':
          description: Invalid webhook signature

  /api/v1/organizations/check-slug:
    get:
      tags: [Organizations]
      summary: Check slug availability
      description: Check if an organization slug is available
      operationId: checkSlug
      security: []
      parameters:
        - name: slug
          in: query
          required: true
          schema:
            type: string
          description: Slug to check
      responses:
        '200':
          description: Slug availability
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CheckSlugResponse'

  /api/v1/organizations/generate-slug:
    post:
      tags: [Organizations]
      summary: Generate unique slug
      description: Generate a unique slug from an organization name
      operationId: generateSlug
      security: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GenerateSlugRequest'
      responses:
        '200':
          description: Generated slug
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GenerateSlugResponse'

  /api/v1/organizations:
    get:
      tags: [Organizations]
      summary: List organizations
      description: List all organizations accessible to the authenticated user
      operationId: listOrganizations
      responses:
        '200':
          description: List of organizations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OrganizationSummary'
    post:
      tags: [Organizations]
      summary: Create organization
      description: Create a new organization
      operationId: createOrganization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOrganizationRequest'
      responses:
        '201':
          description: Organization created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '409':
          description: Organization with this slug already exists
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/organizations/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Organization ID
    get:
      tags: [Organizations]
      summary: Get organization
      operationId: getOrganization
      responses:
        '200':
          description: Organization details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '404':
          description: Organization not found
    put:
      tags: [Organizations]
      summary: Update organization
      operationId: updateOrganization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOrganizationRequest'
      responses:
        '200':
          description: Organization updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
        '404':
          description: Organization not found
    delete:
      tags: [Organizations]
      summary: Delete organization
      operationId: deleteOrganization
      responses:
        '204':
          description: Organization deleted
        '404':
          description: Organization not found

  /api/v1/organizations/usage:
    get:
      tags: [Organizations]
      summary: Get organization usage
      description: |
        Returns current resource usage and plan limits for the authenticated organization.
        Includes daily job counts, resource counts, and warnings for approaching limits.
      operationId: getOrganizationUsage
      responses:
        '200':
          description: Usage information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageInfo'

  /api/v1/organizations/webhook-token:
    get:
      tags: [Organizations]
      summary: Get webhook token
      description: |
        Get the current webhook token and URL for receiving incoming webhooks.
        The token is automatically generated when the organization is created.
      operationId: getWebhookToken
      responses:
        '200':
          description: Webhook token information
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookTokenResponse'
              example:
                webhook_token: 'whk_abc123...'
                webhook_url: 'https://api.spooled.cloud/api/v1/webhooks/org-id/custom'

  /api/v1/organizations/webhook-token/regenerate:
    post:
      tags: [Organizations]
      summary: Regenerate webhook token
      description: |
        Generate a new webhook token, invalidating the old one.
        Update your external services with the new token after regenerating.
      operationId: regenerateWebhookToken
      responses:
        '200':
          description: New webhook token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookTokenResponse'

  /api/v1/organizations/webhook-token/clear:
    post:
      tags: [Organizations]
      summary: Clear webhook token (disabled)
      description: |
        This endpoint is **disabled**.

        Spooled Cloud no longer supports unauthenticated incoming webhook ingestion.
        Use `/api/v1/organizations/webhook-token/regenerate` to rotate the token instead.
      operationId: clearWebhookToken
      deprecated: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [confirm]
              properties:
                confirm:
                  type: boolean
                  description: Must be true to confirm clearing the token
            example:
              confirm: true
      responses:
        '400':
          description: Not allowed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: validation_error
                message: Clearing the webhook token is not allowed. Use /organizations/webhook-token/regenerate to rotate it.

  # Admin Endpoints
  /api/v1/admin/organizations:
    get:
      tags: [Admin]
      summary: List all organizations
      description: |
        List all organizations on the platform. Requires admin authentication via X-Admin-Key header.
      operationId: adminListOrganizations
      security:
        - AdminKeyAuth: []
      parameters:
        - name: plan_tier
          in: query
          schema:
            type: string
            enum: [free, starter, pro, enterprise]
          description: Filter by plan tier
        - name: search
          in: query
          schema:
            type: string
          description: Search by name or slug
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: List of organizations
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminOrganizationList'
        '401':
          description: Invalid or missing admin key

    post:
      tags: [Admin]
      summary: Create organization (admin)
      description: Create a new organization with specified plan
      operationId: adminCreateOrganization
      security:
        - AdminKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminCreateOrganizationRequest'
      responses:
        '201':
          description: Organization created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminCreateOrganizationResponse'

  /api/v1/admin/organizations/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Organization ID
    get:
      tags: [Admin]
      summary: Get organization details
      description: Get detailed information about an organization including usage statistics
      operationId: adminGetOrganization
      security:
        - AdminKeyAuth: []
      responses:
        '200':
          description: Organization details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminOrganizationDetail'
        '404':
          description: Organization not found
    patch:
      tags: [Admin]
      summary: Update organization
      description: Update organization settings including plan tier
      operationId: adminUpdateOrganization
      security:
        - AdminKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AdminUpdateOrganizationRequest'
      responses:
        '200':
          description: Organization updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Organization'
    delete:
      tags: [Admin]
      summary: Delete organization
      description: |
        Delete an organization and all its data.
        
        - **Soft delete** (default): Marks organization as deleted.
        - **Hard delete** (`hard_delete=true`): Permanently removes organization and all related data (jobs, workflows, workers, etc.).
      operationId: adminDeleteOrganization
      security:
        - AdminKeyAuth: []
      parameters:
        - name: hard_delete
          in: query
          schema:
            type: boolean
            default: false
          description: Permanent deletion (cannot be undone)
      responses:
        '204':
          description: Organization deleted
        '404':
          description: Organization not found

  /api/v1/admin/stats:
    get:
      tags: [Admin]
      summary: Get platform statistics
      description: Get platform-wide statistics
      operationId: adminGetStats
      security:
        - AdminKeyAuth: []
      responses:
        '200':
          description: Platform statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformStats'

  /api/v1/admin/plans:
    get:
      tags: [Admin]
      summary: List available plans
      description: Get all available plan tiers with their limits
      operationId: adminListPlans
      security:
        - AdminKeyAuth: []
      responses:
        '200':
          description: List of plans
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PlanLimits'

  /api/v1/admin/organizations/{id}/api-keys:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    post:
      tags: [Admin]
      summary: Create API key for organization
      description: Create an API key for a specific organization
      operationId: adminCreateApiKey
      security:
        - AdminKeyAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApiKeyRequest'
      responses:
        '201':
          description: API key created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateApiKeyResponse'

  /api/v1/admin/organizations/{id}/reset-usage:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    post:
      tags: [Admin]
      summary: Reset organization usage
      description: Reset daily usage counters for an organization
      operationId: adminResetUsage
      security:
        - AdminKeyAuth: []
      responses:
        '200':
          description: Usage reset
          content:
            application/json:
              schema:
                type: object
                properties:
                  reset:
                    type: boolean
                  organization_id:
                    type: string

  /api/v1/jobs:
    get:
      tags: [Jobs]
      summary: List jobs
      description: List jobs with optional filtering
      operationId: listJobs
      parameters:
        - name: queue_name
          in: query
          schema:
            type: string
          description: Filter by queue name
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, scheduled, processing, completed, failed, deadletter, cancelled]
          description: Filter by status
        - name: tag
          in: query
          schema:
            type: string
            maxLength: 64
          description: Filter jobs by a single tag (matches Postgres `tags ? tag` semantics)
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            maximum: 100
          description: Maximum number of results
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
          description: Offset for pagination
      responses:
        '200':
          description: List of jobs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/JobSummary'
    post:
      tags: [Jobs]
      summary: Create job
      description: |
        Create a new job in the specified queue.

        If an `idempotency_key` is provided and a job with the same key exists,
        the existing job ID is returned (idempotent behavior).
      operationId: createJob
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateJobRequest'
      responses:
        '201':
          description: Job created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateJobResponse'
        '200':
          description: Existing job returned (idempotent)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateJobResponse'

  /api/v1/jobs/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Job ID
    get:
      tags: [Jobs]
      summary: Get job
      operationId: getJob
      responses:
        '200':
          description: Job details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '404':
          description: Job not found
    delete:
      tags: [Jobs]
      summary: Cancel job
      description: Cancel a pending or scheduled job
      operationId: cancelJob
      responses:
        '204':
          description: Job cancelled
        '404':
          description: Job not found
        '409':
          description: Job cannot be cancelled (not in pending/scheduled state)

  /api/v1/jobs/{id}/retry:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    post:
      tags: [Jobs]
      summary: Retry job
      description: Retry a failed or dead-lettered job
      operationId: retryJob
      responses:
        '200':
          description: Job queued for retry
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '409':
          description: Job cannot be retried

  /api/v1/jobs/claim:
    post:
      tags: [Jobs]
      summary: Claim jobs for processing
      description: |
        Claim one or more jobs from a queue for processing.
        Jobs are leased to the worker for a configurable duration (default 5 minutes).
        If not completed before lease expiry, jobs are released for other workers.
      operationId: claimJobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClaimJobsRequest'
      responses:
        '200':
          description: Jobs claimed successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClaimJobsResponse'
        '404':
          description: Queue not found

  /api/v1/jobs/{id}/complete:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    post:
      tags: [Jobs]
      summary: Complete job
      description: Mark a claimed job as successfully completed
      operationId: completeJob
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompleteJobRequest'
      responses:
        '200':
          description: Job completed
          content:
            application/json:
              schema:
                type: object
                required: [success]
                properties:
                  success:
                    type: boolean
        '404':
          description: Job not found
        '409':
          description: Job not in processing state or lease expired

  /api/v1/jobs/{id}/fail:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    post:
      tags: [Jobs]
      summary: Fail job
      description: |
        Mark a claimed job as failed. If retries remain, job will be rescheduled.
        If no retries remain, job moves to dead-letter queue.
      operationId: failJob
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FailJobRequest'
      responses:
        '200':
          description: Job failed (will retry or go to DLQ)
          content:
            application/json:
              schema:
                type: object
                required: [success]
                properties:
                  success:
                    type: boolean
        '404':
          description: Job not found

  /api/v1/jobs/{id}/heartbeat:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    post:
      tags: [Jobs]
      summary: Renew job lease
      description: Extend the lease on a processing job to prevent it being reclaimed
      operationId: jobHeartbeat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HeartbeatJobRequest'
      responses:
        '200':
          description: Lease renewed
          content:
            application/json:
              schema:
                type: object
                required: [success]
                properties:
                  success:
                    type: boolean
        '404':
          description: Job not found
        '409':
          description: Job not in processing state

  /api/v1/jobs/stats:
    get:
      tags: [Jobs]
      summary: Get job statistics
      operationId: getJobStats
      parameters:
        - name: queue_name
          in: query
          required: false
          description: Optional queue filter (alias `queue` also accepted)
          schema:
            type: string
          example: emails
      responses:
        '200':
          description: Job statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStats'

  /api/v1/jobs/status:
    get:
      tags: [Jobs]
      summary: Batch job status lookup
      description: |
        Get the status of multiple jobs in a single request.
        Maximum 100 job IDs per request.
      operationId: batchJobStatus
      parameters:
        - name: ids
          in: query
          required: true
          description: Comma-separated list of job IDs
          schema:
            type: string
          example: 'job-1,job-2,job-3'
      responses:
        '200':
          description: Job statuses retrieved
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/BatchJobStatus'
        '400':
          description: Too many job IDs (max 100)

  /api/v1/jobs/bulk:
    post:
      tags: [Jobs]
      summary: Bulk enqueue jobs
      description: |
        Enqueue multiple jobs in a single request. 
        Maximum 100 jobs per request.
        Jobs are processed atomically where possible.
      operationId: bulkEnqueueJobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkEnqueueRequest'
            example:
              queue_name: emails
              default_priority: 0
              default_max_retries: 3
              jobs:
                - payload: { to: 'user@example.com', subject: 'Hello' }
                - payload: { to: 'user2@example.com', subject: 'Welcome' }
                  priority: 10
      responses:
        '200':
          description: Bulk enqueue results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BulkEnqueueResponse'

  /api/v1/jobs/{id}/priority:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    put:
      tags: [Jobs]
      summary: Boost job priority
      description: Update the priority of a pending or scheduled job
      operationId: boostJobPriority
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BoostPriorityRequest'
      responses:
        '200':
          description: Priority updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BoostPriorityResponse'
        '404':
          description: Job not found or not in pending/scheduled state

  /api/v1/jobs/dlq:
    get:
      tags: [Jobs]
      summary: List dead-letter queue
      description: List jobs in the dead-letter queue
      operationId: listDeadLetterQueue
      parameters:
        - name: queue_name
          in: query
          schema:
            type: string
          description: Filter by queue name
        - name: tag
          in: query
          schema:
            type: string
            maxLength: 64
          description: Filter jobs by a single tag (matches Postgres `tags ? tag` semantics)
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            maximum: 100
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: List of dead-letter jobs
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/JobSummary'

  /api/v1/jobs/dlq/retry:
    post:
      tags: [Jobs]
      summary: Retry dead-letter jobs
      description: Move jobs from dead-letter queue back to pending
      operationId: retryDeadLetterJobs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RetryDlqRequest'
      responses:
        '200':
          description: Retry results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RetryDlqResponse'

  /api/v1/jobs/dlq/purge:
    post:
      tags: [Jobs]
      summary: Purge dead-letter queue
      description: Permanently delete jobs from dead-letter queue
      operationId: purgeDeadLetterQueue
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurgeDlqRequest'
            example:
              queue_name: emails
              confirm: true
      responses:
        '200':
          description: Purge results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurgeDlqResponse'
        '400':
          description: Must confirm purge operation

  /api/v1/queues:
    get:
      tags: [Queues]
      summary: List queues
      operationId: listQueues
      responses:
        '200':
          description: List of queue configurations
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/QueueConfigSummary'

  /api/v1/queues/{name}:
    parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
        description: Queue name
    get:
      tags: [Queues]
      summary: Get queue configuration
      operationId: getQueueConfig
      responses:
        '200':
          description: Queue configuration
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueConfig'
        '404':
          description: Queue not found

    delete:
      tags: [Queues]
      summary: Delete queue
      description: |
        Delete a queue and optionally all its jobs.
        Use with caution - this operation is destructive.
      operationId: deleteQueue
      parameters:
        - name: delete_jobs
          in: query
          schema:
            type: boolean
            default: false
          description: Also delete all jobs in the queue
      responses:
        '204':
          description: Queue deleted
        '404':
          description: Queue not found

  /api/v1/queues/{name}/config:
    parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
    put:
      tags: [Queues]
      summary: Update queue configuration
      operationId: updateQueueConfig
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpsertQueueConfigRequest'
      responses:
        '200':
          description: Queue configuration updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueConfig'

  /api/v1/queues/{name}/stats:
    parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
    get:
      tags: [Queues]
      summary: Get queue statistics
      operationId: getQueueStats
      responses:
        '200':
          description: Queue statistics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueStats'

  /api/v1/queues/{name}/pause:
    parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
    post:
      tags: [Queues]
      summary: Pause queue
      description: |
        Pause job processing for this queue.
        New jobs can still be enqueued but won't be processed until resumed.
      operationId: pauseQueue
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PauseQueueRequest'
      responses:
        '200':
          description: Queue paused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PauseQueueResponse'

  /api/v1/queues/{name}/resume:
    parameters:
      - name: name
        in: path
        required: true
        schema:
          type: string
    post:
      tags: [Queues]
      summary: Resume queue
      description: Resume job processing for a paused queue
      operationId: resumeQueue
      responses:
        '200':
          description: Queue resumed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ResumeQueueResponse'
        '404':
          description: Queue not found

  /api/v1/workers:
    get:
      tags: [Workers]
      summary: List workers
      operationId: listWorkers
      responses:
        '200':
          description: List of workers
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WorkerSummary'

  /api/v1/workers/register:
    post:
      tags: [Workers]
      summary: Register worker
      operationId: registerWorker
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RegisterWorkerRequest'
      responses:
        '201':
          description: Worker registered
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RegisterWorkerResponse'

  /api/v1/workers/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      tags: [Workers]
      summary: Get worker
      operationId: getWorker
      responses:
        '200':
          description: Worker details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Worker'
        '404':
          description: Worker not found

  /api/v1/workers/{id}/heartbeat:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    post:
      tags: [Workers]
      summary: Send heartbeat
      operationId: workerHeartbeat
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkerHeartbeatRequest'
      responses:
        '200':
          description: Heartbeat received
        '404':
          description: Worker not found

  /api/v1/workers/{id}/deregister:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    post:
      tags: [Workers]
      summary: Deregister worker
      operationId: deregisterWorker
      responses:
        '204':
          description: Worker deregistered
        '404':
          description: Worker not found

  /api/v1/api-keys:
    get:
      tags: [API Keys]
      summary: List API keys
      operationId: listApiKeys
      responses:
        '200':
          description: List of API keys (without secret values)
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ApiKeySummary'
    post:
      tags: [API Keys]
      summary: Create API key
      description: |
        Create a new API key. The raw key value is only returned once in the response.
        Store it securely - it cannot be retrieved later.
      operationId: createApiKey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateApiKeyRequest'
      responses:
        '201':
          description: API key created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateApiKeyResponse'

  /api/v1/api-keys/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      tags: [API Keys]
      summary: Get API key
      operationId: getApiKey
      responses:
        '200':
          description: API key details (without secret)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeySummary'
        '404':
          description: API key not found
    put:
      tags: [API Keys]
      summary: Update API key
      operationId: updateApiKey
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateApiKeyRequest'
      responses:
        '200':
          description: API key updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiKeySummary'
        '404':
          description: API key not found
    delete:
      tags: [API Keys]
      summary: Revoke API key
      operationId: revokeApiKey
      responses:
        '204':
          description: API key revoked
        '404':
          description: API key not found

  /api/v1/webhooks/{org_id}/custom:
    parameters:
      - name: org_id
        in: path
        required: true
        schema:
          type: string
        description: Organization ID (UUID)
        example: org_a1b2c3d4e5f6
    post:
      tags: [Webhooks]
      summary: Custom webhook
      description: |
        Receive webhook events from any external source and create jobs automatically.

        Each organization has a unique webhook URL. Configure your external services
        (payment providers, form handlers, CI/CD pipelines, etc.) to POST events here.

        ## Authentication

        You must include the organization’s webhook token in the `X-Webhook-Token` header.

        To configure a webhook token:
        ```
        GET /api/v1/organizations/webhook-token
        POST /api/v1/organizations/webhook-token/regenerate
        ```

        ## Security

        - In production, HTTPS is required (HTTP webhooks are rejected)
        - Use idempotency keys to handle retries from external services
        - The payload is stored as-is, validate in your worker
      operationId: customWebhook
      security: []
      parameters:
        - name: X-Webhook-Token
          in: header
          required: true
          schema:
            type: string
          description: |
            Webhook authentication token (required).
          example: your-secret-webhook-token
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CustomWebhookRequest'
            examples:
              payment:
                summary: Payment webhook
                value:
                  queue_name: payments
                  event_type: payment.completed
                  payload:
                    payment_id: pay_xyz789
                    amount: 5000
                    currency: usd
                  idempotency_key: payment-pay_xyz789
              form:
                summary: Form submission
                value:
                  queue_name: form-submissions
                  event_type: contact.form
                  payload:
                    name: Jane Doe
                    email: jane@example.com
                    message: I have a question
              deployment:
                summary: CI/CD deployment
                value:
                  queue_name: deployments
                  event_type: deploy.triggered
                  priority: 10
                  payload:
                    repo: my-app
                    branch: main
                    commit: abc123def
                  idempotency_key: deploy-abc123def
      responses:
        '200':
          description: Webhook received and job created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookResponse'
              example:
                job_id: job_550e8400e29b41d4
                queue_name: payments
                status: pending
        '400':
          description: Invalid request (missing queue_name, payload too large, etc.)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Invalid or missing X-Webhook-Token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                code: authentication_error
                message: Invalid or missing X-Webhook-Token
        '404':
          description: Organization not found

  # Workflow Endpoints
  /api/v1/workflows:
    get:
      tags: [Workflows]
      summary: List workflows
      description: List all workflows for the organization
      operationId: listWorkflows
      parameters:
        - name: status
          in: query
          schema:
            type: string
            enum: [pending, running, completed, failed, cancelled]
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
            maximum: 100
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: List of workflows
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/WorkflowResponse'
    post:
      tags: [Workflows]
      summary: Create workflow
      description: |
        Create a new workflow with multiple jobs and dependencies.
        Jobs within a workflow can have dependencies on other jobs,
        creating a DAG of job execution.
      operationId: createWorkflow
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateWorkflowRequest'
      responses:
        '201':
          description: Workflow created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateWorkflowResponse'
        '400':
          description: Invalid workflow definition (e.g., circular dependency)

  /api/v1/workflows/{id}:
    get:
      tags: [Workflows]
      summary: Get workflow
      description: Get workflow details including progress
      operationId: getWorkflow
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Workflow details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowResponse'
        '404':
          description: Workflow not found

  /api/v1/workflows/{id}/cancel:
    post:
      tags: [Workflows]
      summary: Cancel workflow
      description: Cancel a workflow and all its pending jobs
      operationId: cancelWorkflow
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Workflow cancelled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowResponse'

  /api/v1/workflows/{id}/retry:
    post:
      tags: [Workflows]
      summary: Retry failed workflow
      description: |
        Retry all failed jobs in a workflow. This resets failed/deadletter jobs
        back to pending status, clears retry counts and error messages, and
        resumes the workflow.

        Only workflows with status 'failed' can be retried.
      operationId: retryWorkflow
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Workflow retry initiated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowResponse'
        '400':
          description: Workflow cannot be retried (not in failed status)
        '404':
          description: Workflow not found

  /api/v1/jobs/{id}/dependencies:
    get:
      tags: [Workflows]
      summary: Get job dependencies
      description: Get the dependencies and dependents of a job
      operationId: getJobDependencies
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Job dependencies
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobWithDependencies'
    post:
      tags: [Workflows]
      summary: Add job dependencies
      description: Add dependencies to an existing job
      operationId: addJobDependencies
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddDependenciesRequest'
      responses:
        '200':
          description: Dependencies added
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AddDependenciesResponse'

  # Real-time Endpoints
  /api/v1/ws:
    get:
      tags: [Real-time]
      summary: WebSocket connection
      description: |
        Establish a WebSocket connection for real-time updates.

        ## Authentication
        **Required**: Pass your JWT token in the `token` query parameter.
        WebSocket connections cannot use headers for authentication.

        ```
        wss://api.spooled.cloud/api/v1/ws?token=eyJ...
        ```

        ## Connection
        Connect to this endpoint and upgrade to WebSocket protocol.

        ## Events
        The server will send events for:
        - Job status changes
        - Queue statistics updates
        - Worker heartbeats
        - System health updates

        ## Filtering
        Use query parameters to filter events:
        - `queue`: Filter by queue name
        - `job_id`: Filter by specific job
        - `events`: Comma-separated event types

        ## Client Commands
        Send JSON messages to subscribe/unsubscribe:
        ```json
        {"cmd": "Subscribe", "queue": "emails", "job_id": null}
        {"cmd": "Unsubscribe", "queue": "emails", "job_id": null}
        {"cmd": "Ping"}
        ```
      operationId: websocketHandler
      parameters:
        - name: token
          in: query
          required: true
          description: JWT authentication token
          schema:
            type: string
        - name: queue
          in: query
          schema:
            type: string
        - name: job_id
          in: query
          schema:
            type: string
        - name: events
          in: query
          description: Comma-separated event types
          schema:
            type: string
      responses:
        '101':
          description: Switching to WebSocket protocol

  /api/v1/events:
    get:
      tags: [Real-time]
      summary: Server-Sent Events stream
      description: Subscribe to all system events via SSE
      operationId: sseEventsHandler
      parameters:
        - name: queue
          in: query
          schema:
            type: string
        - name: events
          in: query
          description: Comma-separated event types to filter
          schema:
            type: string
      responses:
        '200':
          description: SSE stream
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/RealtimeEvent'

  /api/v1/events/jobs/{id}:
    get:
      tags: [Real-time]
      summary: Job status SSE stream
      description: Subscribe to status updates for a specific job
      operationId: sseJobHandler
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: SSE stream for job status
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/RealtimeEvent'

  /api/v1/events/queues/{name}:
    get:
      tags: [Real-time]
      summary: Queue stats SSE stream
      description: Subscribe to statistics updates for a specific queue
      operationId: sseQueueHandler
      parameters:
        - name: name
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: SSE stream for queue stats
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/RealtimeEvent'

  # Schedule (Cron) Endpoints
  /api/v1/schedules:
    get:
      tags: [Schedules]
      summary: List schedules
      description: List all cron-based job schedules
      operationId: listSchedules
      parameters:
        - name: organization_id
          in: query
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 100
      responses:
        '200':
          description: List of schedules
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Schedule'
    post:
      tags: [Schedules]
      summary: Create schedule
      description: Create a new cron-based recurring job schedule
      operationId: createSchedule
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateScheduleRequest'
      responses:
        '201':
          description: Schedule created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateScheduleResponse'
        '400':
          description: Invalid cron expression or validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/schedules/{id}:
    get:
      tags: [Schedules]
      summary: Get schedule
      description: Get a schedule by ID
      operationId: getSchedule
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Schedule details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schedule'
        '404':
          description: Schedule not found
    put:
      tags: [Schedules]
      summary: Update schedule
      description: Update an existing schedule
      operationId: updateSchedule
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateScheduleRequest'
      responses:
        '200':
          description: Schedule updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schedule'
        '404':
          description: Schedule not found
    delete:
      tags: [Schedules]
      summary: Delete schedule
      description: Delete a schedule
      operationId: deleteSchedule
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Schedule deleted
        '404':
          description: Schedule not found

  /api/v1/schedules/{id}/pause:
    post:
      tags: [Schedules]
      summary: Pause schedule
      description: Temporarily pause a schedule from creating jobs
      operationId: pauseSchedule
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Schedule paused
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schedule'
        '404':
          description: Schedule not found

  /api/v1/schedules/{id}/resume:
    post:
      tags: [Schedules]
      summary: Resume schedule
      description: Resume a paused schedule
      operationId: resumeSchedule
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Schedule resumed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Schedule'
        '404':
          description: Schedule not found

  /api/v1/schedules/{id}/trigger:
    post:
      tags: [Schedules]
      summary: Trigger schedule
      description: Manually trigger a schedule to create a job immediately
      operationId: triggerSchedule
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Schedule triggered, job created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TriggerScheduleResponse'
        '404':
          description: Schedule not found

  /api/v1/schedules/{id}/history:
    get:
      tags: [Schedules]
      summary: Schedule history
      description: Get the execution history of a schedule
      operationId: getScheduleHistory
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
        - name: limit
          in: query
          schema:
            type: integer
            default: 50
      responses:
        '200':
          description: Schedule run history
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ScheduleRun'
        '404':
          description: Schedule not found

  # Outgoing Webhook Endpoints
  /api/v1/outgoing-webhooks:
    get:
      tags: [Outgoing Webhooks]
      summary: List outgoing webhooks
      description: List all configured outgoing webhooks for the organization
      operationId: listOutgoingWebhooks
      responses:
        '200':
          description: List of outgoing webhooks
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OutgoingWebhook'
    post:
      tags: [Outgoing Webhooks]
      summary: Create outgoing webhook
      description: |
        Create a new outgoing webhook configuration.
        The webhook will be called when any of the subscribed events occur.
      operationId: createOutgoingWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOutgoingWebhookRequest'
      responses:
        '201':
          description: Webhook created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutgoingWebhook'
        '400':
          description: Invalid request

  /api/v1/outgoing-webhooks/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Webhook ID
    get:
      tags: [Outgoing Webhooks]
      summary: Get outgoing webhook
      operationId: getOutgoingWebhook
      responses:
        '200':
          description: Webhook details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutgoingWebhook'
        '404':
          description: Webhook not found
    put:
      tags: [Outgoing Webhooks]
      summary: Update outgoing webhook
      operationId: updateOutgoingWebhook
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateOutgoingWebhookRequest'
      responses:
        '200':
          description: Webhook updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OutgoingWebhook'
        '404':
          description: Webhook not found
    delete:
      tags: [Outgoing Webhooks]
      summary: Delete outgoing webhook
      operationId: deleteOutgoingWebhook
      responses:
        '204':
          description: Webhook deleted
        '404':
          description: Webhook not found

  /api/v1/outgoing-webhooks/{id}/test:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    post:
      tags: [Outgoing Webhooks]
      summary: Test outgoing webhook
      description: Send a test payload to the webhook URL to verify connectivity
      operationId: testOutgoingWebhook
      responses:
        '200':
          description: Test result
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TestWebhookResponse'
        '404':
          description: Webhook not found

  /api/v1/outgoing-webhooks/{id}/deliveries:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
    get:
      tags: [Outgoing Webhooks]
      summary: Get webhook delivery history
      description: Get the delivery history for an outgoing webhook
      operationId: getOutgoingWebhookDeliveries
      responses:
        '200':
          description: Delivery history
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OutgoingWebhookDelivery'
        '404':
          description: Webhook not found

  /api/v1/outgoing-webhooks/{id}/retry/{delivery_id}:
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
        description: Webhook ID
      - name: delivery_id
        in: path
        required: true
        schema:
          type: string
        description: Delivery ID
    post:
      tags: [Outgoing Webhooks]
      summary: Retry webhook delivery
      description: |
        Trigger a retry for a specific outgoing webhook delivery attempt.
        
        **Limitations:**
        - Cannot retry successful deliveries (returns 400)
        - Maximum 10 total attempts per delivery (returns 400 when exceeded)
      operationId: retryOutgoingWebhookDelivery
      responses:
        '200':
          description: Retry initiated
          content:
            application/json:
              schema:
                type: object
                required: [success, message]
                properties:
                  success:
                    type: boolean
                  message:
                    type: string
        '400':
          description: Bad request (delivery already successful or max attempts exceeded)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Webhook or delivery not found

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key in Bearer token format
    AdminKeyAuth:
      type: apiKey
      in: header
      name: X-Admin-Key
      description: Admin API key for platform administration

  schemas:
    HealthResponse:
      type: object
      required: [status, version, database, cache]
      properties:
        status:
          type: string
          enum: [healthy, degraded]
        version:
          type: string
        database:
          type: boolean
        cache:
          type: boolean

    # Authentication Schemas
    LoginRequest:
      type: object
      required: [api_key]
      properties:
        api_key:
          type: string
          description: API key to exchange for JWT tokens
          minLength: 10

    LoginResponse:
      type: object
      required: [access_token, refresh_token, token_type, expires_in, refresh_expires_in]
      properties:
        access_token:
          type: string
          description: JWT access token (short-lived)
        refresh_token:
          type: string
          description: JWT refresh token (long-lived)
        token_type:
          type: string
          enum: [Bearer]
        expires_in:
          type: integer
          description: Access token expiration in seconds
        refresh_expires_in:
          type: integer
          description: Refresh token expiration in seconds

    RefreshTokenRequest:
      type: object
      required: [refresh_token]
      properties:
        refresh_token:
          type: string
          description: Valid refresh token

    RefreshTokenResponse:
      type: object
      required: [access_token, token_type, expires_in]
      properties:
        access_token:
          type: string
          description: New JWT access token
        token_type:
          type: string
          enum: [Bearer]
        expires_in:
          type: integer
          description: Access token expiration in seconds

    CurrentUserResponse:
      type: object
      required: [organization_id, api_key_id, queues, issued_at, expires_at]
      properties:
        organization_id:
          type: string
        api_key_id:
          type: string
        queues:
          type: array
          items:
            type: string
        issued_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time

    ValidateTokenRequest:
      type: object
      required: [token]
      properties:
        token:
          type: string
          description: JWT token to validate

    ValidateTokenResponse:
      type: object
      required: [valid]
      properties:
        valid:
          type: boolean
        error:
          type: string
          description: Error message if token is invalid
        claims:
          type: object
          description: Token claims if valid

    # Schedule Schemas
    Schedule:
      type: object
      required:
        [id, organization_id, name, cron_expression, timezone, queue_name, is_active, created_at]
      properties:
        id:
          type: string
        organization_id:
          type: string
        name:
          type: string
        description:
          type: string
        cron_expression:
          type: string
          description: 'Cron expression: 5-field (minute hour day month weekday) or 6-field (leading seconds). 5-field defaults seconds to 0.'
          example: '0 */5 * * * *'
        timezone:
          type: string
          default: UTC
        queue_name:
          type: string
        payload_template:
          type: object
        priority:
          type: integer
          default: 0
        max_retries:
          type: integer
          default: 3
        timeout_seconds:
          type: integer
          default: 300
        is_active:
          type: boolean
        last_run_at:
          type: string
          format: date-time
        next_run_at:
          type: string
          format: date-time
        run_count:
          type: integer
        tags:
          type: object
        metadata:
          type: object
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    CreateScheduleRequest:
      type: object
      required: [name, cron_expression, queue_name, payload_template]
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
        description:
          type: string
          maxLength: 1000
        cron_expression:
          type: string
          description: Cron expression (5-field, or 6-field with leading seconds)
        timezone:
          type: string
          default: UTC
        queue_name:
          type: string
        payload_template:
          type: object
        priority:
          type: integer
          minimum: -100
          maximum: 100
        max_retries:
          type: integer
          minimum: 0
          maximum: 100
        timeout_seconds:
          type: integer
          minimum: 1
          maximum: 86400
        tags:
          type: object
        metadata:
          type: object

    CreateScheduleResponse:
      type: object
      required: [id, name, cron_expression]
      properties:
        id:
          type: string
        name:
          type: string
        cron_expression:
          type: string
        next_run_at:
          type: string
          format: date-time

    UpdateScheduleRequest:
      type: object
      properties:
        name:
          type: string
        description:
          type: string
        cron_expression:
          type: string
        timezone:
          type: string
        payload_template:
          type: object
        priority:
          type: integer
        max_retries:
          type: integer
        timeout_seconds:
          type: integer
        is_active:
          type: boolean
        tags:
          type: object
        metadata:
          type: object

    TriggerScheduleResponse:
      type: object
      required: [job_id, triggered_at]
      properties:
        job_id:
          type: string
        triggered_at:
          type: string
          format: date-time

    ScheduleRun:
      type: object
      required: [id, schedule_id, status, started_at]
      properties:
        id:
          type: string
        schedule_id:
          type: string
        job_id:
          type: string
        status:
          type: string
          enum: [pending, running, completed, failed]
        error_message:
          type: string
        started_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time

    ErrorResponse:
      type: object
      required: [code, message]
      properties:
        code:
          type: string
          description: Machine-readable error code
        message:
          type: string
          description: Human-readable error message
        details:
          type: object
          description: Additional error details

    Organization:
      type: object
      required: [id, name, slug, plan_tier, settings, created_at, updated_at]
      properties:
        id:
          type: string
        name:
          type: string
        slug:
          type: string
        plan_tier:
          type: string
          enum: [free, starter, pro, enterprise]
        billing_email:
          type: string
          format: email
        settings:
          type: object
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    OrganizationSummary:
      type: object
      required: [id, name, slug, plan_tier, created_at]
      properties:
        id:
          type: string
        name:
          type: string
        slug:
          type: string
        plan_tier:
          type: string
        created_at:
          type: string
          format: date-time

    CreateOrganizationRequest:
      type: object
      required: [name, slug]
      properties:
        name:
          type: string
          minLength: 3
          maxLength: 100
        slug:
          type: string
          minLength: 3
          maxLength: 50
          pattern: '^[a-z0-9][a-z0-9-]*[a-z0-9]$'
        billing_email:
          type: string
          format: email

    UpdateOrganizationRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 3
          maxLength: 100
        billing_email:
          type: string
          format: email
        settings:
          type: object

    Job:
      type: object
      required:
        [
          id,
          organization_id,
          queue_name,
          status,
          payload,
          retry_count,
          max_retries,
          timeout_seconds,
          priority,
          created_at,
          updated_at,
        ]
      properties:
        id:
          type: string
        organization_id:
          type: string
        queue_name:
          type: string
        status:
          type: string
          enum: [pending, scheduled, processing, completed, failed, deadletter, cancelled]
        payload:
          type: object
        result:
          type: object
        retry_count:
          type: integer
        max_retries:
          type: integer
        last_error:
          type: string
        created_at:
          type: string
          format: date-time
        scheduled_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        priority:
          type: integer
        tags:
          type: object
        timeout_seconds:
          type: integer
        parent_job_id:
          type: string
        completion_webhook:
          type: string
          format: uri
        assigned_worker_id:
          type: string
        lease_id:
          type: string
        lease_expires_at:
          type: string
          format: date-time
        idempotency_key:
          type: string
        updated_at:
          type: string
          format: date-time

    JobSummary:
      type: object
      required: [id, queue_name, status, priority, retry_count, created_at]
      properties:
        id:
          type: string
        queue_name:
          type: string
        status:
          type: string
        priority:
          type: integer
        retry_count:
          type: integer
        created_at:
          type: string
          format: date-time
        scheduled_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time

    CreateJobRequest:
      type: object
      required: [queue_name, payload]
      properties:
        queue_name:
          type: string
          minLength: 1
          maxLength: 100
        payload:
          type: object
        priority:
          type: integer
          minimum: -100
          maximum: 100
          default: 0
        max_retries:
          type: integer
          minimum: 0
          maximum: 100
          default: 3
        timeout_seconds:
          type: integer
          minimum: 1
          maximum: 86400
          default: 300
        scheduled_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time
        tags:
          type: object
        parent_job_id:
          type: string
        completion_webhook:
          type: string
          format: uri
        completion_webhook_secret:
          type: string
          description: Optional shared secret used to sign completion webhook callbacks.
        idempotency_key:
          type: string
          maxLength: 255

    CreateJobResponse:
      type: object
      required: [id, created]
      properties:
        id:
          type: string
          description: Job ID (new or existing if idempotent)
        created:
          type: boolean
          description: Whether this was a new job or existing

    JobStats:
      type: object
      required: [pending, scheduled, processing, completed, failed, deadletter, cancelled, total]
      properties:
        pending:
          type: integer
        scheduled:
          type: integer
        processing:
          type: integer
        completed:
          type: integer
        failed:
          type: integer
        deadletter:
          type: integer
        cancelled:
          type: integer
        total:
          type: integer

    QueueConfig:
      type: object
      required:
        [
          id,
          organization_id,
          queue_name,
          max_retries,
          default_timeout,
          enabled,
          settings,
          created_at,
          updated_at,
        ]
      properties:
        id:
          type: string
        organization_id:
          type: string
        queue_name:
          type: string
        max_retries:
          type: integer
        default_timeout:
          type: integer
        rate_limit:
          type: integer
        enabled:
          type: boolean
        settings:
          type: object
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    QueueConfigSummary:
      type: object
      required: [queue_name, max_retries, default_timeout, enabled]
      properties:
        queue_name:
          type: string
        max_retries:
          type: integer
        default_timeout:
          type: integer
        rate_limit:
          type: integer
        enabled:
          type: boolean

    UpsertQueueConfigRequest:
      type: object
      required: [queue_name]
      properties:
        queue_name:
          type: string
        max_retries:
          type: integer
          minimum: 0
          maximum: 100
        default_timeout:
          type: integer
          minimum: 1
          maximum: 86400
        rate_limit:
          type: integer
          minimum: 1
          maximum: 100000
        enabled:
          type: boolean
        settings:
          type: object

    QueueStats:
      type: object
      required:
        [
          queue_name,
          pending_jobs,
          processing_jobs,
          completed_jobs_24h,
          failed_jobs_24h,
          active_workers,
        ]
      properties:
        queue_name:
          type: string
        pending_jobs:
          type: integer
        processing_jobs:
          type: integer
        completed_jobs_24h:
          type: integer
        failed_jobs_24h:
          type: integer
        avg_processing_time_ms:
          type: number
        max_job_age_seconds:
          type: integer
        active_workers:
          type: integer

    Worker:
      type: object
      required:
        [
          id,
          organization_id,
          queue_name,
          queue_names,
          hostname,
          max_concurrency,
          current_jobs,
          status,
          last_heartbeat,
          metadata,
          registered_at,
          updated_at,
        ]
      properties:
        id:
          type: string
        organization_id:
          type: string
        queue_name:
          type: string
        queue_names:
          type: array
          items:
            type: string
        hostname:
          type: string
        worker_type:
          type: string
        max_concurrency:
          type: integer
        current_jobs:
          type: integer
        status:
          type: string
          enum: [healthy, degraded, offline, draining]
        last_heartbeat:
          type: string
          format: date-time
        metadata:
          type: object
        version:
          type: string
        registered_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    WorkerSummary:
      type: object
      required: [id, queue_name, hostname, status, current_jobs, max_concurrency, last_heartbeat]
      properties:
        id:
          type: string
        queue_name:
          type: string
        hostname:
          type: string
        status:
          type: string
        current_jobs:
          type: integer
        max_concurrency:
          type: integer
        last_heartbeat:
          type: string
          format: date-time

    RegisterWorkerRequest:
      type: object
      required: [queue_name, hostname]
      properties:
        queue_name:
          type: string
          minLength: 1
          maxLength: 100
        hostname:
          type: string
          minLength: 1
          maxLength: 255
        worker_type:
          type: string
          maxLength: 50
        max_concurrency:
          type: integer
          minimum: 1
          maximum: 100
          default: 5
        metadata:
          type: object
        version:
          type: string
          maxLength: 50

    RegisterWorkerResponse:
      type: object
      required: [id, queue_name, lease_duration_secs, heartbeat_interval_secs]
      properties:
        id:
          type: string
        queue_name:
          type: string
        lease_duration_secs:
          type: integer
        heartbeat_interval_secs:
          type: integer

    WorkerHeartbeatRequest:
      type: object
      required: [current_jobs]
      properties:
        current_jobs:
          type: integer
        status:
          type: string
        metadata:
          type: object

    ApiKeySummary:
      type: object
      required: [id, name, queues, is_active, created_at]
      properties:
        id:
          type: string
        name:
          type: string
        queues:
          type: array
          items:
            type: string
        rate_limit:
          type: integer
        is_active:
          type: boolean
        created_at:
          type: string
          format: date-time
        last_used:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time

    CreateApiKeyRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        queues:
          type: array
          items:
            type: string
        rate_limit:
          type: integer
          minimum: 1
          maximum: 10000
        expires_at:
          type: string
          format: date-time

    CreateApiKeyResponse:
      type: object
      required: [id, key, name, created_at]
      properties:
        id:
          type: string
        key:
          type: string
          description: The raw API key (only shown once)
        name:
          type: string
        created_at:
          type: string
          format: date-time
        expires_at:
          type: string
          format: date-time

    UpdateApiKeyRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 100
        queues:
          type: array
          items:
            type: string
        rate_limit:
          type: integer
          minimum: 1
          maximum: 10000
        is_active:
          type: boolean

    CustomWebhookRequest:
      type: object
      required: [queue_name, payload]
      properties:
        queue_name:
          type: string
        event_type:
          type: string
        payload:
          type: object
        idempotency_key:
          type: string
        priority:
          type: integer

    WebhookResponse:
      type: object
      properties:
        job_id:
          type: string
          description: ID of the created job
        queue_name:
          type: string
          description: Name of the queue the job was enqueued to
        status:
          type: string
          description: Job status (pending, scheduled)

    # Bulk Operations
    BulkEnqueueRequest:
      type: object
      required: [queue_name, jobs]
      properties:
        queue_name:
          type: string
          minLength: 1
          maxLength: 100
        jobs:
          type: array
          minItems: 1
          maxItems: 100
          items:
            $ref: '#/components/schemas/BulkJobItem'
        default_priority:
          type: integer
          default: 0
        default_max_retries:
          type: integer
          default: 3
        default_timeout_seconds:
          type: integer
          default: 300

    BulkJobItem:
      type: object
      required: [payload]
      properties:
        payload:
          type: object
        priority:
          type: integer
        idempotency_key:
          type: string
          maxLength: 255
        scheduled_at:
          type: string
          format: date-time

    BulkEnqueueResponse:
      type: object
      required: [succeeded, failed, total, success_count, failure_count]
      properties:
        succeeded:
          type: array
          items:
            $ref: '#/components/schemas/BulkJobResult'
        failed:
          type: array
          items:
            $ref: '#/components/schemas/BulkJobError'
        total:
          type: integer
        success_count:
          type: integer
        failure_count:
          type: integer

    BulkJobResult:
      type: object
      required: [index, job_id, created]
      properties:
        index:
          type: integer
        job_id:
          type: string
        created:
          type: boolean

    BulkJobError:
      type: object
      required: [index, error]
      properties:
        index:
          type: integer
        error:
          type: string

    # Priority Boost
    BoostPriorityRequest:
      type: object
      required: [priority]
      properties:
        priority:
          type: integer
          minimum: -100
          maximum: 100

    BoostPriorityResponse:
      type: object
      required: [job_id, old_priority, new_priority]
      properties:
        job_id:
          type: string
        old_priority:
          type: integer
        new_priority:
          type: integer

    # Dead-Letter Queue Operations
    RetryDlqRequest:
      type: object
      properties:
        job_ids:
          type: array
          items:
            type: string
        queue_name:
          type: string
          maxLength: 100
        limit:
          type: integer
          minimum: 1
          maximum: 1000
          default: 100

    RetryDlqResponse:
      type: object
      required: [retried_count, retried_jobs]
      properties:
        retried_count:
          type: integer
        retried_jobs:
          type: array
          items:
            type: string

    PurgeDlqRequest:
      type: object
      required: [confirm]
      properties:
        queue_name:
          type: string
          maxLength: 100
        older_than:
          type: string
          format: date-time
        confirm:
          type: boolean
          description: Must be true to execute purge

    PurgeDlqResponse:
      type: object
      required: [purged_count]
      properties:
        purged_count:
          type: integer

    # Queue Control
    PauseQueueRequest:
      type: object
      properties:
        reason:
          type: string
          description: Optional reason for pausing

    PauseQueueResponse:
      type: object
      required: [queue_name, paused, paused_at]
      properties:
        queue_name:
          type: string
        paused:
          type: boolean
        paused_at:
          type: string
          format: date-time
        reason:
          type: string

    ResumeQueueResponse:
      type: object
      required: [queue_name, resumed, paused_duration_secs]
      properties:
        queue_name:
          type: string
        resumed:
          type: boolean
        paused_duration_secs:
          type: integer

    # Workflow Models
    CreateWorkflowRequest:
      type: object
      required: [name, jobs]
      properties:
        name:
          type: string
          maxLength: 255
        description:
          type: string
          maxLength: 1000
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowJobDefinition'
          minItems: 1
          maxItems: 1000
        metadata:
          type: object

    WorkflowJobDefinition:
      type: object
      required: [key, queue_name, payload]
      properties:
        key:
          type: string
          description: Unique key for this job within the workflow
          maxLength: 100
        queue_name:
          type: string
          maxLength: 255
        payload:
          type: object
        depends_on:
          type: array
          items:
            type: string
          description: Keys of jobs this job depends on
        dependency_mode:
          type: string
          enum: [all, any]
          default: all
        priority:
          type: integer
          default: 0
        max_retries:
          type: integer
        timeout_seconds:
          type: integer

    CreateWorkflowResponse:
      type: object
      required: [workflow_id, job_ids, status]
      properties:
        workflow_id:
          type: string
          format: uuid
        job_ids:
          type: array
          items:
            $ref: '#/components/schemas/WorkflowJobMapping'
        status:
          type: string

    WorkflowJobMapping:
      type: object
      required: [key, job_id]
      properties:
        key:
          type: string
        job_id:
          type: string
          format: uuid

    WorkflowResponse:
      type: object
      required:
        [id, name, status, total_jobs, completed_jobs, failed_jobs, progress_percent, created_at]
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        description:
          type: string
        status:
          type: string
          enum: [pending, running, completed, failed, cancelled]
        total_jobs:
          type: integer
        completed_jobs:
          type: integer
        failed_jobs:
          type: integer
        progress_percent:
          type: number
        created_at:
          type: string
          format: date-time
        started_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
        metadata:
          type: object

    AddDependenciesRequest:
      type: object
      required: [depends_on]
      properties:
        depends_on:
          type: array
          items:
            type: string
          minItems: 1
          maxItems: 100
        dependency_mode:
          type: string
          enum: [all, any]
          default: all

    AddDependenciesResponse:
      type: object
      required: [dependencies_added, dependencies_met]
      properties:
        dependencies_added:
          type: integer
        dependencies_met:
          type: boolean

    JobWithDependencies:
      type: object
      required: [job_id, dependencies, dependents, dependencies_met]
      properties:
        job_id:
          type: string
        dependencies:
          type: array
          items:
            $ref: '#/components/schemas/DependencyInfo'
        dependents:
          type: array
          items:
            $ref: '#/components/schemas/DependencyInfo'
        dependencies_met:
          type: boolean

    DependencyInfo:
      type: object
      required: [job_id, queue_name, status]
      properties:
        job_id:
          type: string
        queue_name:
          type: string
        status:
          type: string

    # Dashboard Models
    DashboardData:
      type: object
      required: [system, jobs, queues, workers, recent_activity]
      properties:
        system:
          $ref: '#/components/schemas/SystemInfo'
        jobs:
          $ref: '#/components/schemas/JobSummaryStats'
        queues:
          type: array
          items:
            $ref: '#/components/schemas/QueueSummary'
        workers:
          $ref: '#/components/schemas/WorkerHealthSummary'
        recent_activity:
          $ref: '#/components/schemas/RecentActivity'

    SystemInfo:
      type: object
      required: [version, uptime_seconds, started_at, database_status, cache_status, environment]
      properties:
        version:
          type: string
        uptime_seconds:
          type: integer
        started_at:
          type: string
          format: date-time
        database_status:
          type: string
        cache_status:
          type: string
        environment:
          type: string

    JobSummaryStats:
      type: object
      required: [total, pending, processing, completed_24h, failed_24h, deadletter]
      properties:
        total:
          type: integer
        pending:
          type: integer
        processing:
          type: integer
        completed_24h:
          type: integer
        failed_24h:
          type: integer
        deadletter:
          type: integer
        avg_wait_time_ms:
          type: number
        avg_processing_time_ms:
          type: number

    QueueSummary:
      type: object
      required: [name, pending, processing, paused]
      properties:
        name:
          type: string
        pending:
          type: integer
        processing:
          type: integer
        paused:
          type: boolean

    WorkerHealthSummary:
      type: object
      required: [total, healthy, unhealthy]
      properties:
        total:
          type: integer
        healthy:
          type: integer
        unhealthy:
          type: integer

    RecentActivity:
      type: object
      required: [jobs_created_1h, jobs_completed_1h, jobs_failed_1h]
      properties:
        jobs_created_1h:
          type: integer
        jobs_completed_1h:
          type: integer
        jobs_failed_1h:
          type: integer

    # Batch Status
    BatchJobStatus:
      type: object
      required: [id, status, queue_name, retry_count, created_at]
      properties:
        id:
          type: string
        status:
          type: string
        queue_name:
          type: string
        retry_count:
          type: integer
        created_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time

    # Real-time Events
    RealtimeEvent:
      type: object
      required: [type, data]
      properties:
        type:
          type: string
          enum:
            # JSON payload "type" values (matches backend `RealtimeEvent` enum variants)
            - JobStatusChange
            - JobCreated
            - JobCompleted
            - JobFailed
            - QueueStats
            - WorkerHeartbeat
            - WorkerRegistered
            - WorkerDeregistered
            - SystemHealth
            - Ping
            - Error
        data:
          type: object

    # Outgoing Webhook Schemas
    OutgoingWebhook:
      type: object
      required:
        [id, organization_id, name, url, events, enabled, failure_count, created_at, updated_at]
      properties:
        id:
          type: string
        organization_id:
          type: string
        name:
          type: string
        url:
          type: string
          format: uri
        events:
          type: array
          items:
            type: string
            enum:
              - job.created
              - job.started
              - job.completed
              - job.failed
              - job.cancelled
              - queue.paused
              - queue.resumed
              - worker.registered
              - worker.deregistered
              - schedule.triggered
        enabled:
          type: boolean
        failure_count:
          type: integer
        last_triggered_at:
          type: string
          format: date-time
        last_status:
          type: string
          enum: [success, failed]
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    CreateOutgoingWebhookRequest:
      type: object
      required: [name, url, events]
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
        url:
          type: string
          format: uri
          maxLength: 2048
        events:
          type: array
          minItems: 1
          items:
            type: string
            enum:
              - job.created
              - job.started
              - job.completed
              - job.failed
              - job.cancelled
              - queue.paused
              - queue.resumed
              - worker.registered
              - worker.deregistered
              - schedule.triggered
        secret:
          type: string
          maxLength: 255
          description: Optional HMAC secret for signing webhook payloads
        enabled:
          type: boolean
          default: true

    UpdateOutgoingWebhookRequest:
      type: object
      properties:
        name:
          type: string
          minLength: 1
          maxLength: 255
        url:
          type: string
          format: uri
          maxLength: 2048
        events:
          type: array
          items:
            type: string
        secret:
          type: string
          maxLength: 255
        enabled:
          type: boolean

    TestWebhookResponse:
      type: object
      required: [success, response_time_ms]
      properties:
        success:
          type: boolean
        status_code:
          type: integer
        response_time_ms:
          type: integer
        error:
          type: string

    OutgoingWebhookDelivery:
      type: object
      required: [id, webhook_id, event, payload, status, attempts, created_at]
      properties:
        id:
          type: string
        webhook_id:
          type: string
        event:
          type: string
        payload:
          type: object
        status:
          type: string
          enum: [pending, success, failed]
        status_code:
          type: integer
        response_body:
          type: string
        error:
          type: string
        attempts:
          type: integer
        created_at:
          type: string
          format: date-time
        delivered_at:
          type: string
          format: date-time

    # Webhook Token Schema
    WebhookTokenResponse:
      type: object
      required: [webhook_url]
      properties:
        webhook_token:
          type: string
          nullable: true
          description: The webhook token (null if cleared)
          example: 'whk_abc123def456...'
        webhook_url:
          type: string
          description: The webhook URL for this organization
          example: 'https://api.spooled.cloud/api/v1/webhooks/org-id/custom'

    # Usage and Admin Schemas
    UsageInfo:
      type: object
      required: [plan, limits, usage, warnings]
      properties:
        plan:
          type: string
          enum: [free, starter, pro, enterprise]
        limits:
          $ref: '#/components/schemas/PlanLimits'
        usage:
          $ref: '#/components/schemas/ResourceUsage'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/UsageWarning'

    PlanLimits:
      type: object
      properties:
        tier:
          type: string
        display_name:
          type: string
        max_jobs_per_day:
          type: integer
          nullable: true
        max_active_jobs:
          type: integer
          nullable: true
        max_queues:
          type: integer
          nullable: true
        max_workers:
          type: integer
          nullable: true
        max_api_keys:
          type: integer
          nullable: true
        max_schedules:
          type: integer
          nullable: true
        max_workflows:
          type: integer
          nullable: true
        max_webhooks:
          type: integer
          nullable: true
        max_payload_size_bytes:
          type: integer
        rate_limit_requests_per_second:
          type: integer
        rate_limit_burst:
          type: integer
        job_retention_days:
          type: integer
        history_retention_days:
          type: integer

    ResourceUsage:
      type: object
      properties:
        jobs_today:
          $ref: '#/components/schemas/UsageItem'
        active_jobs:
          $ref: '#/components/schemas/UsageItem'
        queues:
          $ref: '#/components/schemas/UsageItem'
        workers:
          $ref: '#/components/schemas/UsageItem'
        api_keys:
          $ref: '#/components/schemas/UsageItem'
        schedules:
          $ref: '#/components/schemas/UsageItem'
        workflows:
          $ref: '#/components/schemas/UsageItem'
        webhooks:
          $ref: '#/components/schemas/UsageItem'

    UsageItem:
      type: object
      properties:
        current:
          type: integer
        limit:
          type: integer
          nullable: true
        percentage:
          type: number
          nullable: true

    UsageWarning:
      type: object
      properties:
        resource:
          type: string
        message:
          type: string
        severity:
          type: string
          enum: [warning, critical]
        current:
          type: integer
        limit:
          type: integer

    AdminOrganizationList:
      type: object
      required: [organizations, total, limit, offset]
      properties:
        organizations:
          type: array
          items:
            $ref: '#/components/schemas/AdminOrganizationSummary'
        total:
          type: integer
        limit:
          type: integer
        offset:
          type: integer

    AdminOrganizationSummary:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        slug:
          type: string
        plan_tier:
          type: string
        is_active:
          type: boolean
        jobs_today:
          type: integer
        active_jobs:
          type: integer
        created_at:
          type: string
          format: date-time

    AdminOrganizationDetail:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        slug:
          type: string
        plan_tier:
          type: string
        billing_email:
          type: string
        is_active:
          type: boolean
        settings:
          type: object
        stripe_customer_id:
          type: string
          nullable: true
          description: Stripe customer ID linked to this organization
        stripe_subscription_id:
          type: string
          nullable: true
          description: Stripe subscription ID for billing
        stripe_subscription_status:
          type: string
          nullable: true
          description: Stripe subscription status (active, past_due, canceled, etc.)
        stripe_current_period_end:
          type: string
          format: date-time
          nullable: true
          description: Current billing period end date
        stripe_cancel_at_period_end:
          type: boolean
          nullable: true
          description: Whether subscription will cancel at period end
        usage:
          $ref: '#/components/schemas/ResourceUsage'
        resource_counts:
          type: object
          properties:
            queues:
              type: integer
            workers:
              type: integer
            api_keys:
              type: integer
            schedules:
              type: integer
            workflows:
              type: integer
            webhooks:
              type: integer
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    AdminUpdateOrganizationRequest:
      type: object
      description: |
        Update organization settings. All fields are optional.
        
        When setting `stripe_subscription_id`, the backend will auto-reconcile with Stripe API
        to fetch the correct plan tier, subscription status, and billing period from Stripe.
      properties:
        name:
          type: string
        plan_tier:
          type: string
          enum: [free, starter, pro, enterprise]
        is_active:
          type: boolean
        billing_email:
          type: string
          format: email
        settings:
          type: object
        custom_limits:
          type: object
          nullable: true
          description: Custom limit overrides (null or empty object resets to plan defaults)
        stripe_customer_id:
          type: string
          nullable: true
          description: Link a Stripe customer to this organization
          example: cus_TcO2bC8PunEANY
        stripe_subscription_id:
          type: string
          nullable: true
          description: Link a Stripe subscription (triggers auto-reconciliation with Stripe)
          example: sub_1Sf9GgDtp6Ou1g6CEOL29LqS
        stripe_subscription_status:
          type: string
          nullable: true
          description: Subscription status (usually auto-filled by reconciliation)
          enum: [active, past_due, canceled, unpaid, incomplete, trialing]

    PlatformStats:
      type: object
      properties:
        total_organizations:
          type: integer
        active_organizations:
          type: integer
        total_jobs_24h:
          type: integer
        completed_jobs_24h:
          type: integer
        failed_jobs_24h:
          type: integer
        active_workers:
          type: integer
        organizations_by_plan:
          type: object
          additionalProperties:
            type: integer

    # Job Processing Schemas
    ClaimJobsRequest:
      type: object
      required: [queue_name, worker_id]
      properties:
        queue_name:
          type: string
          description: Queue to claim jobs from
        worker_id:
          type: string
          description: Worker identifier (for tracking)
        limit:
          type: integer
          minimum: 1
          maximum: 100
          default: 1
          description: Maximum number of jobs to claim
        lease_duration_secs:
          type: integer
          minimum: 5
          maximum: 3600
          default: 30
          description: Lease duration in seconds

    ClaimJobsResponse:
      type: object
      required: [jobs]
      properties:
        jobs:
          type: array
          items:
            $ref: '#/components/schemas/ClaimedJob'

    ClaimedJob:
      type: object
      required: [id, queue_name, payload, retry_count, max_retries, timeout_seconds, lease_expires_at, lease_id]
      properties:
        id:
          type: string
        queue_name:
          type: string
        payload:
          type: object
        retry_count:
          type: integer
        max_retries:
          type: integer
        timeout_seconds:
          type: integer
        lease_expires_at:
          type: string
          format: date-time
        lease_id:
          type: string
          description: >-
            Fencing token for this lease. Echo it back in complete/fail/heartbeat
            so the operation applies only to the lease this worker actually holds.

    CompleteJobRequest:
      type: object
      required: [worker_id, lease_id]
      properties:
        result:
          type: object
          description: Optional result data to store with the job
        worker_id:
          type: string
        lease_id:
          type: string
          description: >-
            Required lease fencing token from the claim response. Completion
            succeeds only if it matches the job's current lease (409
            LEASE_EXPIRED otherwise).

    FailJobRequest:
      type: object
      required: [worker_id, lease_id, error]
      properties:
        error:
          type: string
          minLength: 1
          maxLength: 2048
          description: Error message for the failed attempt
        worker_id:
          type: string
        lease_id:
          type: string
          description: >-
            Required lease fencing token from the claim response. Failure
            succeeds only if it matches the job's current lease (409
            LEASE_EXPIRED otherwise).

    HeartbeatJobRequest:
      type: object
      required: [worker_id, lease_id, lease_duration_secs]
      properties:
        lease_duration_secs:
          type: integer
          minimum: 5
          maximum: 3600
          description: New lease duration from now, in seconds
        worker_id:
          type: string
        lease_id:
          type: string
          description: >-
            Required lease fencing token from the claim response. Renewal
            succeeds only if it matches the job's current lease (409
            LEASE_EXPIRED otherwise).

    # Email Authentication Schemas
    CheckEmailRequest:
      type: object
      required: [email]
      properties:
        email:
          type: string
          format: email

    CheckEmailResponse:
      type: object
      required: [available, exists]
      properties:
        available:
          type: boolean
          description: Whether the email is available (no account exists)
        exists:
          type: boolean
          description: Whether an account exists with this email

    StartEmailLoginRequest:
      type: object
      required: [email]
      properties:
        email:
          type: string
          format: email

    StartEmailLoginResponse:
      type: object
      required: [message, email_sent_to]
      properties:
        message:
          type: string
          description: Human-friendly status message
          example: Login code sent to your email
        email_sent_to:
          type: string
          description: Email address masked for privacy
          example: j***n@example.com

    VerifyEmailRequest:
      type: object
      required: [email, code]
      properties:
        email:
          type: string
          format: email
        code:
          type: string
          minLength: 6
          maxLength: 6

    VerifyEmailResponse:
      description: |
        Email verification result. The response is one of:
        - `type: login` (existing organization) with JWT tokens
        - `type: signup` (new email) with a short-lived signup token
      oneOf:
        - $ref: '#/components/schemas/VerifyEmailLoginResponse'
        - $ref: '#/components/schemas/VerifyEmailSignupResponse'
      discriminator:
        propertyName: type
        mapping:
          login: '#/components/schemas/VerifyEmailLoginResponse'
          signup: '#/components/schemas/VerifyEmailSignupResponse'

    VerifyEmailLoginResponse:
      type: object
      required: [type, access_token, refresh_token, token_type, expires_in, refresh_expires_in]
      properties:
        type:
          type: string
          enum: [login]
        access_token:
          type: string
        refresh_token:
          type: string
        token_type:
          type: string
          enum: [Bearer]
        expires_in:
          type: integer
        refresh_expires_in:
          type: integer

    VerifyEmailSignupResponse:
      type: object
      required: [type, signup_token, email, expires_in]
      properties:
        type:
          type: string
          enum: [signup]
        signup_token:
          type: string
          description: Token to complete signup (used with /api/v1/auth/signup/complete)
        email:
          type: string
          format: email
        expires_in:
          type: integer
          description: Token expiration in seconds

    SignupOrganization:
      type: object
      required: [id, name, slug, billing_email]
      properties:
        id:
          type: string
        name:
          type: string
        slug:
          type: string
        billing_email:
          type: string
          format: email

    CompleteSignupRequest:
      type: object
      required: [signup_token, name, slug]
      properties:
        signup_token:
          type: string
        name:
          type: string
          minLength: 3
          maxLength: 100
        slug:
          type: string
          minLength: 3
          maxLength: 50

    CompleteSignupResponse:
      type: object
      required: [organization, api_key, access_token, refresh_token, token_type, expires_in]
      properties:
        organization:
          $ref: '#/components/schemas/SignupOrganization'
        access_token:
          type: string
        refresh_token:
          type: string
        token_type:
          type: string
          enum: [Bearer]
        expires_in:
          type: integer
        api_key:
          type: string
          description: Initial API key (shown only once)

    # Billing Schemas
    BillingStatus:
      type: object
      required: [plan_tier]
      properties:
        plan_tier:
          type: string
          enum: [free, starter, pro, enterprise]
        has_stripe_customer:
          type: boolean
        stripe_customer_id:
          type: string
        subscription_status:
          type: string
          enum: [active, canceled, past_due, trialing, incomplete]
        current_period_end:
          type: string
          format: date-time
        cancel_at_period_end:
          type: boolean

    CreatePortalRequest:
      type: object
      required: [return_url]
      properties:
        return_url:
          type: string
          format: uri

    CreatePortalResponse:
      type: object
      required: [url]
      properties:
        url:
          type: string
          format: uri
          description: Stripe Customer Portal URL

    # Slug Schemas
    CheckSlugResponse:
      type: object
      required: [available, valid]
      properties:
        available:
          type: boolean
        valid:
          type: boolean
        suggestion:
          type: string
          description: Suggested alternative if not available

    GenerateSlugRequest:
      type: object
      required: [name]
      properties:
        name:
          type: string

    GenerateSlugResponse:
      type: object
      required: [slug]
      properties:
        slug:
          type: string

    # Admin Schemas
    AdminCreateOrganizationRequest:
      type: object
      required: [name, slug]
      properties:
        name:
          type: string
          minLength: 3
          maxLength: 100
        slug:
          type: string
          minLength: 3
          maxLength: 50
        billing_email:
          type: string
          format: email
        plan_tier:
          type: string
          enum: [free, starter, pro, enterprise]
          default: free
        settings:
          type: object

    AdminCreateOrganizationResponse:
      type: object
      required: [id, name, slug, plan_tier, api_key]
      properties:
        id:
          type: string
        name:
          type: string
        slug:
          type: string
        plan_tier:
          type: string
        api_key:
          type: string
          description: Initial API key (shown only once)
        api_key_id:
          type: string
        created_at:
          type: string
          format: date-time

security:
  - bearerAuth: []