Bellator Schedule Intelligence Jobs API

openapi: 3.2.0
info:
  title: Bellatorsi Com Jobs API
  version: '1.0'
  description: 'Operations tagged Jobs across 2 of this provider''s published API definitions: api-bellatorsi-com-openapi.json, bellatorsi-com-openapi.json. Each path carries the servers of the definition it was published in.'
tags:
- name: Jobs
paths:
  /api/v1/jobs/{job_id}:
    get:
      tags:
      - Jobs
      summary: Get Job Status
      description: 'Poll async job status and retrieve result when completed.


        This unified endpoint serves all async operations including:

        - Health score calculations

        - Forensics analysis (logic audit, DCMA 14-point, etc.)

        - CPM calculations

        - Resource analysis

        - And all other async endpoints


        **Job Lifecycle:**

        1. **queued** - Job submitted, waiting for worker

        2. **processing** - Worker executing job

        3. **completed** - Job finished successfully, result available

        4. **failed** - Job encountered error

        5. **cancelled** - Job cancelled by user


        **Progress Tracking:**

        - `progress_percent`: Overall progress (0-100)

        - `checks_completed` / `total_checks`: Granular progress for forensics endpoints


        **Polling Recommendations:**

        - Initial delay: 5 seconds

        - Interval: 2-5 seconds

        - Exponential backoff for long-running jobs


        **Result Expiration:**

        - Job results are stored for 24 hours

        - After expiration, job status returns 404'
      operationId: get_async_job_status_api_v1_jobs__job_id__get
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-bellator-internal-dispatch
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Bellator-Internal-Dispatch
      responses:
        '200':
          description: Success - Job status retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobStatusResponse'
              examples:
                queued:
                  summary: Job queued
                  value:
                    job_id: 550e8400-e29b-41d4-a716-446655440000
                    status: queued
                    created_at: '2025-01-08T12:00:00Z'
                    task_count: 5000
                    progress_percent: 0.0
                    endpoint_name: forensics/logic-audit
                processing:
                  summary: Job processing with progress
                  value:
                    job_id: 550e8400-e29b-41d4-a716-446655440000
                    status: processing
                    created_at: '2025-01-08T12:00:00Z'
                    started_at: '2025-01-08T12:00:05Z'
                    task_count: 5000
                    progress_percent: 50.0
                    endpoint_name: forensics/dcma-14-point
                    checks_completed: 7
                    total_checks: 14
                completed:
                  summary: Job completed
                  value:
                    job_id: 550e8400-e29b-41d4-a716-446655440000
                    status: completed
                    created_at: '2025-01-08T12:00:00Z'
                    started_at: '2025-01-08T12:00:05Z'
                    completed_at: '2025-01-08T12:00:20Z'
                    task_count: 5000
                    result:
                      score: 85.5
                      breakdown:
                        criticality_score: 90.0
                        float_erosion_score: 85.0
                      top_signals:
                      - High critical path density
                      confidence: 0.95
                    progress_percent: 100.0
                    endpoint_name: health/score
        '404':
          description: Not Found - Job does not exist or has expired
          content:
            application/json:
              example:
                detail: 'Job not found: 550e8400-e29b-41d4-a716-446655440000'
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              example:
                detail: Rate limit exceeded. Maximum 500 requests per 60 seconds.
                type: rate_limit_exceeded
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    delete:
      tags:
      - Jobs
      summary: Delete Job
      description: 'Delete a completed, failed, or cancelled job result.


        **Deletion Rules:**

        - Only completed, failed, or cancelled jobs can be deleted

        - Queued or processing jobs cannot be deleted (return 409 Conflict)

        - Job data is permanently removed from Redis


        **Use Cases:**

        - Cleanup after retrieving results

        - Remove sensitive job data

        - Free up storage space'
      operationId: delete_job_api_v1_jobs__job_id__delete
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-bellator-internal-dispatch
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Bellator-Internal-Dispatch
      responses:
        '204':
          description: No Content - Job deleted successfully
        '409':
          description: Conflict - Job is still queued or processing
          content:
            application/json:
              example:
                detail: Cannot delete job while it is still processing. Cancel the job first.
        '404':
          description: Not Found - Job does not exist
          content:
            application/json:
              example:
                detail: 'Job not found: 550e8400-e29b-41d4-a716-446655440000'
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              example:
                detail: Rate limit exceeded. Maximum 500 requests per 60 seconds.
                type: rate_limit_exceeded
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /api/v1/jobs/{job_id}/cancel:
    post:
      tags:
      - Jobs
      summary: Cancel Job
      description: 'Cancel a queued or processing job.


        **Cancellation Rules:**

        - Only queued or processing jobs can be cancelled

        - Completed, failed, or already cancelled jobs cannot be cancelled

        - Celery task is revoked (terminated) if currently executing


        **Use Cases:**

        - User-initiated cancellation

        - Timeout or resource constraints

        - Superseded by newer job submission'
      operationId: cancel_async_job_api_v1_jobs__job_id__cancel_post
      parameters:
      - name: job_id
        in: path
        required: true
        schema:
          type: string
          title: Job Id
      - name: x-api-key
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Api-Key
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      - name: x-bellator-internal-dispatch
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: X-Bellator-Internal-Dispatch
      responses:
        '200':
          description: Success - Job cancelled
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                title: Response Cancel Async Job Api V1 Jobs  Job Id  Cancel Post
              example:
                job_id: 550e8400-e29b-41d4-a716-446655440000
                cancelled: true
                message: Job successfully cancelled
        '400':
          description: Bad Request - Job cannot be cancelled
          content:
            application/json:
              example:
                detail: 'Job cannot be cancelled: already completed'
        '404':
          description: Not Found - Job does not exist
          content:
            application/json:
              example:
                detail: 'Job not found: 550e8400-e29b-41d4-a716-446655440000'
        '429':
          description: Too Many Requests - Rate limit exceeded
          content:
            application/json:
              example:
                detail: Rate limit exceeded. Maximum 500 requests per 60 seconds.
                type: rate_limit_exceeded
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
            - type: string
            - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
      - loc
      - msg
      - type
      title: ValidationError
    JobStatusResponse:
      properties:
        job_id:
          type: string
          title: Job Id
          description: Job identifier
        status:
          $ref: '#/components/schemas/JobStatus'
          description: Current job status
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Job creation timestamp
        started_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Started At
          description: Job start timestamp
        completed_at:
          anyOf:
          - type: string
            format: date-time
          - type: 'null'
          title: Completed At
          description: Job completion timestamp
        task_count:
          type: integer
          title: Task Count
          description: Number of tasks in schedule
        result:
          anyOf:
          - additionalProperties: true
            type: object
          - type: 'null'
          title: Result
          description: Job result when completed
        error:
          anyOf:
          - type: string
          - type: 'null'
          title: Error
          description: Error message if failed
        progress_percent:
          anyOf:
          - type: number
            maximum: 100.0
            minimum: 0.0
          - type: 'null'
          title: Progress Percent
          description: Job progress percentage (if available)
        endpoint_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Endpoint Name
          description: Endpoint that submitted this job
        checks_completed:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Checks Completed
          description: Number of checks/steps completed (for forensics endpoints)
        total_checks:
          anyOf:
          - type: integer
            minimum: 0.0
          - type: 'null'
          title: Total Checks
          description: Total number of checks/steps (for forensics endpoints)
      type: object
      required:
      - job_id
      - status
      - created_at
      - task_count
      title: JobStatusResponse
      description: Response model for job status polling.
      example:
        completed_at: '2025-01-08T12:00:20Z'
        created_at: '2025-01-08T12:00:00Z'
        job_id: 550e8400-e29b-41d4-a716-446655440000
        progress_percent: 100.0
        result:
          breakdown: {}
          confidence: 0.95
          score: 85.5
          top_signals: []
        started_at: '2025-01-08T12:00:05Z'
        status: completed
        task_count: 5000
    JobStatus:
      type: string
      enum:
      - queued
      - processing
      - completed
      - failed
      - cancelled
      title: JobStatus
      description: 'Status of an async job.


        Job lifecycle:

        1. QUEUED - Job submitted to queue, waiting for worker

        2. PROCESSING - Worker picked up job and is executing

        3. COMPLETED - Job finished successfully

        4. FAILED - Job encountered an error

        5. CANCELLED - Job was cancelled by user before completion'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: API key for authentication. Required when API_KEY is configured.
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize
          tokenUrl: https://login.microsoftonline.com/{tenant}/oauth2/v2.0/token
          scopes:
            api.read: Read access to API
            api.write: Write access to API
      description: OAuth 2.0 / Azure AD authentication (recommended)
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT Bearer token from OAuth 2.0 / Azure AD
x-refined-from:
- api-bellatorsi-com-openapi.json
- bellatorsi-com-openapi.json