> ## Documentation Index
> Fetch the complete documentation index at: https://mako-docs.devinagiffy.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# API Introduction

> Getting started with the Hitler API

## Overview

The Hitler API is a RESTful API that powers all Hitler functionality. Whether you're building a custom integration, bot adapter, or admin tool, this API provides the foundation.

## Base URL

<CodeGroup>
  ```bash Production theme={null}
  https://api.hitler.app/api
  ```

  ```bash Development theme={null}
  http://localhost:3001/api
  ```
</CodeGroup>

## Authentication

Most endpoints require authentication via JWT bearer token.

```bash theme={null}
curl -X GET "https://api.hitler.app/api/auth/me" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"
```

See [Authentication](/api-reference/authentication) for details on obtaining tokens.

## Request Format

### Headers

| Header          | Required | Description                                |
| --------------- | -------- | ------------------------------------------ |
| `Authorization` | Yes\*    | Bearer token for authenticated endpoints   |
| `Content-Type`  | Yes      | `application/json` for POST/PATCH requests |

\*Not required for public endpoints like login/register

### Request Body

POST and PATCH requests expect JSON:

```json theme={null}
{
  "email": "user@example.com",
  "password": "securepassword"
}
```

## Response Format

### Success Response

```json theme={null}
{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "email": "user@example.com",
  "name": "John Doe",
  "createdAt": "2024-01-15T10:30:00.000Z"
}
```

### Error Response

```json theme={null}
{
  "statusCode": 400,
  "message": "Validation failed",
  "error": "Bad Request"
}
```

## Status Codes

| Code  | Description                             |
| ----- | --------------------------------------- |
| `200` | Success                                 |
| `201` | Created                                 |
| `400` | Bad Request - Invalid input             |
| `401` | Unauthorized - Missing or invalid token |
| `403` | Forbidden - Insufficient permissions    |
| `404` | Not Found                               |
| `409` | Conflict - Resource already exists      |
| `500` | Internal Server Error                   |

## Rate Limiting

| Endpoint Type      | Limit                |
| ------------------ | -------------------- |
| Standard endpoints | 100 requests/minute  |
| Auth endpoints     | 20 requests/minute   |
| Webhook endpoints  | 1000 requests/minute |

Rate limit headers:

```
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642089600
```

## Pagination

List endpoints support pagination:

```bash theme={null}
GET /api/tasks?limit=20&offset=0
```

Response includes pagination info:

```json theme={null}
{
  "data": [...],
  "total": 150,
  "limit": 20,
  "offset": 0
}
```

## Filtering

Many endpoints support query filters:

```bash theme={null}
GET /api/tasks?status=open
GET /api/moods?days=30
GET /api/flags?status=active
```

## SDKs & Libraries

<CardGroup cols={2}>
  <Card title="TypeScript SDK" icon="js">
    Official SDK for Node.js and browser

    ```bash theme={null}
    npm install @hitler/sdk
    ```
  </Card>

  <Card title="OpenAPI Spec" icon="file-code">
    Download the OpenAPI 3.0 specification

    [Download JSON](/openapi.json)
  </Card>
</CardGroup>

## Interactive Docs

For interactive API exploration, visit our Swagger UI:

* **Production**: [api.hitler.app/docs](https://api.hitler.app/docs)
* **Development**: [localhost:3000/docs](http://localhost:3000/docs)

## API Modules

<CardGroup cols={3}>
  <Card title="Auth" icon="key" href="/api-reference/auth/login">
    Login, register, token management
  </Card>

  <Card title="Organizations" icon="building" href="/api-reference/organizations/create">
    Organization management
  </Card>

  <Card title="Users" icon="users" href="/api-reference/users/list">
    User CRUD operations
  </Card>

  <Card title="Tasks" icon="list-check" href="/api-reference/tasks/overview">
    Task and draft management
  </Card>

  <Card title="Chat" icon="message" href="/api-reference/chat/send-message">
    Conversational AI interface
  </Card>

  <Card title="Moods" icon="heart" href="/api-reference/moods/log">
    Mood tracking
  </Card>

  <Card title="Flags" icon="flag" href="/api-reference/flags/overview">
    Wellbeing flags
  </Card>
</CardGroup>