Skip to main content
The SemaiSens REST API gives you programmatic access to every feature on the platform. Use it to register and manage field boundaries, retrieve satellite and aerial imagery, calculate vegetation indices like NDVI and NDRE, generate agronomic reports, and receive real-time notifications via webhooks — all from your own applications and workflows.

​
Base URL

All API requests are made to the following base URL. Include /v1/ in every request path.

​
Quick Reference

Authentication

Learn how to generate API keys and authenticate every request with a Bearer token.

Rate Limits

Understand request quotas by plan and how to implement exponential backoff.

Fields

Register field boundaries, set crop metadata, and manage your field portfolio.

Imagery

Browse satellite passes, filter by cloud cover, and upload drone orthomosaics.

Indices

Calculate NDVI, NDRE, NDWI, EVI, and custom band-math indices for your fields.

Reports

Generate scouting summaries, seasonal analyses, and prescription maps.

Webhooks

Subscribe to real-time events for new imagery, triggered alerts, and ready reports.

​
Request Format

Every request to the API must follow these conventions:
  • Content-Type — Include the header Content-Type: application/json on all requests that send a body (POST, PATCH, PUT).
  • Authorization — Include the header Authorization: Bearer YOUR_API_KEY on every request. Requests without a valid key are rejected with 401 Unauthorized.
  • Dates — Express all date values in ISO 8601 format. Use YYYY-MM-DD for date-only fields and YYYY-MM-DDTHH:MM:SSZ for timestamps.

​
Response Format

All responses are returned as JSON. The API uses standard HTTP status codes to indicate the outcome of each request. Successful responses Error responses When a request fails, the API returns an error object with a machine-readable code, a human-readable message, and the HTTP status code.

​
Standard Error Codes

​
Versioning

The current API version is v1. Include /v1/ in every request URL to target this version. When breaking changes are introduced, they are released under a new version (e.g., /v2/). The previous version remains supported for a minimum of 6 months after a new version is announced, giving you time to migrate your integrations.
Non-breaking changes — such as new optional fields, new endpoints, and new event types — may be added to the current version at any time without a version bump.

​
SDKs and Client Libraries

Official Python and JavaScript client libraries are in active development and will be available soon. The libraries will wrap the REST API, handle authentication, and provide typed models for all resources. Until then, use any standard HTTP client with the examples throughout this reference.
All code examples in this reference use plain curl, requests (Python), and fetch (JavaScript) so you can run them immediately without any additional dependencies.