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:

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

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:

{
  "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.

API Reference

​API Reference

​Base URL

​Authentication

​Endpoints Overview

​Core Resources

​Agriculture & Crop Data

​Satellite & Remote Sensing

​Climate Intelligence (NASA POWER)

​Crop Intelligence

​AI Assistant

​Streaming Chat (SSE)

​Chat Request Fields

​File Upload

​Billing & Subscriptions

​Role-Based Access

​Authentication & Account

​Notifications

​Archive

​Activity Log

​Response Format

​Error Responses

​Rate Limiting

API Reference

Base URL

Authentication

Endpoints Overview

Core Resources

Agriculture & Crop Data

Satellite & Remote Sensing

Climate Intelligence (NASA POWER)

Crop Intelligence

AI Assistant

Streaming Chat (SSE)

Chat Request Fields

File Upload

Billing & Subscriptions

Role-Based Access

Authentication & Account

Notifications

Archive

Activity Log

Response Format

Error Responses

Rate Limiting