Prompt
customer-facing API reference docs
Latest observation
Nov 10, 2026
OpenAI APIWeb search: off
Here’s a clean, customer-facing way to present API reference docs:
API Reference
This reference documents the endpoints available in our API, including request formats, authentication, parameters, response schemas, and error handling.
Base URL
https://api.example.com/v1
Authentication
All requests must include an API key in the Authorization header:
Authorization: Bearer YOUR_API_KEY
Content Type
Requests and responses use JSON:
Content-Type: application/json
Endpoints
GET /customers
Retrieves a list of customers.
Request
GET /customers?page=1&limit=25
Query Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| page | integer | No | Page number |
| limit | integer | No | Number of results per page |
Response
{
"data": [
{
"id": "cust_123",
"name": "Acme Corp",
"email": "billing@acme.com"
}
],
"meta": {
"page": 1,
"limit": 25,
"total": 1
}
}
Errors
401 Unauthorized— Missing or invalid API key400 Bad Request— Invalid query parameters
POST /customers
Creates a new customer.
Request Body
{
"name": "Acme Corp",
"email": "billing@acme.com"
}
Fields
| Name | Type | Required | Description |
|---|---|---|---|
| name | string | Yes | Customer name |
| string | Yes | Customer email address |
Response
{
"id": "cust_123",
"name": "Acme Corp",
"email": "billing@acme.com",
"created_at": "2026-01-01T12:00:00Z"
}
Errors
400 Bad Request— Invalid request body409 Conflict— Customer already exists
GET /customers/{customer_id}
Retrieves a specific customer by ID.
Path Parameters
| Name | Type | Required | Description |
|---|---|---|---|
| customer_id | string | Yes | Customer ID |
Response
{
"id": "cust_123",
"name": "Acme Corp",
"email": "billing@acme.com"
}
Errors
404 Not Found— Customer does not exist
Error Format
All errors return a consistent JSON structure:
{
"error": {
"code": "invalid_request",
"message": "The email field is required."
}
}
Common HTTP Status Codes
| Code | Meaning |
|---|---|
| 200 | OK |
| 201 | Created |
| 400 | Bad Request |
| 401 | Unauthorized |
| 404 | Not Found |
| 409 | Conflict |
| 500 | Internal Server Error |
Rate Limits
Requests are limited to 100 requests per minute per API key.
When the limit is exceeded, the API returns:
429 Too Many Requests
Example Request
curl -X POST "https://api.example.com/v1/customers" \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Corp",
"email": "billing@acme.com"
}'
If you want, I can also turn this into:
- a more polished product-doc style,
- a developer portal format with examples per language, or
- a template for your actual API with your endpoints and fields filled in.