API, webhooks and MCP: connect your ERP to the notebook
If you run the farm with an ERP, a cost spreadsheet or your advisory firm's software, there is no point typing every task twice. This is the documentation for pulling the notebook, the costs and the compliance status out from outside, and for pushing tasks in from the system you already use.
The base URL is https://agrogps-api.fly.dev/api/v1. It has been in production since 17 September 2026. It always answers in JSON, errors included.
Two ways to authenticate
| Who is calling | Header | What it can do |
|---|---|---|
| The app or the web | Authorization: Bearer <sesión> | Everything, including creating and revoking keys |
| An external system | X-API-Key: agk_… | Read, or read and write, depending on the key's scope |
A key is created once from your session and shown only once: after that we only keep its hash. If you lose it, revoke it and create another. A read-only key that tries to write gets 403 AUT_004. Keys cannot create or delete other keys or webhooks: that always takes a person's session.
curl -X POST https://agrogps-api.fly.dev/api/v1/api-keys \
-H "Authorization: Bearer $SESION" \
-H "Content-Type: application/json" \
-d '{"name":"ERP Sage","scope":"read"}'What you can read
| Endpoint | Returns |
|---|---|
GET /farms | The key owner's farms, with their role |
GET /sync/entries?farm_id=…&since=0 | Every task with the full Annex II fields, paginated with next |
GET /groups/:id/overview | Group dashboard: tasks, cost, income, margin, treated hectares and crop per farm |
GET /advisor/portfolio | The advisor's portfolio: which farms are up to date and which are not |
GET /advisor/farms/:id/pending | The fields still missing, task by task |
GET /notebook/entries/:id/history | Who changed what, and when, in a task |
With a write key you can also record tasks with POST /sync/entries, using the same body the app uses. Sync works with since, so a nightly job only fetches what has changed.
Signed webhooks
Instead of asking every five minutes, we tell you. You register a public https URL and we send a notice when something happens on a farm where you are owner or manager.
| Event | When it fires |
|---|---|
entry.pushed | Tasks are synced and at least one is accepted |
entry.reviewed | An advisor or the owner approves or flags a task |
webhook.test | You press test |
Every delivery carries X-Agro-Event, X-Agro-Timestamp in Unix seconds and X-Agro-Signature with the HMAC-SHA256 of "<timestamp>.<cuerpo>". Check both things: the signature, and that the clock has not drifted more than five minutes.
import hmac, hashlib, time
ts = request.headers["X-Agro-Timestamp"]
assert abs(time.time() - int(ts)) < 300
esperada = "sha256=" + hmac.new(
secreto.encode(), ts.encode() + b"." + cuerpo, hashlib.sha256
).hexdigest()
ok = hmac.compare_digest(esperada, request.headers["X-Agro-Signature"])Delivery rules, stated plainly so there are no surprises: one attempt, a six-second timeout and no retries. We do not follow redirects, and we reject private, link-local and cloud-metadata addresses, both when the URL is registered and when the DNS is resolved for each delivery. If your system needs guarantees, use the webhook as a notice and GET /sync/entries with since as the safety net: the notice is a courtesy, the API is the truth.
MCP for AI assistants
The same API is exposed as an MCP server, the protocol assistants use to connect to tools. You can ask an assistant things like which farms are behind, how much the season has cost or what is still missing before an inspection.
{ "mcpServers": { "agro-gps": {
"command": "npx", "args": ["-y", "agro-gps-mcp"],
"env": { "AGROGPS_API_KEY": "agk_…" } } } }Available tools: list_farms, list_entries, entry_history, list_groups, group_overview, advisor_portfolio, advisor_pending and record_entry. The last one only works with a write key, is marked in the history as written through the API and never sends anything to the administration.
Why the API cannot be used to cheat
An API on top of a record with legal value has to hold up to scrutiny. In Spain, RD 1054/2022 allows the farm notebook to be kept with any software that meets the requirements of Annex II and is interoperable with SIEX, and makes clear that the owner, not the program, is responsible for the truth of the records. Our part is integrity, and it is built into the code.
| What someone might try | What the API does |
|---|---|
| Recording today with a date months back | Every task keeps the declared date and the real arrival time at the server, and the history notes the days of delay |
| Recording with a future date | Rejected if it is more than 24 hours ahead |
| Writing without a person behind it | Every task has an author, and those that come in through a key are marked with that key's prefix |
| Deleting what gets in the way | Nothing is deleted: deletions are dated tombstones |
| Submitting to the administration automatically | Official submission, which only exists in Spain and is pending each region's approval, requires the session of a person with permission: a key gets 403 SIE_403 |
Errors
Always {"code":"INT_NNN","message":"…"}, never a stack trace. The ones you will see most: AUT_003 invalid key, AUT_004 read-only key, AUT_429 too many attempts, AUT_503 authentication unavailable (not the same as a bad key: retry), INT_003 URL that is not https, INT_403 operation that requires a session, INT_404 key or webhook that is not yours.
How to get a key
The API comes with the business and advisory plans. If you already have an account, you create the key from the app itself. If you are evaluating the integration before signing up, write to support@agrogps.eu telling us which system you want to connect and we will give you test access. The documentation is public and free: we would rather you read it before you pay.
Frequently asked questions
Can I run the whole notebook from my ERP without opening the app? Yes for recording and reading. Not for official submission to the administration, which only exists in Spain and requires the session of a person with permission to submit. That is deliberate: the act has legal consequences and should not be triggered by an automatic process.
Is the data mine? Yes. The full export is always free, also if you cancel, and through the API you take away exactly what you see on screen, including history and the trail of changes.
Is there a rate limit? There is no published quota for normal ERP use. Testing a webhook is limited to twenty times per user and IP every ten minutes, so nobody uses the feature to generate traffic.
What happens if you change the API? The version is in the URL. While v1 is published we do not remove fields or change the meaning of existing ones; new things are added. If there is ever a v2, both will coexist.
Is the MCP server on npm? Not yet. Today it runs from the repository; publishing is still to be decided. The configuration above is the one that will work on the day it is published.
Does this work for an advisor with many clients? That is what advisor/portfolio is for: one call tells you which farms are up to date and which have incomplete tasks, without opening them one by one.