AGRO-AI Guides / Platform API

AGRO-AI Platform API

A product-grounded guide for engineering teams integrating agricultural data, recommendations, reporting and operational intelligence into their own software.

What the Platform API is

The Platform API is a separate developer product from the Enterprise Portal. It exposes a curated, organization-scoped REST surface for agricultural product teams that want to work with AGRO-AI resources from their own backend.

The current public contract centers on:

• fields and source registration;
• observation ingestion and query;
• recommendation requests;
• report generation and asynchronous jobs;
• provider readiness and synchronization;
• usage and safe request-log visibility;
• service accounts, scoped API keys and environment controls;
• webhook infrastructure where delivery is enabled.

Base path:

https://api.agroai-pilot.com/v1/platform

Understand the current product state

Platform API capabilities are deliberately separated so one product flag cannot silently activate unrelated production behavior. The important boundaries are:

A TEST project is structurally a TEST project. It is not promoted in place into a LIVE project. LIVE access uses a separate reviewed path.

Quickstart

For an organization already provisioned for the Platform API, the shortest reliable path is:

1. Sign in to the Developer Console. Use platform.agroai-pilot.com with the AGRO-AI account associated with the approved organization.
2. Create a TEST project. TEST projects use deterministic synthetic data and are intentionally isolated from LIVE access.
3. Create a service account. Give the machine identity only the scopes and optional resource/provider restrictions it needs.
4. Create a TEST key. Plaintext API keys are shown once. Store the value in your server-side secret manager immediately.
5. Make an authenticated request. Start with an identity or read route before building writes.

curl https://api.agroai-pilot.com/v1/platform/me \
  -H "Authorization: Bearer $AGROAI_API_KEY" \
  -H "X-Request-Id: quickstart-001"

Then list a safe resource such as fields:

curl https://api.agroai-pilot.com/v1/platform/fields \
  -H "Authorization: Bearer $AGROAI_API_KEY"

Authentication, service accounts and scopes

Platform API machine access uses Bearer API keys associated with service accounts. Portal browser sessions/JWTs are not interchangeable with Platform API keys.

• TEST keys use the agro_test_ prefix.
• LIVE keys use the agro_live_ prefix when LIVE access is separately available.
• Service accounts can be restricted by scope and can also be bounded by workspace, provider, resource and optional CIDR policy.
• A key can narrow the service account's permissions; it cannot widen them.

Common scope examples in the current contract include fields:read, fields:write, sources:read, observations:write, recommendations:write, reports:read, webhooks:write and usage:read.

Key handling checklist

• Store the plaintext key immediately because it is intended to be shown once.
• Use the minimum scopes required.
• Use environment-specific keys; do not share one key across unrelated services.
• Rotate with bounded overlap, then revoke the old key.
• Revoke or disable a key immediately if exposure is suspected.

Projects and environments

Projects are organization-scoped and explicitly typed as TEST or LIVE. Environment separation is a security and commercial boundary, not a label you should infer from the hostname alone.

TEST

TEST is for integration development. The deterministic sandbox can include synthetic organizations, farms, fields, zones, crops, seasons, irrigation systems, observations, anomalies, recommendations, reports, jobs and webhook events. It does not contain customer provider credentials, real charges or physical execution.

LIVE

LIVE requires a separate live-access decision, an eligible plan or contract and production-readiness review. Provider access can have additional enrollment requirements. Do not write code that assumes a TEST project will later receive LIVE privileges.

Resource model

Fields and sources

Fields can be created and safely updated within project scope. The current contract supports field boundaries as GeoJSON Polygon or MultiPolygon values.

curl -X POST https://api.agroai-pilot.com/v1/platform/fields \
  -H "Authorization: Bearer $AGROAI_API_KEY" \
  -H "Idempotency-Key: field-create-001" \
  -H "Content-Type: application/json" \
  -d '{"name":"North Block","crop":"almond","area_hectares":24.6}'

Sources describe where data comes from. Direct upload flows use project/organization namespaces and can require expected checksums so the backend can verify that the stored object matches what the client intended to send.

Observations

Observations are queryable by field, type and time range. The contract is designed to preserve provenance and quality flags so downstream applications can distinguish the source and quality of operational context.

For batch ingestion:

1. validate the payload before sending;
2. use one logical idempotency key for the logical write;
3. store the returned job/request identifiers;
4. wait for the asynchronous result instead of assuming the POST means processing is complete;
5. query the resulting observations and inspect provenance/quality.

Recommendations

Recommendation computation is asynchronous. The intended pattern is:

Recommendations are advisory. Design your product so a recommendation can be reviewed with its evidence and provenance rather than silently converting a model result into a physical action.

Reports and jobs

Report generation is also asynchronous. Report metadata is designed not to expose raw object-storage paths; authorized content is returned through the product's download boundary.

Your application should treat jobs as first-class objects:

• persist the job ID;
• poll with a bounded interval/backoff;
• handle success and terminal failure separately;
• avoid creating duplicate work when retrying;
• surface the server request ID for support/debugging.

Providers and connector jobs

