How do I authenticate with the Hercox AI API?

Hercox AI uses session-based authentication with CSRF tokens. Login via /api/auth/login to start a session.

What is the base URL for the API?

The base URL is https://your-domain.com/api/

Hercox AI API Reference — Complete REST API Documentation

Overview

REST API for Hercox AI

The Hercox AI API provides programmatic access to all system features:

Authentication: Session-based with CSRF protection
Users: Registration, profiles, status
Memory: Short-term and long-term storage
Reasoning: Decision support and pattern recognition
Automation: Workflows, tasks, triggers
Subscriptions: Plans and payments
Business: API keys, training, widgets
Security: Logs, events, monitoring

GET /api/status

Health Check — Verify the API is operational.

Response:

                                {
                                    "status": "online",
                                    "version": "1.0.0",
                                    "timestamp": "2026-09-24 01:29:55"
                                }
                            

Authentication

Session-based authentication with CSRF protection

Hercox AI uses session-based authentication with:

HttpOnly cookies for security
CSRF tokens for state-changing requests
Session timeout (configurable)
Login attempt rate limiting

POST /api/auth/login

Login — Authenticate a user session.

Parameters:
username (string) — User's username
password (string) — User's password

                            // Request
                            POST /api/auth/login
                            {
                                "username": "operator",
                                "password": "secure_password"
                            }

                            // Response (success)
                            {
                                "success": true,
                                "message": "Login successful",
                                "user": {
                                    "id": 1,
                                    "username": "operator",
                                    "email": "operator@hercoxai.com",
                                    "plan": "pro"
                                }
                            }

                            // Response (failure)
                            {
                                "success": false,
                                "message": "Invalid credentials"
                            }
                        

POST /api/auth/logout

Logout — Destroy the current session.

Headers: X-CSRF-Token (required)

                            // Request
                            POST /api/auth/logout
                            Headers: { "X-CSRF-Token": "token_value" }

                            // Response
                            {
                                "success": true,
                                "message": "Logged out successfully"
                            }
                        

GET /api/auth/status

Check Status — Verify if user is authenticated.

                            // Request
                            GET /api/auth/status

                            // Response (authenticated)
                            {
                                "authenticated": true,
                                "user": {
                                    "id": 1,
                                    "username": "operator"
                                }
                            }

                            // Response (unauthenticated)
                            {
                                "authenticated": false
                            }
                        

Users

User management endpoints

POST /api/users/register

Register — Create a new user account.

Parameters:
username (string) — Unique username (3-50 chars)
email (string) — Valid email address
password (string) — Min 8 characters

                            // Request
                            POST /api/users/register
                            {
                                "username": "new_user",
                                "email": "user@hercoxai.com",
                                "password": "secure_password"
                            }

                            // Response
                            {
                                "success": true,
                                "user_id": 123,
                                "message": "Registration successful",
                                "recovery_phrase": "abandon ability able ..."
                            }
                        

GET /api/users/profile

Get Profile — Get current user's profile.

Headers: X-CSRF-Token (required)

                            // Request
                            GET /api/users/profile
                            Headers: { "X-CSRF-Token": "token_value" }

                            // Response
                            {
                                "success": true,
                                "user": {
                                    "id": 1,
                                    "username": "operator",
                                    "email": "operator@hercoxai.com",
                                    "plan": "pro",
                                    "status": "active",
                                    "created_at": "2024-01-01 00:00:00"
                                }
                            }
                        

PUT /api/users/profile

Update Profile — Update user profile information.

Headers: X-CSRF-Token (required)
Parameters:
username (string, optional) — New username
email (string, optional) — New email
profile_picture (string, optional) — URL to profile image

                            // Request
                            PUT /api/users/profile
                            Headers: { "X-CSRF-Token": "token_value" }
                            {
                                "username": "new_username",
                                "email": "new_email@hercoxai.com"
                            }

                            // Response
                            {
                                "success": true,
                                "message": "Profile updated successfully"
                            }
                        

Memory

Short-term and long-term memory operations

POST /api/memory/store

Store Memory — Save a memory to long-term storage.

Headers: X-CSRF-Token (required)
Parameters:
key (string) — Memory key (unique)
value (string) — Memory content
type (string) — personal, preference, habit, relationship, goal, appointment, knowledge, business

                            // Request
                            POST /api/memory/store
                            Headers: { "X-CSRF-Token": "token_value" }
                            {
                                "key": "user_preference",
                                "value": "Prefers dark mode interface",
                                "type": "preference"
                            }

                            // Response
                            {
                                "success": true,
                                "message": "Memory stored",
                                "memory_id": 456
                            }
                        

GET /api/memory/recall

Recall Memory — Retrieve a memory by key.

