Skip to main content
The Poultry Farm Analytics API is a REST API for managing poultry farm inventory, flocks, cycles, analytics, anomalies, IoT devices, and operational workflows.
  • Base URL (local dev): http://localhost:3000
  • Version: 2.0.0
  • Content type: application/json

​
Authentication

Most endpoints require a JSON Web Token (JWT). Obtain one by calling POST /api/v1/auth/login and then send it on every subsequent request:
A small number of endpoints are public — GET /, GET /health, POST /api/v1/auth/signup, and POST /api/v1/auth/login. Example login flow:
Many endpoints additionally require specific capabilities (for example view_analytics, manage_flocks, create_movement). Capabilities are assigned per user by an admin; if your token does not carry the required capability the server responds with 403 Forbidden.

​
Standard responses

  • 200 OK — successful read/update.
  • 201 Created — successful create.
  • 204 No Content — successful delete.
  • 400 Bad Request — validation error. Body: { error, details }.
  • 401 Unauthorized — missing or invalid token.
  • 403 Forbidden — missing capability, locked account, or unverified account.
  • 404 Not Found — resource does not exist.
  • 429 Too Many Requests — rate limit hit.
  • 500 Internal Server Error — body: { error }.
Successful responses are JSON, typically shaped as { message, data } or a list of resources.

​
Rate limits

​
Endpoint groups

Endpoints are organised by tag in the sidebar. Each endpoint page is auto-generated from the OpenAPI specification and includes an interactive Try it playground.

​
Health & welcome

​
GET /

Welcome endpoint. Returns API metadata, version, and a map of endpoint base paths.

​
GET /health

Liveness probe. Returns { status, timestamp, uptime, environment }. Not rate limited.