graphql-schema.md

GraphQL Schema Documentation

Note: This documentation is based on GraphQL introspection queries against the live API endpoint. It represents the current schema and should be updated when the backend schema changes.

Endpoint Information

• URL: Configured via VITE_GRAPHQL_URI environment variable (see .env.example)
• Authorization: x-api-key header
• Introspection: Enabled

Schema Overview

Candidate Type

The main Candidate object type with the following fields:

Required Fields (NON_NULL)

• id: ID! - Unique identifier
• firstName: String! - Candidate's first name
• lastName: String! - Candidate's last name
• status: CandidateStatus! - Application status (enum)
• score: Float! - Candidate score/rating
• createdAt: AWSDateTime! - Creation timestamp
• updatedAt: AWSDateTime! - Last update timestamp

Optional Fields (Nullable)

• email: String - Candidate's email address
• phoneNumber: String - Candidate's phone number

CandidateStatus Enum

enum CandidateStatus {
  APPLIED
  SHORTLISTED
  REJECTED
}

Queries

listCandidates

Fetches a paginated list of candidates with optional filtering.

listCandidates(
  filter: ModelCandidateFilterInput
  limit: Int
  nextToken: String
): ModelCandidateConnection

Arguments:

• filter - Optional filter input for searching/filtering candidates
• limit - Maximum number of items to return
• nextToken - Pagination token for fetching next page

Returns: ModelCandidateConnection

type ModelCandidateConnection {
  items: [Candidate]!
  nextToken: String
}

getCandidate

Fetches a single candidate by ID.

getCandidate(id: ID!): Candidate

Filter Capabilities

The ModelCandidateFilterInput supports filtering on:

String Fields (firstName, lastName, email, phoneNumber)

• eq - Equals
• ne - Not equals
• contains - Contains substring
• notContains - Does not contain substring
• beginsWith - Starts with
• between - Between two values
• le, lt, ge, gt - Comparison operators

Status Field

• eq - Equals specific status
• ne - Not equals specific status

Score Field (Float)

• eq, ne - Equality operators
• le, lt, ge, gt - Comparison operators
• between - Between two values

Logical Operators

• and: [ModelCandidateFilterInput] - AND condition
• or: [ModelCandidateFilterInput] - OR condition
• not: ModelCandidateFilterInput - NOT condition

Example Queries

List all candidates

query ListAllCandidates {
  listCandidates {
    items {
      id
      firstName
      lastName
      email
      phoneNumber
      status
      score
      createdAt
      updatedAt
    }
    nextToken
  }
}

Search by name

query SearchCandidates($searchTerm: String!) {
  listCandidates(
    filter: {
      or: [
        { firstName: { contains: $searchTerm } }
        { lastName: { contains: $searchTerm } }
      ]
    }
  ) {
    items {
      id
      firstName
      lastName
      email
      status
      score
    }
    nextToken
  }
}

Filter by status

query FilterByStatus($status: CandidateStatus!) {
  listCandidates(
    filter: {
      status: { eq: $status }
    }
  ) {
    items {
      id
      firstName
      lastName
      status
      score
    }
  }
}

Paginated query

query PaginatedCandidates($limit: Int, $nextToken: String) {
  listCandidates(limit: $limit, nextToken: $nextToken) {
    items {
      id
      firstName
      lastName
      status
    }
    nextToken
  }
}

Mutations

createCandidate

mutation CreateCandidate($input: CreateCandidateInput!) {
  createCandidate(input: $input) {
    id
    firstName
    lastName
    email
    phoneNumber
    status
    score
    createdAt
    updatedAt
  }
}

Input:

input CreateCandidateInput {
  id: ID
  firstName: String!
  lastName: String!
  email: String
  phoneNumber: String
  status: CandidateStatus!
  score: Float!
}

updateCandidate

mutation UpdateCandidate($input: UpdateCandidateInput!) {
  updateCandidate(input: $input) {
    id
    firstName
    lastName
    email
    phoneNumber
    status
    score
    updatedAt
  }
}

Input:

input UpdateCandidateInput {
  id: ID!
  firstName: String
  lastName: String
  email: String
  phoneNumber: String
  status: CandidateStatus
  score: Float
}

deleteCandidate

mutation DeleteCandidate($input: DeleteCandidateInput!) {
  deleteCandidate(input: $input) {
    id
  }
}

Input:

input DeleteCandidateInput {
  id: ID!
}

Custom Scalars

AWSDateTime

AWS AppSync datetime scalar representing ISO 8601 datetime strings.

Format: YYYY-MM-DDThh:mm:ss.SSSZ

Examples:

• 2025-10-14T19:00:00.000Z
• 1970-01-01T12:00:00.277Z
• 1970-01-01T12:00:00.123456789Z

Requirements:

• Time zone offset is required (either Z for UTC or ±hh:mm:ss)
• Nanoseconds field (1-9 digits) is optional
• Supports negative years (e.g., -2017-01-01T00:00Z)

TypeScript Type Definitions

See src/types/candidate.ts for the corresponding TypeScript types that match this schema.