API Reference

Workflow

Trigger state machine transitions and query workflow history for interviews.

The workflow API exposes the HITL state machine transitions. Use it to manually trigger state changes (approve, reject, schedule) and to retrieve transition history for audit trails.

Endpoints

Method	Endpoint	Permission	Description
POST	/workflow/interviews/:id/transition	interview:approve	Trigger state transition
GET	/workflow/interviews/:id/history	interview:read	Get transition history
GET	/workflow/interviews/:id/available-transitions	interview:read	List valid next states

POST /workflow/interviews/:id/transition

Trigger an explicit workflow transition. The available transitions depend on the current state — use the available-transitions endpoint to see valid options before calling.

bash

curl -X POST http://localhost:3009/api/v1/workflow/interviews/interview-uuid/transition \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "transition": "APPROVE",
    "userId": "recruiter-uuid",
    "reason": "Plan looks comprehensive and well-structured"
  }'

Response 200

{
  "interviewId": "interview-uuid",
  "previousState": "PENDING",
  "newState": "APPROVED",
  "transition": "APPROVE",
  "triggeredBy": "recruiter-uuid",
  "reason": "Plan looks comprehensive and well-structured",
  "timestamp": "2024-01-15T11:00:00.000Z"
}

Transition	From State	To State	Description
VALIDATE	RECEIVED	VALIDATING_SKILLS	Start skill validation
REQUEST_INFO	RECEIVED	INFO_NEEDED	Request missing data from HITL
COMPLETE_INFO	INFO_NEEDED	VALIDATING_SKILLS	Info completed by HITL
GENERATE_PLAN	VALIDATING_SKILLS	GENERATING_PLAN	Agno begins plan generation
PLAN_READY	GENERATING_PLAN	PENDING	Plan ready for review
APPROVE	PENDING	APPROVED	Recruiter approves plan
REJECT	PENDING	REJECTED	Recruiter rejects plan
MODIFY	PENDING	GENERATING_PLAN	Recruiter requests changes
SCHEDULE	APPROVED	SCHEDULED	Interview scheduled
START	SCHEDULED	IN_PROGRESS	Interview session started
COMPLETE	IN_PROGRESS	COMPLETED	Interview session ended
ASSESS	COMPLETED	ASSESSMENT_PENDING	Assessment ready for review
APPROVE_ASSESSMENT	ASSESSMENT_PENDING	ASSESSMENT_APPROVED	Assessment approved
CANCEL	*	CANCELLED	Cancel at any stage

GET /workflow/interviews/:id/history

Returns the full audit trail of all state transitions for an interview.

bash

curl http://localhost:3009/api/v1/workflow/interviews/interview-uuid/history \
  -H "Authorization: Bearer <jwt>"

Response 200

{
  "interviewId": "interview-uuid",
  "transitions": [
    {
      "id": "transition-uuid",
      "from": "RECEIVED",
      "to": "VALIDATING_SKILLS",
      "transition": "VALIDATE",
      "triggeredBy": "system",
      "reason": "Data validation passed",
      "timestamp": "2024-01-15T10:00:00.000Z"
    },
    {
      "id": "transition-uuid-2",
      "from": "VALIDATING_SKILLS",
      "to": "PENDING",
      "transition": "PLAN_READY",
      "triggeredBy": "agno-agent",
      "reason": "Plan generation complete",
      "timestamp": "2024-01-15T10:45:00.000Z"
    }
  ]
}

GET /workflow/interviews/:id/available-transitions

Returns the list of valid transitions from the interview's current state. Use this to conditionally render action buttons in the admin UI.

bash

curl http://localhost:3009/api/v1/workflow/interviews/interview-uuid/available-transitions \
  -H "Authorization: Bearer <jwt>"

Response 200 (state: PENDING)

{
  "currentState": "PENDING",
  "transitions": [
    {
      "name": "APPROVE",
      "description": "Approve the plan and generate candidate link",
      "requiredPermission": "interview:approve"
    },
    {
      "name": "REJECT",
      "description": "Reject the plan with a reason",
      "requiredPermission": "interview:approve"
    },
    {
      "name": "MODIFY",
      "description": "Request plan modifications from the AI agent",
      "requiredPermission": "interview:approve"
    },
    {
      "name": "CANCEL",
      "description": "Cancel this interview entirely",
      "requiredPermission": "interview:delete"
    }
  ]
}

Invalid transitions return a 400 Bad Request with the message "Transition X is not valid from state Y". Always check available transitions before calling.

Was this page helpful?

Previous← Candidate Access

NextUsers & Tenants →