A2A Protocol

REST Endpoints

RESTful A2A endpoints for ATS integrations and human-readable API consumers.

The REST endpoints mirror all JSON-RPC 2.0 functionality in a conventional HTTP style. These are recommended for ATS integrations, third-party tools, and any integration where human readability and standard HTTP tooling matter.

Endpoints

Method	Endpoint	Description
POST	/a2a/interview	Create interview request
GET	/a2a/interview/:runId/status	Poll interview status
PATCH	/a2a/interview/:id/complete-info	HITL: provide missing fields
POST	/a2a/interview/:runId/approve	HITL: approve or reject plan
PATCH	/a2a/interview/:runId/request-modification	HITL: request plan changes
POST	/a2a/interview/:id/approve-assessment	HITL: approve/reject assessment

POST /a2a/interview

Create an interview request. On success the system starts skill validation (if data is complete) or enters INFO_NEEDED state (if data is incomplete).

Request Body

Field	Type	Required	Description
candidateName	string	Yes	Full name of the candidate
candidateEmail	string	Yes	Email address for OTP delivery
position	string	Yes	Job title being interviewed for
level	string	Yes	JUNIOR / MID / SENIOR / LEAD / PRINCIPAL
skills	string[]	Yes (1+)	Skill names to validate and assess
jobDescription	string	Yes (50+ chars)	Detailed role description for plan generation
companyName	string	No	Company name — used in Maya's greeting and InMail draft
companyDescription	string	No	Brief company overview — enriches greeting and InMail draft
callbackUrl	string	No	HTTPS URL to receive webhook events
scheduledAt	ISO date	No	Pre-schedule interview time

Example — Complete Data

bash

curl -X POST http://localhost:3009/api/v1/a2a/interview \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "candidateName": "Jane Smith",
    "candidateEmail": "jane@example.com",
    "position": "Senior Software Engineer",
    "level": "SENIOR",
    "skills": ["TypeScript", "React", "Node.js", "PostgreSQL"],
    "jobDescription": "Join our platform team to build scalable web applications with modern tech stack.",
    "companyName": "Acme Corp",
    "companyDescription": "Acme Corp builds developer tools used by over 50,000 engineers worldwide.",
    "callbackUrl": "https://ats.example.com/webhook"
  }'

Response 201 — VALIDATING_SKILLS

{
  "runId": "agno-run-uuid",
  "interviewId": "interview-uuid",
  "state": "VALIDATING_SKILLS",
  "message": "Interview request accepted. Skill validation in progress.",
  "dataQuality": "EXCELLENT"
}

Example — Incomplete Data

Response 201 — INFO_NEEDED

{
  "runId": "agno-run-uuid",
  "interviewId": "interview-uuid",
  "state": "INFO_NEEDED",
  "message": "Missing critical data. Please provide the required fields.",
  "dataQuality": "POOR",
  "missingFields": [
    {
      "field": "jobDescription",
      "severity": "HIGH",
      "reason": "Job description too brief (< 50 chars)",
      "question": "Please provide a detailed job description"
    }
  ]
}

GET /a2a/interview/:runId/status

Poll the current state of an interview.

bash

curl http://localhost:3009/api/v1/a2a/interview/agno-run-uuid/status \
  -H "X-API-Key: your_api_key"

Response 200

{
  "runId": "agno-run-uuid",
  "interviewId": "interview-uuid",
  "state": "PENDING",
  "plan": {
    "id": "plan-uuid",
    "generatedAt": "2024-01-15T10:45:00.000Z"
  }
}

POST /a2a/interview/:runId/approve

bash

# Approve
curl -X POST http://localhost:3009/api/v1/a2a/interview/agno-run-uuid/approve \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "approved": true, "userId": "recruiter-uuid" }'

# Reject
curl -X POST http://localhost:3009/api/v1/a2a/interview/agno-run-uuid/approve \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{ "approved": false, "userId": "recruiter-uuid", "reason": "Plan too basic for senior role." }'

Response 200 — approved

{
  "message": "Interview plan approved. Candidate link generated.",
  "workflowState": "APPROVED",
  "interviewLink": "https://app.ai-interview.com/interview/join/abc123token",
  "inmailDraft": {
    "subject": "Senior Software Engineer Opportunity at Acme Corp — Interview Invitation",
    "body": "Hi Jane,\n\nI came across your profile and was impressed by your TypeScript and React expertise. At Acme Corp we build developer tools used by 50,000+ engineers...\n\nPlease click the link below to begin your interview:\nhttps://app.ai-interview.com/interview/join/abc123token\n\nBest regards,\nThe Acme Corp Recruiting Team"
  }
}

PATCH /a2a/interview/:runId/request-modification

bash

curl -X PATCH http://localhost:3009/api/v1/a2a/interview/agno-run-uuid/request-modification \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "userId": "recruiter-uuid",
    "comments": "Add more system design questions. Candidate has 8 years experience."
  }'

Response 200

{
  "message": "Modification requested. Agent will regenerate the plan.",
  "workflowState": "GENERATING_PLAN"
}

All REST endpoints publish the same Kafka events and fire the same webhooks as the JSON-RPC 2.0 interface. They are functionally equivalent — choose based on preference.

Was this page helpful?

Previous← JSON-RPC 2.0

NextHITL Workflow →