Skip to main content

​
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

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

CodeDescription
UNAUTHORIZEDInvalid or missing API key
FORBIDDENInsufficient permissions
NOT_FOUNDResource not found
VALIDATION_ERRORInvalid request data
RATE_LIMITEDToo many requests
SERVER_ERRORInternal 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