> ## Documentation Index > Fetch the complete documentation index at: https://docs.eyesotope.com/llms.txt > Use this file to discover all available pages before exploring further. # API Reference > Overview of the Eyesotope REST API # API Reference Eyesotope provides a RESTful API for programmatic access to your farm data. This section provides an overview of the API structure. Full interactive API documentation with request/response examples is coming soon. This page provides a structural overview. ## Base URL ``` https://api.eyesotope.com/api/v1/ ``` ## Authentication The API uses token-based authentication. Include your token in the `Authorization` header: ```bash theme={null} curl -H "Authorization: Token YOUR_API_TOKEN" \ https://api.eyesotope.com/api/v1/fields/ ``` ## Endpoints Overview All farm-scoped endpoints require the `X-Farm-ID` header with your farm UUID. ### Core Resources | Endpoint | Methods | Description | | ----------------------------- | ---------------- | ------------------- | | `/api/v1/farms/` | GET, POST | List/create farms | | `/api/v1/farms/{id}/` | GET, PUT, DELETE | Farm detail | | `/api/v1/farms/{id}/members/` | GET, POST | Farm members | | `/api/v1/fields/` | GET, POST | List/create fields | | `/api/v1/fields/{id}/` | GET, PUT, DELETE | Field detail | | `/api/v1/seasons/` | GET, POST | List/create seasons | | `/api/v1/inventory/products/` | GET, POST | Inventory products | | `/api/v1/equipment/` | GET, POST | Equipment list | | `/api/v1/operations/` | GET, POST | Operations | | `/api/v1/partners/` | GET, POST | Partners | | `/api/v1/contracts/` | GET, POST | Contracts | | `/api/v1/deliveries/` | GET, POST | Deliveries | | `/api/v1/leases/` | GET, POST | Leases | ### Agriculture & Crop Data | Endpoint | Methods | Description | | ---------------------------------------------------------------- | --------- | ------------------------------------- | | `/api/v1/crop-types/` | GET | Global crop type reference library | | `/api/v1/phenology-stages/` | GET | Growth stage definitions (BBCH scale) | | `/api/v1/farms/{id}/agriculture-years/` | GET, POST | Seasons (agriculture years) | | `/api/v1/farms/{id}/agriculture-years/{yr}/crops/` | GET, POST | Crops within a season | | `/api/v1/farms/{id}/agriculture-years/{yr}/crops/{c}/varieties/` | GET, POST | Crop varieties | ### Satellite & Remote Sensing | Endpoint | Methods | Description | | ------------------------------------------------------------------------ | --------- | --------------------------------------------------- | | `/api/v1/farms/{f}/fields/{fd}/satellite/` | GET, POST | Satellite monitoring data / activate monitoring | | `/api/v1/farms/{f}/fields/{fd}/satellite/images/bulk-toggle-visibility/` | POST | Bulk archive/restore satellite images | | `/api/v1/farms/{f}/fields/{fd}/satellite/images/{img}/proxy/{index}/` | GET | Proxy satellite image (serves PNG for map overlays) | | `/api/v1/farms/{f}/satellite-overlays/` | GET | Satellite imagery overlays for all fields | | `/api/v1/farms/{f}/satellite-overlay-dates/` | GET | Available satellite imagery dates | | `/api/v1/farms/{f}/field-previews/` | GET | Batch field preview images | | `/api/v1/farms/{f}/field-rankings/` | GET | Field rankings by EVI and health scores | | `/api/v1/farms/{f}/rainfall-by-location/` | GET | Rainfall data by location | | `/api/v1/farms/{f}/soil-moisture-by-location/` | GET | Soil moisture data by location | ### Climate Intelligence (NASA POWER) | Endpoint | Methods | Description | | --------------------------------------------------------------- | --------- | -------------------------------------------------- | | `/api/v1/farms/{f}/fields/{fd}/satellite/climate-intelligence/` | GET | 28 NASA POWER channels + derived metrics | | `/api/v1/farms/{f}/fields/{fd}/satellite/climate-history/` | GET | Historical climate metrics | | `/api/v1/farms/{f}/fields/{fd}/satellite/climate-raw/` | GET | Raw NASA POWER data for a field | | `/api/v1/farms/{f}/fields/{fd}/satellite/climate-sync/` | POST | Trigger climate data synchronization | | `/api/v1/farms/{f}/climate-points/` | GET, POST | Climate observation points for farm-level analysis | | `/api/v1/farms/{f}/climate-points/{p}/historical/` | GET | 44-year historical climate data for a point | | `/api/v1/farms/{f}/climate-points/{p}/heatmap/` | GET | Monthly heatmap data (year × month grid) | | `/api/v1/farms/{f}/climate-points/{p}/advanced-stats/` | GET | Growing season shifts, drought probability | | `/api/v1/farms/{f}/climate-points/{p}/crop-suitability/` | GET | Crop suitability scoring (6 crops, 5 factors) | | `/api/v1/farms/{f}/climate-points/{p}/extreme-events/` | GET | Extreme event detection with trend analysis | | `/api/v1/farms/{f}/climate-points/{p}/climate-records/` | GET | All-time climate records | | `/api/v1/farms/{f}/climate-points/{p}/rainfall-analysis/` | GET | SPI drought index and rainfall decomposition | | `/api/v1/farms/{f}/climate-points/compare/` | GET | Multi-point comparison data | ### Crop Intelligence | Endpoint | Methods | Description | | ------------------------------------------------------------------ | ------- | -------------------------------------------- | | `/api/v1/farms/{f}/fields/{fd}/satellite/water-balance/` | GET | FAO Penman-Monteith water balance | | `/api/v1/farms/{f}/fields/{fd}/satellite/yield-potential/` | GET | Yield estimation (3 FAO methods) | | `/api/v1/farms/{f}/fields/{fd}/satellite/yield-estimates/` | GET | Persisted yield estimate records | | `/api/v1/farms/{f}/fields/{fd}/satellite/water-balance-summaries/` | GET | Persisted water balance summaries | | `/api/v1/farms/{f}/yield-estimates/` | GET | All yield estimates for a farm (cross-field) | | `/api/v1/farms/{f}/water-balance-summaries/` | GET | All water balance summaries for a farm | ### AI Assistant | Endpoint | Methods | Description | | -------------------------------------------- | ----------- | --------------------------------------------------------------------------- | | `/api/v1/farms/{f}/ai/chat/` | POST | Send a message, receive an AI response | | `/api/v1/farms/{f}/ai/chat/stream/` | POST | **SSE streaming chat** — real-time token-by-token response with tool events | | `/api/v1/farms/{f}/ai/upload/` | POST | Upload a file (image/PDF/text/CSV) for AI chat analysis | | `/api/v1/farms/{f}/ai/conversations/` | GET | List user's conversations for this farm | | `/api/v1/farms/{f}/ai/conversations/{id}/` | GET, DELETE | Conversation detail with messages / soft-delete | | `/api/v1/farms/{f}/ai/tasks/` | GET | List AI agent tasks (last 100) | | `/api/v1/farms/{f}/ai/tasks/{id}/` | GET | Task detail (status, tokens, cost, tools used) | | `/api/v1/farms/{f}/ai/credits/` | GET | Credit wallet balance | | `/api/v1/farms/{f}/ai/credits/transactions/` | GET | Credit usage ledger | | `/api/v1/ai/agents/` | GET | List all active agent types | | `/api/v1/ai/pricing/` | GET | Active credit pricing tiers | #### Streaming Chat (SSE) The streaming endpoint (`/ai/chat/stream/`) returns a `text/event-stream` response with the following event types: | Event | Description | | ----------------- | ------------------------------------------------------------------------------- | | `start` | Stream started — includes `conversation_id` | | `token` | A text token to append to the response | | `tool_start` | An AI tool began executing (includes tool name) | | `tool_end` | A tool finished (includes latency and success status) | | `warning` | Non-fatal warning (e.g., provider fallback) | | `reasoning_start` | Deep reasoning stage began (includes model name) | | `reasoning_delta` | Reasoning content signal (`clear: true` means replace Stage 1 output) | | `reasoning_end` | Deep reasoning completed | | `done` | Stream complete — includes full metadata (model, tokens, cost, tools, duration) | | `error` | An error occurred | #### Chat Request Fields | Field | Type | Required | Description | | ----------------- | ------- | -------- | ------------------------------------------ | | `message` | string | Yes | The user's message | | `conversation_id` | UUID | No | Continue an existing conversation | | `agent_type` | string | No | Agent type slug (e.g., `chat-assistant`) | | `context` | array | No | @mention references: `[{type, id, label}]` | | `web_research` | boolean | No | Enable web search for additional context | | `reasoning` | boolean | No | Enable two-stage deep reasoning pipeline | | `attachments` | array | No | List of upload UUIDs from `/ai/upload/` | #### File Upload The upload endpoint (`/ai/upload/`) accepts multipart file uploads with the following constraints: * **Supported formats** — JPEG, PNG, WebP, GIF, PDF, TXT, CSV * **Max file size** — 10 MB * **Rate limit** — 10 uploads per minute * **Security** — MIME type validated via magic bytes, filenames sanitized, image decompression bomb protection, PDF page limit (200 pages) ### Billing & Subscriptions | Endpoint | Methods | Description | | --------------------------------------------- | ------- | ---------------------------------- | | `/api/v1/billing/plans/` | GET | Available subscription plans | | `/api/v1/billing/packages/credits/` | GET | Available credit packages | | `/api/v1/billing/packages/seats/` | GET | Available seat packages | | `/api/v1/farms/{f}/billing/subscription/` | GET | Current subscription details | | `/api/v1/farms/{f}/billing/wallet/` | GET | AI credit wallet balance | | `/api/v1/farms/{f}/billing/wallet/ledger/` | GET | Credit usage history | | `/api/v1/farms/{f}/billing/seats/ledger/` | GET | Seat changes history | | `/api/v1/farms/{f}/billing/usage/` | GET | Resource usage vs. plan limits | | `/api/v1/farms/{f}/billing/checkout/plan/` | POST | Create Stripe Checkout for plan | | `/api/v1/farms/{f}/billing/checkout/credits/` | POST | Create Stripe Checkout for credits | | `/api/v1/farms/{f}/billing/checkout/seats/` | POST | Create Stripe Checkout for seats | | `/api/v1/farms/{f}/billing/change-plan/` | POST | Instant plan change (proration) | | `/api/v1/farms/{f}/billing/cancel/` | POST | Cancel subscription | | `/api/v1/farms/{f}/billing/resume/` | POST | Resume cancelled subscription | | `/api/v1/farms/{f}/billing/portal/` | POST | Get Stripe Customer Portal URL | | `/api/v1/farms/{f}/billing/invoices/` | GET | Invoice history | ### Role-Based Access API endpoints enforce the same role-based permissions as the web interface: * **GET** requests — Available to all authenticated members * **POST, PUT, PATCH** — Requires Operator role or above * **DELETE** — Requires Manager role or above * **Viewers** receive a `403 Forbidden` response for write operations ### Authentication & Account | Endpoint | Methods | Description | | ---------------------------------- | ------- | ------------------------------------------------------- | | `/auth/login/` | POST | Login with email/password (supports `remember_me` flag) | | `/auth/registration/` | POST | Register a new account | | `/auth/google/` | POST | Google OAuth login/registration | | `/auth/password/reset/` | POST | Request a password reset email | | `/auth/password/reset/confirm/` | POST | Set a new password with UID/token | | `/auth/registration/verify-email/` | POST | Verify email with confirmation key | | `/auth/token/verify/` | POST | Verify if a token is still valid | | `/auth/token/refresh/` | POST | Refresh an authentication token | | `/auth/logout/` | POST | Logout (blacklists the current token) | | `/auth/totp/create/` | POST | Generate TOTP QR code and secret | | `/auth/totp/login/` | POST | Verify TOTP code during login | | `/auth/totp/` | GET | Check TOTP 2FA status | ### Notifications | Endpoint | Methods | Description | | -------------------------------------- | --------- | ---------------------------------- | | `/api/v1/notifications/` | GET | List notifications (paginated) | | `/api/v1/notifications/unread-count/` | GET | Get count of unread notifications | | `/api/v1/notifications/{id}/read/` | POST | Mark a single notification as read | | `/api/v1/notifications/mark-all-read/` | POST | Mark all notifications as read | | `wss://*/ws/notifications/` | WebSocket | Real-time notification stream | ### Archive | Endpoint | Methods | Description | | ------------------------------ | ------- | ---------------------------------------- | | `/api/v1/farms/{f}/archive/` | GET | List all archived items across all types | | `/api/v1/farms/{f}/archive/` | POST | Archive an item (type + ID) | | `/api/v1/farms/{f}/unarchive/` | POST | Restore an archived item | ### Activity Log | Endpoint | Methods | Description | | ----------------------------- | ------- | ------------------------------------ | | `/api/v1/farms/{f}/activity/` | GET | Full audit trail of all farm actions | ## Response Format All responses are in JSON format. List endpoints support pagination: ```json theme={null} { "count": 42, "next": "https://api.eyesotope.com/api/v1/fields/?page=2", "previous": null, "results": [...] } ``` ## Error Responses | Status Code | Meaning | | ----------- | ----------------------------------------------------- | | 400 | Bad Request — Invalid input data | | 401 | Unauthorized — Missing or invalid token | | 403 | Forbidden — Insufficient permissions (role or module) | | 404 | Not Found — Resource doesn't exist | | 429 | Too Many Requests — Rate limit exceeded | | 500 | Server Error — Contact support | ## Rate Limiting The API enforces rate limiting to ensure fair usage: * **Authenticated requests** — Throttled per user * **Anonymous requests** — Throttled per IP address * Rate limit headers are included in responses: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` When rate limited, the API returns a `429 Too Many Requests` response with a `Retry-After` header.