Headers: X-CSRF-Token (required)
Parameters: key (string) — Memory key

                            // Request
                            GET /api/memory/recall?key=user_preference
                            Headers: { "X-CSRF-Token": "token_value" }

                            // Response
                            {
                                "success": true,
                                "memory": {
                                    "id": 456,
                                    "key": "user_preference",
                                    "value": "Prefers dark mode interface",
                                    "type": "preference",
                                    "created_at": "2024-01-01 00:00:00"
                                }
                            }
                        

GET /api/memory/search

Search Memory — Search memories by keyword.

Headers: X-CSRF-Token (required)
Parameters:
q (string) — Search query
limit (int, optional) — Max results (default: 10)

                            // Request
                            GET /api/memory/search?q=dark+mode&limit=5
                            Headers: { "X-CSRF-Token": "token_value" }

                            // Response
                            {
                                "success": true,
                                "results": [
                                    {
                                        "id": 456,
                                        "key": "user_preference",
                                        "value": "Prefers dark mode interface",
                                        "confidence": 85.00
                                    }
                                ],
                                "total": 1
                            }
                        

DELETE /api/memory/delete

Delete Memory — Remove a memory by key.

Headers: X-CSRF-Token (required)
Parameters: key (string) — Memory key to delete

                            // Request
                            DELETE /api/memory/delete?key=user_preference
                            Headers: { "X-CSRF-Token": "token_value" }

                            // Response
                            {
                                "success": true,
                                "message": "Memory deleted successfully"
                            }
                        

Reasoning

Decision support and pattern recognition

POST /api/reasoning/analyze

Analyze — Get reasoning steps and conclusion.

Headers: X-CSRF-Token (required)
Parameters: query (string) — Question or problem to analyze

                            // Request
                            POST /api/reasoning/analyze
                            Headers: { "X-CSRF-Token": "token_value" }
                            {
                                "query": "Should I upgrade to the Pro plan?"
                            }

                            // Response
                            {
                                "success": true,
                                "reasoning_steps": [
                                    "Current plan: Trial (50 messages/month)",
                                    "Pro plan offers: 500 messages/month",
                                    "Advanced AI chat and enhanced memory",
                                    "Cost: $10 USDT/month"
                                ],
                                "conclusion": "Upgrade recommended for power users",
                                "confidence_score": 85.50
                            }
                        

POST /api/reasoning/decide

Decide — Get decision support with options.

Headers: X-CSRF-Token (required)
Parameters:
decision_type (string) — Type of decision
options (array) — Available options

                            // Request
                            POST /api/reasoning/decide
                            Headers: { "X-CSRF-Token": "token_value" }
                            {
                                "decision_type": "subscription_plan",
                                "options": ["Trial", "Pro", "Business", "Enterprise"]
                            }

                            // Response
                            {
                                "success": true,
                                "recommendation": "Pro",
                                "reasons": [
                                    "Best value for features offered",
                                    "Most common choice for individuals"
                                ]
                            }
                        

Automation

Workflows, tasks, and event triggers

POST /api/workflows/create

Create Workflow — Create a new automation workflow.

Headers: X-CSRF-Token (required)
Parameters:
name (string) — Workflow name
steps (array) — Array of workflow steps
trigger_type (string) — manual, scheduled, event, command
schedule_config (object, optional) — Cron schedule

                            // Request
                            POST /api/workflows/create
                            Headers: { "X-CSRF-Token": "token_value" }
                            {
                                "name": "Daily Email Backup",
                                "steps": [
                                    "fetch_emails",
                                    "compress_files",
                                    "store_backup"
                                ],
                                "trigger_type": "scheduled",
                                "schedule_config": {
                                    "cron": "0 0 * * *"
                                }
                            }

                            // Response
                            {
                                "success": true,
                                "workflow_id": 789,
                                "message": "Workflow created successfully"
                            }
                        

POST /api/workflows/execute

Execute Workflow — Run a workflow manually.

Headers: X-CSRF-Token (required)
Parameters: workflow_id (int) — ID of workflow to execute

                            // Request
                            POST /api/workflows/execute
                            Headers: { "X-CSRF-Token": "token_value" }
                            {
                                "workflow_id": 789
                            }

                            // Response
                            {
                                "success": true,
                                "execution_id": 101,
                                "status": "running",
                                "message": "Workflow execution started"
                            }
                        

GET /api/workflows/list

List Workflows — Get all user workflows.

Headers: X-CSRF-Token (required)

                            // Request
                            GET /api/workflows/list
                            Headers: { "X-CSRF-Token": "token_value" }

                            // Response
                            {
                                "success": true,
                                "workflows": [
                                    {
                                        "id": 789,
                                        "name": "Daily Email Backup",
                                        "trigger_type": "scheduled",
                                        "is_active": true,
                                        "last_run": "2024-01-01 00:00:00"
                                    }
                                ],
                                "total": 1
                            }
                        

Subscriptions

Plan management and payments

