How to document POST endpoints

POST endpoints create resources. Your documentation must clearly describe required fields, validation rules, and failure behavior.

What to document for POST endpoints

For each POST endpoint, include:

1. Purpose - What resource gets created
2. Method and URL - For example, POST /api/v1/users
3. Authentication and headers - Required token and Content-Type
4. Request body schema - Field name, type, required status, and validation
5. Success response - Usually 201 Created with created resource payload
6. Validation and error responses - Common 400, 401, and 409 patterns

Example: Create a new user

• Endpoint summary: Creates a new user account.
• Method: POST
• URL: /api/v1/users
• Authentication: Bearer token required
• Headers:
  • Content-Type: application/json
  • Authorization: Bearer <token>

Request body

Request example

curl -X POST "https://api.example.com/api/v1/users" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <token>" \
  -d '{
    "name": "Asha Verma",
    "email": "asha.verma@example.com",
    "role": "editor"
  }'

Success response (201)

{
  "id": "u_456",
  "name": "Asha Verma",
  "email": "asha.verma@example.com",
  "role": "editor",
  "createdAt": "2026-02-24T10:30:00Z"
}

Validation error (400)

{
  "error": {
    "code": "INVALID_EMAIL",
    "message": "email must be a valid email address"
  }
}