The provider catalog is designed to report truthful capability state instead of implying that every integration is production-ready. Synchronization can be restricted by key scope, organization enrollment, provider and resource policy.

Partner/provider integrations may require a separate technical and commercial review, credential-vault readiness and explicit sandbox/read/write/production status. Provider credentials must remain in the credential boundary and must not be embedded in application JSON or logs.

Idempotency

Logical writes accept or require an Idempotency-Key. Use a stable key for retries of the same logical operation and a new key for a genuinely new operation.

The server contract distinguishes between:

• a completed matching request, which can replay the stored response;
• a concurrent matching operation, which can return an operation-in-progress state;
• reuse of the same idempotency key with different content, which is a conflict.

This prevents network retries from accidentally creating duplicate fields, observation batches or report/recommendation work.

Pagination and filtering

Collection routes use bounded limit values and opaque cursor tokens. A paginated response uses:

{
  "items": [...],
  "next_cursor": "...",
  "has_more": true
}

Do not construct cursors manually. Pass the returned next_cursor back to the API until has_more is false.

Errors and request IDs

Errors use a typed structure with fields such as code, type, message and request_id. Every response receives a server-generated X-Request-Id. Use that server value when contacting AGRO-AI Support.

Rate limits and API credits

Rate-limit responses expose RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset. Build clients that can slow down before a hard limit becomes an outage.

The API also has a credit ledger model for metered operations. Platform API commercial plans are a separate billing boundary from Enterprise Portal plans. Do not assume buying one automatically changes the other.

Webhooks

The webhook contract supports versioned events with an event ID and timestamp, HMAC-SHA256 signatures, durable retry behavior, delivery history and redelivery controls. Production webhook delivery is separately gated, so your organization must actually have the capability enabled before depending on delivery.

AgroAI-Signature: t=<timestamp>,v1=<hex-hmac>
AgroAI-Event-Id: <event-id>
AgroAI-Event-Version: 2026-07-01

Receiver requirements:

• verify the signature and timestamp;
• deduplicate by event ID;
• return quickly and move heavy work to your own queue;
• handle retries safely;
• never log the signing secret.

Security checklist

• Keep API keys and webhook secrets server-side.
• Use minimum scopes and resource/provider restrictions.
• Use separate TEST and LIVE credentials.
• Rotate and revoke credentials deliberately.
• Validate webhook timestamps and deduplicate event IDs.
• Use idempotency for writes.
• Keep server request IDs for operational debugging.
• Do not pass organization IDs or privileged scope decisions from untrusted browser input and assume they grant authority.
• Do not expose provider credentials in application JSON, frontend bundles or logs.

Deterministic TEST sandbox

The TEST environment exists so a developer can build against stable agricultural objects without using customer data. It is intentionally resettable and deterministic.

Use TEST for:

• schema and client development;
• pagination/error handling;
• recommendation/report job orchestration;
• webhook receiver development using TEST-safe events where available;
• usage and observability integration;
• CI and repeatable integration tests.

Do not use TEST as evidence that a LIVE provider, production webhook or physical action is enabled.

SDKs and CLI

The repository contains Python and TypeScript SDK foundations with typed errors, request IDs, rate-limit state, safe retries, pagination, uploads, job polling, usage access and webhook verification. Public package-registry availability must not be assumed until the relevant namespace/release path is actually activated.

The repository also contains an AGRO-AI CLI and public installer paths designed for the protected public TEST self-service launch. Because that launch has separate production gates, use the installation path advertised by the live Platform API site rather than assuming every repository installer route is currently public.

Recommended integration patterns

Add AGRO-AI intelligence to an existing farm application

1. Model or map your fields into the Platform field resource.
2. Register the source(s) that provide operational context.
3. Ingest observations with provenance.
4. Request recommendations asynchronously.
5. Show the recommendation with evidence/provenance in your own UI.
6. Keep user approval/execution as a separate application decision.

Use AGRO-AI for reporting

1. Keep the field/source/observation context current.
2. Create a report request with an idempotency key.
3. Poll the returned job.
4. Retrieve the authorized report metadata/content only after completion.
5. Store only the identifiers and artifacts your own retention policy requires.

Connect a provider or enterprise system

1. Read provider readiness for the organization/environment.
2. Confirm the required enrollment, scope and provider capability.
3. Complete the approved credential/connection flow.
4. Run synchronization through the durable job path.
5. Observe job and request IDs; do not assume connection means a sync has completed.

Troubleshooting

401 after a key worked previously

Check whether the key was rotated, revoked or environment-mismatched. If the key uses CIDR restrictions, confirm the trusted client address reaching AGRO-AI still matches the allowed network.

403 on a valid key

A valid key can still lack the required scope, provider enrollment, resource permission or environment entitlement. Do not solve a 403 by blindly generating a broader key.

409 on a write

Review the idempotency key and current operation state. A reused key with changed payload is intentionally rejected.

429 responses

Honor the rate-limit reset/backoff information and inspect API credit usage. Retrying immediately in a tight loop makes the situation worse.

An asynchronous request never becomes successful

Inspect the job's terminal state and server request ID. Do not keep polling indefinitely after a terminal failure. Include those IDs in Support.

Frequently asked questions