API Introduction - hans.ai Documentation

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:

Authorization: Bearer YOUR_API_KEY

Getting your API Key

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

Request Format

All POST and PUT requests should include:

Content-Type: application/json

Request bodies should be valid JSON.

Response Format

All responses are returned as JSON:

{
  "success": true,
  "data": {
    // Response data
  }
}

Error responses include:

{
  "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:

GET /api/notifications?page=1&limit=20

Paginated responses include:

{
  "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

Notifications

Create and manage notification tasks

Actions

Configure notification actions

Execute

Manually trigger task execution

Schedule

Manage task schedules

​Base URL

​Authentication

​Getting your API Key

​Request Format

​Response Format

​Rate Limiting

​Pagination

​Error Codes

​SDK Libraries

​API Endpoints