GET /api/subscriptions/current

Get Current Subscription — Get user's active subscription.

Headers: X-CSRF-Token (required)

                            // Request
                            GET /api/subscriptions/current
                            Headers: { "X-CSRF-Token": "token_value" }

                            // Response
                            {
                                "success": true,
                                "subscription": {
                                    "id": 1,
                                    "plan": "pro",
                                    "price_usdt": "10.00",
                                    "start_date": "2024-01-01",
                                    "expiry_date": "2024-02-01",
                                    "is_active": true,
                                    "days_left": 30
                                }
                            }
                        

POST /api/subscriptions/create

Create Subscription — Activate a new subscription.

Headers: X-CSRF-Token (required)
Parameters:
plan (string) — pro, business, enterprise
transaction_hash (string) — Blockchain transaction hash

                            // Request
                            POST /api/subscriptions/create
                            Headers: { "X-CSRF-Token": "token_value" }
                            {
                                "plan": "pro",
                                "transaction_hash": "0x742d35Cc6634C0532925a3b844Bc9e75993b9e6d"
                            }

                            // Response
                            {
                                "success": true,
                                "subscription_id": 1,
                                "message": "Subscription activated successfully"
                            }
                        

POST /api/subscriptions/cancel

Cancel Subscription — Cancel current subscription.

Headers: X-CSRF-Token (required)
Parameters: subscription_id (int) — ID of subscription to cancel

                            // Request
                            POST /api/subscriptions/cancel
                            Headers: { "X-CSRF-Token": "token_value" }
                            {
                                "subscription_id": 1
                            }

                            // Response
                            {
                                "success": true,
                                "message": "Subscription cancelled successfully"
                            }
                        

Business Tools

API keys, training, and widgets

POST /api/business/api-key

Generate API Key — Create a new API key for integration.

Headers: X-CSRF-Token (required)
Parameters: name (string) — Name for the API key

                            // Request
                            POST /api/business/api-key
                            Headers: { "X-CSRF-Token": "token_value" }
                            {
                                "name": "My App Integration"
                            }

                            // Response
                            {
                                "success": true,
                                "api_key": "hj8d9f7g6h5j4k3l2m1n",
                                "message": "API key generated successfully"
                            }
                        

POST /api/business/training

Add Training Data — Train the AI with custom Q&A.

Headers: X-CSRF-Token (required)
Parameters:
question (string) — User question
answer (string) — AI response
category (string, optional) — Category for organization

                            // Request
                            POST /api/business/training
                            Headers: { "X-CSRF-Token": "token_value" }
                            {
                                "question": "What services do you offer?",
                                "answer": "We offer AI memory, reasoning, automation, and business tools.",
                                "category": "general"
                            }

                            // Response
                            {
                                "success": true,
                                "training_id": 234,
                                "message": "Training data added"
                            }
                        

Security

Security logs and monitoring

GET /api/security/logs

Get Security Logs — Retrieve security event logs.

Headers: X-CSRF-Token (required)
Parameters:
limit (int, optional) — Max results (default: 20)
severity (string, optional) — low, medium, high, critical

                            // Request
                            GET /api/security/logs?limit=5&severity=high
                            Headers: { "X-CSRF-Token": "token_value" }

                            // Response
                            {
                                "success": true,
                                "logs": [
                                    {
                                        "id": 1,
                                        "event_type": "fraud_attempt",
                                        "ip_address": "192.168.1.1",
                                        "severity": "high",
                                        "created_at": "2024-01-01 00:00:00"
                                    }
                                ],
                                "total": 1
                            }
                        

GET /api/security/status

Security Status — Get current security status.

Headers: X-CSRF-Token (required)

                            // Request
                            GET /api/security/status
                            Headers: { "X-CSRF-Token": "token_value" }

                            // Response
                            {
                                "success": true,
                                "status": {
                                    "threats": 0,
                                    "last_attack": null,
                                    "failed_logins_today": 2,
                                    "is_secure": true
                                }
                            }
                        

Response Codes

Standard HTTP status codes used by the API

Code	Description	When Used
200	Success	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid parameters or missing fields
401	Unauthorized	Authentication required or session expired
403	Forbidden	Insufficient permissions
404	Not Found	Resource does not exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error, check logs

Error Handling

Error response format and common errors

Error Response Format — All errors follow this structure:

                            {
                                "success": false,
                                "message": "Human-readable error message",
                                "code": "ERROR_CODE",
                                "details": {
                                    "field": "Additional error context"
                                }
                            }
                        

Common Errors

Code	Description	Solution
AUTH_001	Invalid credentials	Check username and password
AUTH_002	Session expired	Re-authenticate
VAL_001	Invalid parameter	Check parameter format
VAL_002	Missing required field	Include all required fields
DB_001	Database error	Contact support
RATE_001	Rate limit exceeded	Wait and try again