GraphQL Subscriptions Reference

Production URL: wss://ai.aiqlick.com/graphql

This document lists all available GraphQL subscriptions for the Background Tasks microservice.

Connection

// Example using graphql-ws
import { createClient } from 'graphql-ws';

const client = createClient({
  url: 'wss://ai.aiqlick.com/graphql',
});

Pipeline Subscriptions

1. `extractCV` - CV Extraction

Extract structured data from CV files (PDF, DOCX, images).

subscription {
  extractCV(input: {
    id: "cv-123"
    fileUrl: "https://storage.aiqlick.com/uploads/resume.pdf"
    sequential: true
  }) {
    ... on CVExtractionProcessing {
      id
      message
      progress
    }
    ... on CVExtractionSuccess {
      id
      parsed {
        contact { name email phone location }
        skills { skill proficiency years }
        experience { title company startDate endDate }
        education { degree institution major }
        languages { name proficiency }
        certifications { name institution year }
      }
      rawText
      fileUrl
    }
    ... on CVExtractionFailure {
      id
      error { code message recoveryHint }
    }
  }
}

Input:

Field	Type	Required	Description
`id`	String	Yes	Unique request identifier
`fileUrl`	String	Yes	URL to the CV file
`sequential`	Boolean	No	Process pages sequentially
`schemaOverride`	String	No	Custom extraction schema

2. `parseJob` - Job Description Parsing

Extract structured data from job descriptions.

subscription {
  parseJob(input: {
    id: "job-456"
    text: "We are looking for a Senior Software Engineer..."
  }) {
    ... on JobParsingProcessing {
      id
      message
      progress
    }
    ... on JobParsingSuccess {
      id
      extractedData {
        title
        description
        jobType
        workSite
        salary
        currency
        skills { name proficiency yearsExperience mustHave }
        languages
        requirements
        responsibilities
        benefits
        companyName
        industry
        location
      }
      rawText
      processingTime
    }
    ... on JobParsingFailure {
      id
      error { code message }
    }
  }
}

Input:

Field	Type	Required	Description
`id`	String	Yes	Unique request identifier
`text`	String	No*	Job description text
`fileUrl`	String	No*	URL to job description file
`extractionSchema`	String	No	Custom extraction schema

*Either text or fileUrl must be provided

3. `faceExtraction` - Face Photo Extraction

Extract face photo from CV documents.

subscription {
  faceExtraction(input: {
    id: "face-789"
    fileUrl: "uploads/cv.pdf"
    originalFilename: "john_doe_cv.pdf"
  }) {
    ... on FaceExtractionProcessing {
      id
      message
      progress
    }
    ... on FaceExtractionSuccess {
      id
      face {
        faceUrl
        faceFound
        detectionMethod
        confidence
      }
      processingTime
    }
    ... on FaceExtractionFailure {
      id
      error { code message recoveryHint }
    }
  }
}

Input:

Field	Type	Required	Description
`id`	String	Yes	Unique request identifier
`fileUrl`	String	Yes	MinIO path or external URL
`originalFilename`	String	No	Original filename for naming output

4. `addCandidate` - Full Candidate Pipeline

Add a candidate manually to a job.

subscription {
  addCandidate(input: {
    id: "add-101"
    jobId: "job-uuid"
    companyId: "company-uuid"
    candidateData: {
      contact: {
        name: "John Doe"
        email: "john@example.com"
        firstName: "John"
        lastName: "Doe"
      }
      skills: [
        { name: "Python", years: 5, proficiency: EXPERT }
      ]
      experience: [
        {
          title: "Senior Developer"
          company: "Tech Corp"
          startDate: "2020-01"
          endDate: "2024-01"
        }
      ]
      education: []
      languages: []
    }
    rawText: "Full CV text..."
  }) {
    ... on AddCandidateProcessing {
      id
      message
      progress
    }
    ... on AddCandidateSuccess {
      id
      candidate {
        candidateId
        userId
        cvId
        matchScore
      }
      processingTime
    }
    ... on AddCandidateFailure {
      id
      error { code message context recoveryHint }
    }
  }
}

5. `userJobMatching` - User-Job Match Score

Calculate match score between a user and a job using AI.

subscription {
  userJobMatching(input: {
    id: "match-201"
    userId: "user-uuid"
    jobId: "job-uuid"
  }) {
    ... on UserJobMatchingProcessing {
      id
      message
      progress
    }
    ... on UserJobMatchingSuccess {
      id
      match {
        matchScore
        userId
        jobId
        scoreBreakdown
        strengths
        gaps
        report
      }
      processingTime
    }
    ... on UserJobMatchingFailure {
      id
      error { code message }
    }
  }
}

6. `candidateJobMatching` - Candidate-Job Match Score

Calculate match score between a candidate and a job using AI.

subscription {
  candidateJobMatching(input: {
    id: "match-301"
    candidateId: "candidate-uuid"
    jobId: "job-uuid"
  }) {
    ... on CandidateJobMatchingProcessing {
      id
      message
      progress
    }
    ... on CandidateJobMatchingSuccess {
      id
      match {
        matchScore
        candidateId
        jobId
        cvId
        matchDetails
        detailedReport
        databaseId
      }
      processingTime
    }
    ... on CandidateJobMatchingFailure {
      id
      error { code message }
    }
  }
}

7. `basicMatching` - Basic Match Score (Domain Logic)

Calculate match score using domain logic (non-AI).

subscription {
  basicMatching(input: {
    id: "basic-401"
    candidateId: "candidate-uuid"
    jobId: "job-uuid"
  }) {
    ... on BasicMatchingProcessing {
      id
      message
      progress
    }
    ... on BasicMatchingSuccess {
      id
      match {
        matchScore
        candidateId
        jobId
        matchDetails
      }
      processingTime
    }
    ... on BasicMatchingFailure {
      id
      error { code message }
    }
  }
}

