API Reference

Integrate your Hatcher agents into any application. Manage agents, send messages, and monitor status programmatically.

Authentication

All API requests require authentication using your platform API key. Include it in the Authorization header as a Bearer token.

Authorization: Bearer hk_your_api_key

You can find and regenerate your API key on the Settings page. Keys are prefixed with hk_ for easy identification.

curl -H "Authorization: Bearer hk_your_api_key" \
  https://api.hatcher.host/api/v1/agents

Never expose your API key in client-side code or public repositories. Use environment variables and server-side requests to keep your key safe.

API usage is rate-limited per day based on your plan. Rate limit information is included in every response header.

Check the following response headers to monitor your usage:

X-RateLimit-LimitYour daily request limit

X-RateLimit-RemainingRequests remaining today

X-RateLimit-ResetUTC timestamp when the limit resets

All API responses follow a consistent JSON structure. Successful responses include a data field. Error responses include error and code fields.

Success

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

Error

{
  "success": false,
  "error": "Not found",
  "code": "NOT_FOUND"
}

Code	HTTP	Description
AUTH_REQUIRED	401	Missing or invalid API key
FORBIDDEN	403	Not authorized for this resource
NOT_FOUND	404	Agent or resource not found
RATE_LIMIT_EXCEEDED	429	Daily API limit reached
VALIDATION_ERROR	400	Invalid request body or parameters
AGENT_NOT_RUNNING	409	Agent must be running for this action
SERVER_ERROR	500	Internal server error

Need help integrating? Check out the platform-specific guides.