Agents API

v1.0 • REST • JSON

Full CRUD management for agent accounts. Create, retrieve, update, and delete agent records with built-in pagination and role-based access control support.

GET POST PUT DELETE 5 Endpoints
Base URL https://bogusapi.com/api/agents

Quick Reference

GET
/api/agents List all agents (paginated)
200 GET
/api/agents/{id} Get one agent by ID
200 POST
/api/agents Create a new agent
201 PUT
/api/agents/{id} Replace agent data
204 DEL
/api/agents/{id} Remove a agent
204 GET
/api/agents/{id} Agent not found example
404
GET /api/agents 200 OK

Get All Agents

Retrieves a paginated list of all agents in the system. Use the page and limit query parameters to navigate large result sets. The response envelope includes total count and page metadata.

Query Parameters
ParameterTypeDefaultDescription
page integer 1 Page number, 1-based index
limit integer 10 Number of records per page
Response: 200 OK
GET /api/agents/{id} 200 OK

Get Single Agent

Fetch the full profile for a specific agent using their numeric ID. Returns all agent fields including assigned role names and account metadata.

Path Parameters
ParameterTypeRequiredDescription
id integer Required Unique agent identifier
Response: 200 OK
GET /api/agents/{id} 404 Not Found

Agent Not Found

Returned when the requested agent ID does not exist in the system. Use this example to test error-handling logic and build graceful fallback UI for missing agent resources.

Response: 404 Not Found
POST /api/agents 201 Created

Create Agent

Registers a new agent with the provided details. On success, returns the newly created agent object including the auto-generated ID, timestamp, and resolved role names.

Request Body
Field Type Required Description
name string Required Name
description string Optional Description
agency string Required Agency
email string Required Email
phone string Required Phone
licenseNumber string Required License number
yearsOfExperience integer Required Years of experience
city string Required City
Body
Response: 201 Created
PUT /api/agents/{id} 200 OK

Update Agent

Fully replaces an existing agent's data with the values in the request body. A successful update returns 200 OK with response body.

Request Body
Field Type Required Description
name string Required Name
description string Optional Description
agency string Required Agency
email string Required Email
phone string Required Phone
licenseNumber string Required License number
yearsOfExperience integer Required Years of experience
city string Required City
Body
Response: 200 OK
DELETE /api/agents/{id} 204 No Content

Delete Agent

Permanently removes a agent from the system by their ID. This action is irreversible once deleted, the agent record and all associated data cannot be recovered through the API.

Path Parameters
ParameterTypeRequiredDescription
id integer Required ID of the agent to delete
Response: 204 No Content