API Versioning
Hatcher uses URL-based API versioning to ensure stability for integrations.
Current Version
v1 — All programmatic API endpoints are available under /api/v1/.
https://api.hatcher.host/api/v1/agents
https://api.hatcher.host/api/v1/me
https://api.hatcher.host/api/v1/usageVersion Headers
Every response from /api/v1/* includes these headers:
| Header | Value | Description |
|---|---|---|
API-Version | v1 | Current API version |
X-API-Version | 1 | Numeric version for programmatic checks |
X-RateLimit-Limit | number | Daily request limit |
X-RateLimit-Remaining | number | Requests remaining today |
X-RateLimit-Reset | timestamp | Unix timestamp when limit resets |
Future Deprecation Headers
When a new version launches, deprecated versions will include:
| Header | Example | Description |
|---|---|---|
Deprecation | true | Indicates this version is deprecated |
Sunset | 2027-01-01T00:00:00Z | Date when this version will be removed |
Authentication
All /api/v1 endpoints require authentication via:
- JWT Token —
Authorization: Bearer <jwt>(from/auth/login) - API Key —
Authorization: Bearer hk_<key>(from Dashboard Settings)
Available Endpoints
| Method | Path | Description | Rate Limit |
|---|---|---|---|
GET | /api/v1/me | Current user info | 30/min |
GET | /api/v1/usage | API usage stats | 30/min |
GET | /api/v1/agents | List your agents | 30/min |
GET | /api/v1/agents/:id | Agent details | 30/min |
GET | /api/v1/agents/:id/status | Agent status | 60/min |
POST | /api/v1/agents/:id/chat | Send message | 10/min |
POST | /api/v1/agents/:id/start | Start agent | 5/min |
POST | /api/v1/agents/:id/stop | Stop agent | 5/min |
POST | /api/v1/agents/:id/restart | Restart agent | 5/min |
Internal Endpoints
Internal endpoints (/internal/*, /health, /healthz) are not versioned and will never be prefixed. These are for platform infrastructure only.
Versioning Policy
- No breaking changes within a version — fields may be added but never removed
- 6-month deprecation window — deprecated versions include
DeprecationandSunsetheaders - Migration guides — published with each new version
- Semantic versioning — major version bumps for breaking changes only