Skip to main content
The profClaw API is a JSON REST API built with Hono. All endpoints are served on the same port as the UI (default 3000).

​
Base URL

http://localhost:3000/api
For production deployments, replace localhost:3000 with your server’s hostname. All routes are prefixed with /api.

​
Authentication

profClaw supports three authentication modes configured via system.authMode in settings:

​
Rate Limits

EndpointLimit
POST /api/auth/login10 requests / 60 seconds
POST /api/auth/signup5 requests / 60 seconds
POST /api/auth/verify-access-key10 requests / 60 seconds
All other endpointsNo hard limit (configurable)
Rate limit responses return HTTP 429 with: 
{ "error": "Too many login attempts. Try again in a minute." }

​
Error Format

All errors follow a consistent shape: 
{
  "error": "Human-readable error message",
  "details": { }  // optional, present for validation errors
}
Common HTTP status codes:
CodeMeaning
400Validation failed or bad request body
401Not authenticated or invalid session
403Authenticated but insufficient permissions
404Resource not found
429Rate limit exceeded
500Internal server error
501Feature not available in current mode/storage
503Service unavailable (queue or adapter down)

​
Pagination

List endpoints support both offset-based and cursor-based pagination: 
# Offset-based (simple)
GET /api/tasks?limit=50&offset=100

# Cursor-based (efficient for large datasets)
GET /api/tasks?limit=50&cursor=<base64url-cursor>
Responses include nextCursor when more results are available. Cursor values are opaque base64url-encoded strings encoding { createdAt, id }.

​
Content Types

All request and response bodies use application/json. Streaming endpoints use text/event-stream (SSE).

​
Versioning

The API is currently unversioned. Breaking changes will be announced in the changelog and migration guides provided.