Response Format

All TechLadder API endpoints return a consistent JSON response envelope.

Success Response

{
  "status_code": 200,
  "message": "Descriptive success message",
  "error": null,
  "data": {
    // Response payload — varies per endpoint
  }
}

Field	Type	Description
status_code	integer	HTTP status code
message	string	Human-readable description of the result
error	null	Always null on success
data	object	The response payload (endpoint-specific)

Error Response

{
  "status_code": 400,
  "message": "Invalid request body",
  "error": {
    "code": "VALIDATION_ERROR",
    "details": [
      "phone_number: Must be at least 10 digits",
      "agent_name: This field is required"
    ]
  },
  "data": null
}

Field	Type	Description
status_code	integer	HTTP status code
message	string	Human-readable error summary
error.code	string	Machine-readable error code
error.details	string[]	List of specific error messages
data	null	Always null on error

Pagination

List endpoints return paginated results:

{
  "status_code": 200,
  "message": "Call batches fetched successfully",
  "error": null,
  "data": {
    "items": [...],
    "total": 142,
    "page": 1,
    "limit": 50,
    "has_more": true
  }
}

Pagination Parameters

Parameter	Type	Default	Description
page	integer	1	Page number (1-indexed)
limit	integer	50	Items per page (max: 100)

Timestamps

All timestamps are in ISO 8601 format in UTC:

2026-05-14T10:30:00Z

IDs

Resources use prefixed IDs for easy identification:

Resource	Prefix	Example
Schedule/Batch	sched_	sched_7bac6f2a
Agent	agt-	agt-57949b14
Call	call_	call_a1b2c3d4
Webhook Endpoint	wh_	wh_e5f6g7h8
Webhook Event	evt_	evt_i9j0k1l2