Developer documentation

The Segesio ERP API lets you read and write your account's data — activities, expenses, inputs, harvests, and the rest of the operational modules — from your own systems, without going through the web interface.

It's not a mirror API or a mock: a write-scoped API key calls exactly the same endpoints the web app uses, authenticated as a real user on your account. It's an Enterprise plan feature.

Every request carries the API key in the X-API-Key header. There's no login and no token that expires in minutes — the key is valid until the expiration date it was assigned.

The full key is shown only once, at the moment you create it. Store it somewhere secure (a secrets manager, not a code repository) — if you lose it, you'll need to generate a new one.

A user with an administrator role can create keys from Settings → API Keys, inside the app.

1. Choose a descriptive name (for example, the system that will use it).
2. Select the scopes it needs — never grant more than that integration actually uses.
3. If any scope is a write scope, choose which team member that key represents: writes run with that person's real identity and permissions.
4. Set an expiration (there's a default if you don't choose one) and confirm.

The full key appears once on screen, right after you create it. Copy it before closing that view.

Every scope follows the same format the rest of the system uses: module:action. A key can never do more than the user it's tied to could do manually in the interface.

The delete action is never available to any key, on any module — to delete something, use the regular interface.

Read access is included in the Enterprise plan. Write access is a separate enablement, activated by our team on request — contact us (see Support, below) to enable it on your account.

All endpoints use the same prefix as the real Segesio ERP API. An example, creating an activity:

When the key has a write scope, the created activity is attributed to the real user the key is tied to — the same value it would get if that person had entered it from the web.

Successful responses return the created or requested resource as JSON. An error — missing permission, invalid data, expired key — returns a matching HTTP status code and a body in this format:

This is the format the framework uses by default on most endpoints. It isn't 100% standardized across every case yet — we're flagging that so your integration doesn't depend on an exact structure beyond statusCode/message.

• Rate limiting by key (not by IP address): a key shares the same limits as normal app traffic, grouped by the key itself instead of by IP.
• Every key has a mandatory expiration — 90 days by default if it has any write scope, 180 days if it's read-only. You can choose a different value when creating it.
• Up to 30 scopes per key.

If you only need to read a handful of data — farms, fields, NDVI, harvests, weather — without writing anything, there's a simpler, more stable API built for that, with these scopes:

• fincas:read
• lotes:read
• ndvi:read
• harvest:read
• weather:read

It's a smaller, more stable contract, useful for simple integrations. It doesn't replace the full catalog above, which does allow writing.

• Most list endpoints return the full result, without pagination — for large volumes, filter using the parameters each endpoint accepts.
• No outbound webhooks yet: your integration has to poll, there's no way for Segesio to notify you of a change.
• Error format isn't 100% standardized across every endpoint — see the note in Response and error format.
• No key rotation without recreating: to rotate a key, create a new one and revoke the old one.

Need us to enable write access on your account, or have a specific question about an endpoint? Reach out.