API Reference

Report Builder API

Create, retrieve, and manage automated reports programmatically over a simple REST interface.

This is a technical writing sample documenting a representative REST API, demonstrating endpoint structure, parameter tables, request/response examples, and error handling.

Authentication

All requests require an API key passed in the Authorization header. Keys are issued from your account dashboard.

Authorization: Bearer YOUR_API_KEY

Keep your key secret. Treat your API key like a password. Do not commit it to source control or expose it in client-side code.

Base URL

All endpoints are relative to the following base URL.

https://api.example.com/v1

Create a report

Creates a new report from a data source. Provide an optional schedule to generate it on a recurring basis.

POST /reports

Body parameters

Parameter	Type	Description
`name`	string	Required A display name for the report.
`source_id`	string	Required The ID of the data source to build from.
`schedule`	string	Optional A cron expression for recurring generation. Omit for a one-time report.

Example request

curl -X POST https://api.example.com/v1/reports \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Weekly Sales",
    "source_id": "src_8821",
    "schedule": "0 9 * * 1"
  }'

Example response 201 Created

{
  "id": "rep_4f7a",
  "name": "Weekly Sales",
  "source_id": "src_8821",
  "schedule": "0 9 * * 1",
  "status": "active",
  "created_at": "2026-06-21T09:00:00Z"
}

Retrieve a report

Returns the details of a single report by its ID.

GET /reports/{id}

Example request

curl https://api.example.com/v1/reports/rep_4f7a \
  -H 'Authorization: Bearer YOUR_API_KEY'

List all reports

Returns a paginated list of all reports in your account.

GET /reports

Query parameters

Parameter	Type	Description
`limit`	integer	Optional Number of results to return. Default 20, maximum 100.
`status`	string	Optional Filter by status: `active` or `paused`.

Error responses

The API uses standard HTTP status codes. Errors return a JSON body with a code and a human-readable message.

Status	Code	Meaning
400	`invalid_request`	A required parameter is missing or malformed.
401	`unauthorized`	The API key is missing or invalid.
404	`not_found`	No report exists with the given ID.
429	`rate_limited`	Too many requests. Retry after the period in the `Retry-After` header.

Example error 404 Not Found

{
  "code": "not_found",
  "message": "No report found with ID rep_0000."
}