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

# API Introduction

> Learn how to interact with the hans.ai API

## Base URL

All API requests should be made to:

```
https://api.hans.ai
```

For local development:

```
http://localhost:3010/api
```

## Authentication

The hans.ai API uses Bearer token authentication. Include your API key in the Authorization header:

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

### Getting your API Key

1. Sign in to your hans.ai account
2. Navigate to Settings → API Keys
3. Create a new API key or copy an existing one

## Request Format

All POST and PUT requests should include:

```bash theme={null}
Content-Type: application/json
```

Request bodies should be valid JSON.

## Response Format

All responses are returned as JSON:

```json theme={null}
{
  "success": true,
  "data": {
    // Response data
  }
}
```

Error responses include:

```json theme={null}
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable error message"
  }
}
```

## Rate Limiting

API requests are rate limited to:

* **Free tier**: 100 requests per hour
* **Pro tier**: 1,000 requests per hour
* **Enterprise**: Custom limits

Rate limit information is included in response headers:

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

## Pagination

List endpoints support pagination:

```bash theme={null}
GET /api/notifications?page=1&limit=20
```

Paginated responses include:

```json theme={null}
{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "pages": 5
  }
}
```

## Error Codes

| Code               | Description                |
| ------------------ | -------------------------- |
| `UNAUTHORIZED`     | Invalid or missing API key |
| `FORBIDDEN`        | Insufficient permissions   |
| `NOT_FOUND`        | Resource not found         |
| `VALIDATION_ERROR` | Invalid request data       |
| `RATE_LIMITED`     | Too many requests          |
| `SERVER_ERROR`     | Internal server error      |

## SDK Libraries

Official SDKs are coming soon for:

* JavaScript/TypeScript
* Python
* Go
* Ruby

## API Endpoints

<CardGroup cols={2}>
  <Card title="Notifications" icon="bell" href="/api-reference/endpoint/notifications">
    Create and manage notification tasks
  </Card>

  <Card title="Actions" icon="bolt" href="/api-reference/endpoint/actions">
    Configure notification actions
  </Card>

  <Card title="Execute" icon="play" href="/api-reference/endpoint/execute">
    Manually trigger task execution
  </Card>

  <Card title="Schedule" icon="clock" href="/api-reference/endpoint/schedule">
    Manage task schedules
  </Card>
</CardGroup>