API Reference

This page lists all API endpoints across the Hokusai platform. For detailed request/response schemas and code examples, follow the links to the dedicated documentation pages.

Authentication Service

Base URL: https://auth.hokus.ai

The authentication service manages registration, authentication, API keys, organizations, and usage tracking for the entire Hokusai platform.

Registration

Method	Endpoint	Auth Required	Description	Docs
GET	/register	No	Registration web form	Registration
POST	/register	No	Submit a registration request	Registration
POST	/registration/status	No	Check registration status by email	Registration
GET	/register/rate-limit-status	No	Check rate limit before submitting	Registration

Sign-In with Ethereum (SIWE)

Method	Endpoint	Auth Required	Description	Docs
POST	/auth/siwe/challenge	No	Generate a wallet authentication challenge	SIWE
POST	/auth/siwe/verify	No	Verify a signed message and get JWT	SIWE

Key Management

All key management endpoints require admin authentication via Authorization: Bearer {ADMIN_TOKEN}.

Method	Endpoint	Description	Docs
POST	/api/v1/keys	Create a new API key	API Keys
GET	/api/v1/keys	List all API keys	API Keys
GET	/api/v1/keys/{key_id}	Get details for a specific key	API Keys
POST	/api/v1/keys/{key_id}/rotate	Rotate a key (revoke old, create new)	API Keys
DELETE	/api/v1/keys/{key_id}	Revoke an API key	API Keys

Validation

Method	Endpoint	Auth Required	Description	Docs
POST	/api/v1/keys/validate	No (public)	Validate an API key	Validation
POST	/api/v1/tokens/validate	No (public)	Validate a JWT token	Validation

Organizations

Organization endpoints require JWT authentication. Required roles are noted per endpoint.

Method	Endpoint	Min Role	Description	Docs
POST	/api/v1/organizations	Authenticated	Create an organization	API Keys
GET	/api/v1/organizations/{org_id}	Viewer	Get organization details	—
PATCH	/api/v1/organizations/{org_id}	Admin	Update organization	—
DELETE	/api/v1/organizations/{org_id}	Owner	Delete organization	—
GET	/api/v1/organizations/{org_id}/members	Viewer	List members	—
PATCH	/api/v1/organizations/{org_id}/members/{user_id}	Admin	Update member role	—
DELETE	/api/v1/organizations/{org_id}/members/{user_id}	Admin	Remove member	—
POST	/api/v1/organizations/{org_id}/invitations	Admin	Send invitation	—
GET	/api/v1/organizations/{org_id}/invitations	Admin	List pending invitations	—
DELETE	/api/v1/organizations/{org_id}/invitations/{id}	Admin	Revoke invitation	—
POST	/api/v1/invitations/accept	Authenticated	Accept an invitation	—
POST	/api/v1/organizations/{org_id}/api-keys	Developer	Create org API key	API Keys
GET	/api/v1/organizations/{org_id}/api-keys	Viewer	List org API keys	API Keys
DELETE	/api/v1/organizations/{org_id}/api-keys/{key_id}	Developer	Revoke org API key	API Keys
GET	/api/v1/organizations/{org_id}/audit-logs	Admin	List audit logs	—

Usage & Billing

Method	Endpoint	Auth Required	Description	Docs
POST	/api/v1/usage/{key_id}	No (internal)	Record API usage	Usage & Billing
GET	/api/v1/usage/{key_id}/stats	Admin	Get usage statistics	Usage & Billing
GET	/api/v1/usage/{key_id}/billing	Admin	Get billing information	Usage & Billing
GET	/api/v1/usage/aggregate	Admin	Aggregate usage across all keys	Usage & Billing

Admin — Registration Management

Method	Endpoint	Auth Required	Description
GET	/api/v1/admin/registrations	Admin	List registration requests (paginated, filterable)
GET	/api/v1/admin/registrations/{id}	Admin	Get registration details
PATCH	/api/v1/admin/registrations/{id}	Admin	Approve or reject a registration
GET	/api/v1/admin/registration/whitelist	Admin	List rate-limit whitelist entries
POST	/api/v1/admin/registration/whitelist	Admin	Add whitelist entry (IP or domain)
PATCH	/api/v1/admin/registration/whitelist/{id}	Admin	Enable/disable whitelist entry
DELETE	/api/v1/admin/registration/whitelist/{id}	Admin	Delete whitelist entry
GET	/api/v1/admin/registration/bans/{ip}	Admin	Check ban status for an IP
DELETE	/api/v1/admin/registration/bans/{ip}	Admin	Remove temporary IP ban

Health & Monitoring

Method	Endpoint	Auth Required	Description
GET	/health	No	Service health check
GET	/ready	No	Readiness check (database + Redis)
GET	/metrics	No	Service metrics summary

Model API

Base URL: https://api.hokus.ai

The Model API provides access to Hokusai's AI models for predictions and management. All endpoints require a valid API key.

For detailed Model API documentation, see the Model API Guide.

Models

Method	Endpoint	Description
GET	/v1/models	List available models
GET	/v1/models/{model_id}	Get model details

Predictions

Method	Endpoint	Description
POST	/v1/predict	Single prediction
POST	/v1/batch-predict	Batch prediction

License Management

Method	Endpoint	Description
GET	/v1/models/{model_id}/license	Check license status
POST	/v1/models/{model_id}/whitelist	Request whitelist access (Co-Op models)

Common Response Formats

Success Response

{
  "data": { ... },
  "status": "success"
}

Error Response

{
  "detail": "Human-readable error message"
}

Standard HTTP Status Codes

Code	Meaning
200	Request succeeded
400	Invalid request parameters
401	Missing or invalid authentication
403	Valid auth but insufficient permissions
404	Resource not found
429	Rate limit exceeded
500	Internal server error
503	Service unavailable (dependency down)

Authentication

All Hokusai APIs authenticate using API keys. See the Authentication Overview for details on:

• Creating API keys
• Three ways to send keys
• Environment prefixes (hk_live_, hk_test_, hk_dev_)
• Security best practices