Architecture

JSON-RPC 2.0

Internal protocol reference for agent-to-agent systems implementing the A2A spec.

This endpoint is for internal and agent-native integrations only. If you are building a REST-based integration — for example, connecting LinkedIn, an ATS, or an HR platform — use the REST endpoints under /api/v1/integration/interviews/... instead. Those endpoints are stable, versioned, and designed for partner use.

The JSON-RPC 2.0 interface provides a single endpoint that routes to any interview management method. This style is intended for systems that are themselves AI agents or automated pipelines implementing the full A2A protocol spec.

Protocol

Property	Value
Endpoint	POST /api/v1/a2a/task
Content-Type	application/json
Auth	X-API-Key or Bearer JWT
Spec	JSON-RPC 2.0 (https://www.jsonrpc.org/specification)

Every request must include jsonrpc: "2.0", a method, params, and an id.

Request envelope

{
  "jsonrpc": "2.0",
  "method": "<method-name>",
  "params": { ... },
  "id": 1
}

Success response envelope

{
  "jsonrpc": "2.0",
  "result": { ... },
  "id": 1
}

Error response envelope

{
  "jsonrpc": "2.0",
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": { "field": "candidateEmail", "issue": "Invalid email format" }
  },
  "id": 1
}

Error Codes

Code	Meaning
-32700	Parse error — invalid JSON
-32600	Invalid Request — not a valid JSON-RPC object
-32601	Method not found
-32602	Invalid params
-32603	Internal error
-32001	Authentication failed
-32002	Insufficient permissions
-32003	Interview not found
-32004	Invalid state transition

Methods

Method	Permission	Description
interview.create	interview:create	Create a new interview request
interview.status	interview:read	Get current workflow status by runId
interview.approve	interview:approve	Approve or reject a plan
interview.complete-info	interview:update	Provide missing HITL data (by runId)
interview.modify	interview:approve	Request plan changes with recruiter comments
assessment.approve	interview:approve	Approve or reject final assessment verdict
interview.rankings	interview:read	Get candidate rankings by assessment score

interview.create

Request

bash

curl -X POST https://mayaapi.teamcast.ai/api/v1/a2a/task \
  -H "X-API-Key: your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "interview.create",
    "params": {
      "candidateName": "Jane Smith",
      "candidateEmail": "jane@example.com",
      "position": "Senior Engineer",
      "level": "SENIOR",
      "skills": ["TypeScript", "React", "Node.js"],
      "jobDescription": "Build scalable platform services.",
      "callbackUrl": "https://ats.example.com/webhook"
    },
    "id": 1
  }'

Response

json

{
  "jsonrpc": "2.0",
  "result": {
    "runId": "agno-run-uuid",
    "interviewId": "interview-uuid",
    "state": "VALIDATING_SKILLS",
    "message": "Interview request accepted.",
    "dataQuality": "EXCELLENT"
  },
  "id": 1
}

interview.status

json

{
  "jsonrpc": "2.0",
  "method": "interview.status",
  "params": { "runId": "agno-run-uuid" },
  "id": 2
}

interview.approve

json

{
  "jsonrpc": "2.0",
  "method": "interview.approve",
  "params": {
    "runId": "agno-run-uuid",
    "approved": true,
    "userId": "recruiter-uuid"
  },
  "id": 3
}

interview.modify

json

{
  "jsonrpc": "2.0",
  "method": "interview.modify",
  "params": {
    "runId": "agno-run-uuid",
    "userId": "recruiter-uuid",
    "comments": "Add more system design questions. Reduce basic syntax checks."
  },
  "id": 4
}

assessment.approve

json

{
  "jsonrpc": "2.0",
  "method": "assessment.approve",
  "params": {
    "interviewId": "interview-uuid",
    "userId": "recruiter-uuid",
    "approved": true,
    "recruiterScores": {
      "technical": { "typescript_proficiency": 4, "system_design": 3 },
      "communication": { "clarity": 4 }
    }
  },
  "id": 5
}

interview.rankings

json

{
  "jsonrpc": "2.0",
  "method": "interview.rankings",
  "params": { "position": "Senior Engineer", "level": "SENIOR" },
  "id": 6
}

For simpler human-readable integrations (ATS webhooks, admin tools), use the REST endpoints instead of JSON-RPC 2.0.

Was this page helpful?

NextIntroduction →