POST /api/v1/users

Authentication

Requires Bearer token with users:write scope.

Request

Headers

Header	Required	Description
Authorization	Yes	Bearer token
Content-Type	Yes	`application/json`

Body Parameters

Parameter	Type	Required	Description
email	string	Yes	User's email address
name	string	Yes	User's display name
role	string	No	User role. Default: `member`

Example Request

```bash curl -X POST https://api.example.com/api/v1/users
-H "Authorization: Bearer sk_live_xxx"
-H "Content-Type: application/json"
-d '{ "email": "john@example.com", "name": "John Doe", "role": "admin" }' ```

Response

Success (201 Created)

```json { "data": { "id": "usr_abc123", "email": "john@example.com", "name": "John Doe", "role": "admin", "createdAt": "2026-01-15T10:30:00Z" } } ```

Error (400 Bad Request)

```json { "error": { "code": "VALIDATION_ERROR", "message": "Invalid request body", "details": [ { "field": "email", "message": "Email is already registered" } ] } } ```

Error Codes

Code	Description
VALIDATION_ERROR	Request body validation failed
UNAUTHORIZED	Missing or invalid authentication
RATE_LIMITED	Too many requests


## OpenAPI Specification

```yaml
openapi: 3.0.3
info:
  title: My API
  version: 1.0.0
  description: API for managing resources

servers:
  - url: https://api.example.com/v1
    description: Production

paths:
  /users:
    post:
      summary: Create user
      operationId: createUser
      tags:
        - Users
      security:
        - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateUserRequest'
      responses:
        '201':
          description: User created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '400':
          $ref: '#/components/responses/BadRequest'

components:
  schemas:
    User:
      type: object
      properties:
        id:
          type: string
          example: usr_abc123
        email:
          type: string
          format: email
        name:
          type: string
        createdAt:
          type: string
          format: date-time

    CreateUserRequest:
      type: object
      required:
        - email
        - name
      properties:
        email:
          type: string
          format: email
        name:
          type: string
          minLength: 1
          maxLength: 100

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

Library Documentation

Function Documentation

/**
 * Formats a date according to the specified pattern.
 *
 * @param date - The date to format
 * @param pattern - Format pattern string
 * @param options - Formatting options
 * @returns Formatted date string
 *
 * @example
 * ```ts
 * formatDate(new Date('2026-01-15'), 'YYYY-MM-DD')
 * // => '2026-01-15'
 *
 * formatDate(new Date(), 'MMM D, YYYY', { locale: 'en-US' })
 * // => 'Jan 15, 2026'
 * ```
 *
 * @see {@link parseDate} for the inverse operation
 * @since 1.0.0
 */
export function formatDate(
  date: Date,
  pattern: string,
  options?: FormatOptions
): string;

Class Documentation

/**
 * HTTP client for making API requests.
 *
 * @example
 * ```ts
 * const client = new ApiClient({
 *   baseUrl: 'https://api.example.com',
 *   apiKey: 'sk_live_xxx'
 * });
 *
 * const users = await client.get('/users');
 * ```
 */
export class ApiClient {
  /**
   * Creates a new API client instance.
   *
   * @param config - Client configuration
   * @throws {ConfigError} If required options are missing
   */
  constructor(config: ClientConfig);

  /**
   * Makes a GET request.
   *
   * @param path - API endpoint path
   * @param params - Query parameters
   * @returns Response data
   *
   * @throws {ApiError} If the request fails
   */
  async get<T>(path: string, params?: QueryParams): Promise<T>;
}

Documentation Sections

Overview/Introduction

# My SDK

Official SDK for the Example API.

## Features

- Full API coverage
- TypeScript support
- Automatic retries
- Rate limit handling

## Installation

\`\`\`bash
npm install @example/sdk
\`\`\`

## Quick Start

\`\`\`typescript
import { Client } from '@example/sdk';

const client = new Client({ apiKey: 'sk_xxx' });
const user = await client.users.create({
  email: 'john@example.com'
});
\`\`\`

Authentication

## Authentication

All API requests require authentication via API key.

### API Keys

Generate API keys in your [dashboard](https://dashboard.example.com).

| Key Type | Prefix | Use Case |
|----------|--------|----------|
| Live | `sk_live_` | Production |
| Test | `sk_test_` | Development |

### Usage

Include your API key in the `Authorization` header:

\`\`\`
Authorization: Bearer sk_live_xxx
\`\`\`

Error Handling

## Errors

The API uses standard HTTP status codes.

### Error Response Format

\`\`\`json
{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "User not found",
    "requestId": "req_abc123"
  }
}
\`\`\`

### Error Codes

| Code | Status | Description |
|------|--------|-------------|
| VALIDATION_ERROR | 400 | Invalid input |
| UNAUTHORIZED | 401 | Invalid API key |
| FORBIDDEN | 403 | Insufficient permissions |
| NOT_FOUND | 404 | Resource not found |
| RATE_LIMITED | 429 | Too many requests |

Authentication

Request

Headers

Body Parameters

Example Request

Response

Success (201 Created)

Error (400 Bad Request)

Error Codes

Library Documentation

Function Documentation

Class Documentation

Documentation Sections

Overview/Introduction

Authentication

Error Handling

Quality Checklist

api-docs

API Documentation Generator

When to Use

REST API Documentation

Endpoint Template