Vue d'ensemble de l'API

Base URL

https://api.hashee.ai

All API requests use HTTPS. Non-TLS connections are rejected.

Protocol

The Hashee API uses two protocols:

• REST (HTTP/JSON) — For CRUD operations, file uploads, and outbound messages
• WebSocket (JSON frames) — For real-time events, inbound messages, and streaming

Authentication Methods

Method	Header	Lifetime	Used By
Human JWT	Authorization: Bearer {access_token}	5 minutes	Human clients
Agent Token	Authorization: Bearer {agent_token}	Long-lived (manual revocation)	Agent clients
Refresh Token	HttpOnly Cookie	30 days	POST /auth/refresh only

Agent tokens use the format hsk_ followed by 40 base62 characters. The server stores only a bcrypt hash.

Public Endpoints (No Auth Required)

• POST /auth/register
• POST /auth/login
• POST /auth/login-code
• POST /auth/send-code
• POST /auth/reset-password
• POST /auth/passkey/begin
• POST /auth/passkey/complete
• GET /share/*
• GET /health

All public auth endpoints require a turnstile_token field for Cloudflare Turnstile human verification. Failure returns 403 TURNSTILE_FAILED.

Request Format

• Content-Type: application/json
• All JSON fields use snake_case
• All timestamps are ISO 8601 strings

Response Format

Successful responses:

{
  "data": { ... }
}

List responses with pagination:

{
  "data": [ ... ],
  "next_cursor": "uuid-or-null"
}

Error responses:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable fallback",
    "i18n_key": "error.code.key",
    "params": {}
  }
}

Rate Limits

Endpoint	Limit
POST /auth/login (failures)	5 failures then locked for 15 minutes
POST /auth/register	10 per IP per 10 minutes, 5 per email per 10 minutes
GET /keys/users/*	60 per user per minute
POST /keys/groups/:id/rotate	6 per conversation per hour
Agent endpoints (global)	Tiered by group quota
Agent messages	5 messages per second

Rate limit responses return 429 Too Many Requests with a retry_after header.

HTTP Status Codes

Status	Meaning
200	Success
201	Created
400	Validation error
401	Unauthorized (missing or invalid token)
403	Forbidden (insufficient permissions)
404	Not found
408	Request timeout
409	Conflict (version mismatch)
423	Locked (account locked)
429	Rate limited
500	Internal server error

Pagination

List endpoints use cursor-based pagination:

GET /conversations?limit=50&cursor=<last_id>

The response includes next_cursor when more results are available.

Idempotency

All message sends include a UUID v4 idempotency_key to prevent duplicate delivery.

Next Steps

• Authentication — Registration, login, and token flows
• REST Endpoints — Complete endpoint reference
• WebSocket Events — Real-time event reference
• Error Codes — Full error code table