Integration API (A2A)

JSON-RPC reference

A single JSON-RPC 2.0 endpoint, one method per interview operation.

Every call is POST /a2a/task (alias: POST /a2a — kept for teams already on Teamcast's original path) with a standard JSON-RPC 2.0 envelope. params is validated per-method against a Zod schema before it reaches any service code.

request

curl -X POST https://devapi.teamcast.ai/api/v2/a2a/task \
  -H "X-API-Key: sk_live_5f2c9a1b..." \
  -H "X-Tenant-ID: tnt_8a21b6" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "interview.create",
    "params": {
      "external_id": "ats-req-4471",
      "candidate_ref": "cand-9021",
      "position": "Senior Backend Engineer",
      "level": "SENIOR",
      "skills": ["Node.js", "PostgreSQL", "distributed systems"]
    }
  }'

Methods

Method	Params	Result
`interview.create`	InterviewCreateParams	RunAccepted
`interview.status`	`{ run_id }`	InterviewStatusResult
`interview.complete-info`	`{ run_id, fields }`	RunAccepted
`interview.approve`	`{ run_id, comment? }`	RunAccepted (approves the plan)
`interview.modify`	`{ run_id, comments }`	RunAccepted (requests a plan revision)
`assessment.approve`	`{ run_id, comment? }`	RunAccepted (approves + delivers the assessment)
`interview.rankings`	`{ position?, level? }`	Coverage-ranked candidate list
`assessment.chat`	`{ run_id, message }`	Deferred — reserved, not yet implemented

Success response

200 OK

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "run_id": "run_1735689600_a1f9c2",
    "interview_id": "int_7d2c...",
    "state": "GENERATING_PLAN",
    "message": "Interview run created."
  }
}

Errors

Standard JSON-RPC codes plus Teamcast's reserved application range (-32000..-32099). INFO_NEEDED is not a failure — it's the expected response when required candidate/role fields are missing.

Code	Name	Meaning
-32700	PARSE	Malformed JSON
-32600	INVALID_REQUEST	Envelope failed validation
-32601	METHOD_NOT_FOUND	Unknown method
-32602	INVALID_PARAMS	params failed the per-method schema
-32603	INTERNAL	Unexpected server error
-32001	INFO_NEEDED	Run needs more candidate/role data before planning can start
-32002	NOT_FOUND	run_id not found for this tenant
-32003	INVALID_STATE	Operation not valid for the run’s current state

INFO_NEEDED example

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32001,
    "message": "Additional candidate information required.",
    "data": {
      "missing_fields": [
        {
          "field": "candidate_resume",
          "severity": "recommended",
          "reason": "No resume or profile URL supplied",
          "question": "Can you provide the candidate's resume or LinkedIn URL?"
        }
      ]
    }
  }
}

run_id follows run_<epoch>_<hex> — treat it as an opaque identifier, not a parseable timestamp.

Was this page helpful?

Previous← Overview

NextREST →