# API Reference Template

## Overview

One-sentence description of what this API surface enables. State the primary use case and intended audience in plain language.

## Authentication

Describe supported methods (API keys, OAuth 2.0, JWT, etc.). Include how to obtain credentials, required scopes, and example header or query parameter usage. Note any rate limiting tied to authentication tier.

## Base URL

Production: `https://api.example.com/v1`
Staging: `https://staging.example.com/v1`

All endpoints are relative to the base URL unless otherwise noted.

## Resources & Operations

### `POST /v1/resources`

**Description**

What this operation accomplishes. One or two sentences maximum.

**Parameters**

| Name | Type | Required | Description |
|------|------|----------|-------------|
| `foo` | string | Yes | The identifier of the target resource. |
| `bar` | integer | No | Optional configuration value (default: 10). |

**Request Body**

```json
{
  "example": "value"
}
```

**Response**

**200 OK**

```json
{
  "id": "res_123",
  "status": "active"
}
```

**Error Responses**

- `400 Bad Request` — Invalid input
- `401 Unauthorized` — Missing or invalid credentials
- `429 Too Many Requests` — Rate limit exceeded

**Example**

```bash
curl -X POST https://api.example.com/v1/resources \n  -H "Authorization: Bearer $TOKEN" \n  -d '{"foo": "abc"}'
```

## Best Practices & Common Pitfalls

- List 3-5 recommendations for safe and efficient usage.
- Call out patterns that frequently cause developer friction.

## Related Resources

- Link to Getting Started guide
- Link to relevant Architecture Decision Records (ADRs)
- Link to SDK repositories and changelog

---

*This template follows Vellum standards. Adapt sections as needed while preserving required accuracy, completeness, and scannability.*