REST endpoint reference

{
  "run_id":          "run_1720000000_a1b2",
  "interview_id":    "int_01j2kpq...",
  "state":           "PENDING",
  "awaiting_human":  true,
  "coverage_summary": null         // populated when state = ASSESSMENT_READY or COMPLETED
}

{
  "run_id":       "run_1720000000_a1b2",
  "interview_id": "int_01j2kpq...",
  "payload":      { /* full plan object with competencies and question topics */ }
}

curl -X PATCH https://devapi.teamcast.ai/api/v2/integration/interviews/run_.../info \
  -H "X-API-Key: ..." -H "X-Tenant-ID: ..." \
  -H "Content-Type: application/json" \
  -d '{
    "fields": {
      "job_description": "Full role description text...",
      "skills":          "TypeScript, AWS, System Design"
    }
  }'

# Approve — advances to APPROVED
curl -X POST https://devapi.teamcast.ai/api/v2/integration/interviews/run_.../plan/approve \
  -H "X-API-Key: ..." -H "X-Tenant-ID: ..." \
  -H "Content-Type: application/json" \
  -d '{ "comment": "Looks good — solid competency coverage" }'

# Reject — terminal REJECTED state
curl -X POST https://devapi.teamcast.ai/api/v2/integration/interviews/run_.../plan/reject \
  -H "X-API-Key: ..." -H "X-Tenant-ID: ..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Role requirements changed" }'

# Revise — returns to GENERATING_PLAN then to PENDING when ready
curl -X PATCH https://devapi.teamcast.ai/api/v2/integration/interviews/run_.../plan/revise \
  -H "X-API-Key: ..." -H "X-Tenant-ID: ..." \
  -H "Content-Type: application/json" \
  -d '{ "comments": "Focus more on system design. Reduce basic syntax questions." }'

{
  "run_id":       "run_1720000000_a1b2",
  "interview_id": "int_01j2kpq...",
  "state":        "APPROVED",
  "message":      "plan approved"
}

curl -X POST https://devapi.teamcast.ai/api/v2/integration/interviews/run_.../invite \
  -H "X-API-Key: ..." -H "X-Tenant-ID: ..." \
  -H "Content-Type: application/json" \
  -d '{
    "ttl_seconds": 259200,
    "base_url":    "https://app.teamcast.ai"
  }'

{
  "run_id":       "run_1720000000_a1b2",
  "interview_id": "int_01j2kpq...",
  "joinLink":     "https://app.teamcast.ai/interview/join/eyJhbGc...",
  "otp":          "847291",
  "expiresAt":    "2026-07-17T10:00:00.000Z"
}

# Approve — advances to COMPLETED
curl -X POST https://devapi.teamcast.ai/api/v2/integration/interviews/run_.../assessment/approve \
  -H "X-API-Key: ..." -H "X-Tenant-ID: ..." \
  -H "Content-Type: application/json" \
  -d '{ "comment": "Coverage looks solid. Approving." }'

# Reject — terminal REJECTED state
curl -X POST https://devapi.teamcast.ai/api/v2/integration/interviews/run_.../assessment/reject \
  -H "X-API-Key: ..." -H "X-Tenant-ID: ..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Assessment quality insufficient — significant gaps remain." }'

{
  "run_id":       "run_1720000000_a1b2",
  "interview_id": "int_01j2kpq...",
  "state":        "COMPLETED",
  "message":      "assessment approved",
  "coverage_summary": {
    "overall_coverage": "sufficient",
    "gap_competencies": ["distributed-systems"],
    "covered_count":    5,
    "total_count":      6
  }
}

