Vantage API (3.1.0)

Authentication

Most endpoints require a bearer token in the Authorization header. Two kinds of token are accepted interchangeably:

• JWT — obtained from POST /login with Basic Auth credentials. Best for interactive, short-lived sessions.
• API key — a long-lived programmatic secret that begins with the vantage_live_ prefix. Send it exactly like a JWT: Authorization: Bearer vantage_live_.... It works on any user endpoint that accepts a JWT. Create and manage your API keys from the API page in your account at https://web.vantage.open-atlas.com/app/api. API keys are the recommended way to authenticate accounts that have no password (e.g. Google sign-ups).

Analyses

Analyses are run by creating a job (POST /jobs/make_job) with one or more checks. Each check has a type naming an analysis capability and an optional config. If checks is omitted, a single eudr check is run by default.

The full capability catalog — including a machine-readable configuration schema (input_schema), display label, result key, and token cost hint for every analysis — is available from GET /v3/discovery/capabilities.

Capabilities fall into three groups:

• Compliance and land status — eudr (deforestation + protected areas + Indigenous land bundle), deforestation, protected_area, indigenous_land, deforestation_risk, forest_loss_by_year, compliance_verification_pack, property_due_diligence, supplier_site_risk_screen.
• Environment, crop and hazard signals — canopy_condition, soil_moisture, productivity_trend, farm_portfolio_health, agricultural_drought_stress, agricultural_climate_aridity, enso_teleconnection, enso_seasonal_outlook, precipitation, water_detection, land_cover, surface_temperature, fire_damage, flood_water_history, flood_risk_5weeks, flood_risk_5years, wildfire_burn_history, wildfire_risk_5weeks, wildfire_risk_5years, coastal_erosion_risk.
• Site suitability and verification — solar_site_suitability, vineyard_site_suitability, data_center_site_suitability, asset_inspection_priority, visual_verification.

Results land in the plot's analysis object. The EUDR bundle writes the legacy top-level fields plus eudr, protected_areas, and indigenous_land; every other capability writes its result under a key matching the capability name (see each capability's result_key in the discovery endpoint when it differs).

Tokens

Running analyses consumes analysis tokens, reserved when the job is created and settled when it completes. The cost depends on the selected capabilities and the plots being analyzed. To preview the exact cost of a job before committing tokens, create it with the X-Dry-Run: true header; per-capability cost information is also returned as cost_hint by GET /v3/discovery/capabilities. Tokens reserved for plots that fail to complete analysis are refunded.

Versioning

Every request must send the X-API-Version header set to 3. Requests without the header receive 400 {"code":400,"error":"MISSING_API_VERSION","message":"The X-API-Version header is required. Please set it to 3. See https://docs.open-atlas.com/docs/changelog#api-versioning for details."}; an unsupported value receives 400 {"code":400,"error":"INVALID_API_VERSION","message":"Invalid X-API-Version value: '2'. Supported versions are: 3."}.

Errors

Most errors are returned as a JSON object {"code": <integer status>, "message": "<message>"}. Exceptions to be aware of:

• Pagination errors on GET /plots and GET /jobs return code as a string: {"code":"400","message":"Cursor not found"}.
• POST /login, the token-balance 404, and the insufficient-tokens 400 outside of make_job return the message as a plain string body (with a JSON content type).
• A few endpoints return {"error": "<message>"} (noted per endpoint below).
• A missing or invalid bearer token returns 401 with the plain-text body Credentials are required to access this resource. and a WWW-Authenticate: Bearer realm="realm" header.
• An authenticated user lacking the required role receives 403 {"code":403,"message":"HTTP 403 Forbidden"}; attempting to access another user's resource receives 403 {"code":403,"message":"Unauthorized access to entity retrieved"}.
• A syntactically invalid JSON body returns 400 {"code":400,"message":"Unable to process JSON"}. A structurally invalid body returns 400 with one of: Unable to process JSON: Unknown property: <name>, Invalid check type '<value>'. Allowed types: <list>, Invalid commodity '<value>'. Allowed types: <list>, Invalid Polygon in GeoJSON: the ring is not closed. The first and last coordinate in a LinearRing must be identical., or Invalid Geometry in GeoJSON: <detail>.
• Unhandled server errors return 500 {"code":500,"message":"There was an error processing your request. It has been logged (ID <16-hex-digit id>)."} — the id correlates with our server logs; no internal details are exposed.
• Protocol-level errors use the generic bodies {"code":404,"message":"HTTP 404 Not Found"} (unknown path or non-numeric path parameter), {"code":405,"message":"HTTP 405 Method Not Allowed"}, {"code":406,"message":"HTTP 406 Not Acceptable"}, and {"code":415,"message":"HTTP 415 Unsupported Media Type"} (e.g. a POST without Content-Type: application/json).