8. `textRewrite` - AI Text Rewriting

Rewrite text using AI according to custom instructions.

subscription {
  textRewrite(input: {
    id: "rewrite-501"
    text: "Original text to be rewritten..."
    instruction: "Make it more professional and concise"
  }) {
    ... on TextRewriteProcessing {
      id
      message
      progress
    }
    ... on TextRewriteSuccess {
      id
      result {
        rewrittenText
        originalText
        instruction
      }
      processingTime
    }
    ... on TextRewriteFailure {
      id
      error { code message }
    }
  }
}

Input:

Field	Type	Required	Description
`id`	String	Yes	Unique request identifier
`text`	String	Yes	Text to rewrite
`instruction`	String	Yes	Rewriting instructions

9. `generateMeetingInsight` - AI Meeting Insights

Generate AI-powered insights from meeting transcripts.

subscription {
  generateMeetingInsight(input: {
    meetingId: "room-abc123"
    interviewId: "optional-interview-uuid"
  }) {
    ... on MeetingInsightProcessing {
      id
      message
      progress
    }
    ... on MeetingInsightSuccess {
      id
      insight {
        fullReport
        skillsAssessment {
          overallSkillMatchPercentage
          matchedSkills { skillName demonstratedLevel }
          missingSkills { skillName importance }
        }
        communicationAnalysis {
          clarityScore
          confidenceScore
          engagementLevel
          strengths
          areasForImprovement
        }
        keyTopicsSummary {
          topic
          candidateResponse
          relevanceToRole
        }
        redFlagsAndConcerns {
          overallRiskLevel
          concerns { category description severity }
        }
        overallRecommendation {
          recommendation
          fitScore
          reasoning
        }
      }
    }
    ... on MeetingInsightFailure {
      id
      error { code message recoveryHint }
    }
  }
}

Input:

Field	Type	Required	Description
`meetingId`	String	Yes	Jitsi meeting room ID
`interviewId`	String	No	Interview UUID for context

System Subscriptions

10. `taskUpdated` - Task Status Updates

Subscribe to updates for a specific task.

subscription {
  taskUpdated(id: "task-uuid") {
    id
    name
    status
    result
    error
    createdAt
    updatedAt
    completedAt
  }
}

11. `tasksStream` - All Tasks Stream

Subscribe to all task updates (dashboard).

subscription {
  tasksStream {
    id
    name
    status
    createdAt
  }
}

Updates every 5 seconds.

12. `systemStatusStream` - System Status

Real-time system status updates.

subscription {
  systemStatusStream {
    matchScoreGeneratorRunning
    rayInitialized
    rayWorkersHealthy
    databaseConnected
    circuitBreakerOpen
    persistentActorsCount
    activeRayWorkers
    uptimeSeconds
  }
}

Updates every 5 seconds.

13. `metricsStream` - System Metrics

Real-time system metrics.

subscription {
  metricsStream {
    totalUsersProcessed
    totalJobsProcessed
    totalMatchesGenerated
    averageProcessingTimeMs
    successRate
    lastExecutionTime
  }
}

Updates every 10 seconds.

14. `healthStream` - Health Status

Real-time health status updates.

subscription {
  healthStream {
    service
    database
    ray
    backgroundTasks
    rayDetails {
      totalCpus
      availableCpus
      cpuUtilization
    }
  }
}

Updates every 3 seconds.

Error Types

All pipeline subscriptions may return these error codes:

Code	Description
`VALIDATION_ERROR`	Input validation failed
`EXTRACTION_ERROR`	Data extraction failed
`MISSING_FIELD`	Required field missing
`DATABASE_ERROR`	Database operation failed
`AI_ERROR`	AI/LLM processing failed
`ONBOARDING_REQUIRED`	User onboarding not complete
`DUPLICATE_ENTRY`	Duplicate record detected
`UNEXPECTED_ERROR`	Unexpected system error

Notes

All pipeline subscriptions have a default timeout of 5 minutes (except generateMeetingInsight which has 10 minutes)
Progress updates are streamed in real-time (0-100%)
Use WebSocket connection for subscriptions
The GraphQL playground is available at https://ai.aiqlick.com/graphql

Connection​

Pipeline Subscriptions​

1. extractCV - CV Extraction​

2. parseJob - Job Description Parsing​

3. faceExtraction - Face Photo Extraction​

4. addCandidate - Full Candidate Pipeline​

5. userJobMatching - User-Job Match Score​

6. candidateJobMatching - Candidate-Job Match Score​

7. basicMatching - Basic Match Score (Domain Logic)​

8. textRewrite - AI Text Rewriting​

9. generateMeetingInsight - AI Meeting Insights​

System Subscriptions​

10. taskUpdated - Task Status Updates​

11. tasksStream - All Tasks Stream​

12. systemStatusStream - System Status​

13. metricsStream - System Metrics​

14. healthStream - Health Status​

Error Types​

Notes​

Connection

Pipeline Subscriptions

1. `extractCV` - CV Extraction

2. `parseJob` - Job Description Parsing

3. `faceExtraction` - Face Photo Extraction

4. `addCandidate` - Full Candidate Pipeline

5. `userJobMatching` - User-Job Match Score

6. `candidateJobMatching` - Candidate-Job Match Score

7. `basicMatching` - Basic Match Score (Domain Logic)

8. `textRewrite` - AI Text Rewriting

9. `generateMeetingInsight` - AI Meeting Insights

System Subscriptions

10. `taskUpdated` - Task Status Updates

11. `tasksStream` - All Tasks Stream

12. `systemStatusStream` - System Status

13. `metricsStream` - System Metrics

14. `healthStream` - Health Status

Error Types

Notes