{
  "run_id":           "run_1720000000_a1b2",
  "interview_id":     "int_01j2kpq...",
  "overall_coverage": "sufficient",
  "payload": {
    "coverage_summary": {
      "overall_coverage":             "sufficient",
      "gap_competencies":             ["leadership"],
      "competencies_well_evidenced":  2,
      "competencies_with_gaps":       1,
      "hitl_flags":                   ["unmet_essential:leadership"]
    },

    "competencies": [
      {
        "competency_id":        "analytical",
        "score":                0.35,
        "role_importance":      1.2,
        "requirement_type":     "essential",
        "sub_dimension_scores":  { "problem_diagnosis": 0.47, "decision_quality": 0.24 },
        "sub_dimension_weights": { "problem_diagnosis": 0.5,  "decision_quality": 0.5 }
      }
      // ... one per competency
    ],

    "sub_dimension_details": [
      {
        "competency_id":    "analytical",
        "sub_dimension_id": "problem_diagnosis",
        "score":            0.47,
        "rubric":           1.0,
        "observed_signals": 3,
        "coverage_factor":  1.0
      }
    ],

    "traces": [
      {
        "signal_id":        "diagnostic_reasoning",
        "competency_id":    "analytical",
        "sub_dimension_id": "problem_diagnosis",
        "strength":         0.8,
        "merged_duplicates": 0,
        "refs": [
          {
            "utterance_id":     "u6",
            "evidence_type_id": "direct_quote",
            "strength":         0.8,
            "quote":            "So we first take all the loggers and track out...",
            "measures": { "quality": 0.8, "confidence": 0.888, "contribution": 0.639 /* ...full block */ }
          }
        ]
      }
      // ... one per scored signal (dark signals have strength 0 and no refs)
    ],

    "narrative": {
      "highlights_text": "Strongest evidence in problem diagnosis...",
      "lowlights_text":  "Leadership was thinly surfaced...",
      "method":          "deterministic"
    },
    "highlights": { "episodes": [], "gaps": [], "lowlights": [] },

    // Additive 13-stage projection for the recruiter Detailed view — present on recently-scored
    // payloads, omitted on legacy ones. Full shape: /docs/measurement/deliverable
    "stage_trace": { "stages": [ /* 13 */ ], "segmentation": [], "evidence_units": [], "era_cot": null },

    "ontology_version":       "4.0.0",
    "signal_weights_version": "1.3.0"
  }
}

{
  "run_id":         "run_1720000000_a1b2",
  "interview_id":   "int_01j2kpq...",
  "transcript":     [],    // array of { speaker, text, offset_ms }
  "proctor_events": []     // proctoring signal events
}

curl "https://devapi.teamcast.ai/api/v2/integration/rankings?position=Senior+Engineer&level=SENIOR" \
  -H "X-API-Key: ..." -H "X-Tenant-ID: ..."

[{
  "rank":             1,
  "interview_id":     "int_01j2kpq...",
  "run_id":           "run_1720000000_a1b2",
  "candidate_name":   "Alex Rivera",
  "candidate_email":  null,
  "position":         "Senior Software Engineer",
  "level":            "senior",
  "overall_coverage": "sufficient",
  "gap_count":        1,
  "created_at":       "2026-07-14T09:00:00.000Z"
}]

# Cancel a still-in-flight run → terminal CANCELLED state
curl -X DELETE https://devapi.teamcast.ai/api/v2/integration/interviews/run_... \
  -H "X-API-Key: ..." -H "X-Tenant-ID: ..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Position filled before interview completed" }'

# Purge candidate PII — recording, transcript, resume, name, email all nulled
# The assessment and audit trail are retained. Irreversible.
curl -X DELETE https://devapi.teamcast.ai/api/v2/integration/interviews/run_.../candidate-data \
  -H "X-API-Key: ..." -H "X-Tenant-ID: ..." \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Retention window elapsed" }'

{
  "purged":    true,
  "purged_at": "2026-07-14T10:00:00.000Z"
}

{
  "statusCode": 400,
  "message":    "level: Invalid enum value. Expected 'ENTRY' | 'MID' | 'SENIOR' | 'LEAD' | 'EXEC'"
}