Vantage API Tutorial

This tutorial shows Vantage API workflows at a high level. Full schemas, parameters, and response definitions are available in the API Reference.

Authenticate

Use either a JWT token from /login or an API key in the bearer token header.

curl --location -X POST 'https://vantage.open-atlas.com/login' \
  --user 'user:password'

export YOUR_BEARER_TOKEN="xxx...xxx"

Check Tokens

Check available, reserved, and total analysis tokens before running billable analysis work.

curl -X GET 'https://vantage.open-atlas.com/users/check_tokens' \
  -H "Authorization: Bearer $YOUR_BEARER_TOKEN"

Register Plots

Register plot geometry and metadata before running analysis. Commodity and harvest date can be provided during plot registration or later when creating an analysis job.

curl -X POST 'https://vantage.open-atlas.com/plots/make_plot' \
  -H "Authorization: Bearer $YOUR_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "geojson": {
      "type": "FeatureCollection",
      "features": [
        {
          "type": "Feature",
          "properties": {},
          "geometry": {
            "type": "Point",
            "coordinates": [107.880247, 14.093255]
          }
        }
      ]
    },
    "plot_name": "Supplier plot",
    "commodity": "cocoa",
    "harvest_date": "2026-07-01",
    "additional_info": {
      "supplier_id": "SUP-001"
    }
  }'

The response includes the registered plot ID, area, plot metadata, and estimated token cost for analysis.

Create an Analysis Job

Create a job to run analysis for one or more plots. Token reservation happens when the job is created. The checks field can include EUDR checks and supported Geospatial Analysis capability types documented in the API Reference.

curl -X POST 'https://vantage.open-atlas.com/jobs/make_job' \
  -H "Authorization: Bearer $YOUR_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "plot_ids": [
      "ab5c45e9-2e18-416b-adb0-9c6cb1536594"
    ],
    "job_name": "Supplier EUDR review",
    "checks": [
      {
        "type": "eudr",
        "config": {
          "commodity": "cocoa",
          "harvest_date": "2026-07-01"
        }
      }
    ]
  }'

If checks is omitted, Vantage runs the default EUDR check.

For non-EUDR analysis jobs, use the capability type and configuration schema shown in the API Reference. Geospatial Analysis results are returned through the same job and analysis-run retrieval flow.

Retrieve Results

Retrieve job results by job ID, or retrieve a plot to inspect its latest analysis state.

curl -X GET 'https://vantage.open-atlas.com/jobs/job/YOUR_JOB_ID' \
  -H "Authorization: Bearer $YOUR_BEARER_TOKEN"

For audit history, list analysis runs for a plot or retrieve a specific analysis run.

curl -X GET 'https://vantage.open-atlas.com/analysis-runs?plot_id=YOUR_PLOT_ID' \
  -H "Authorization: Bearer $YOUR_BEARER_TOKEN"

Protected Area Checks

Protected Areas can also be used directly when you only need overlap validation.

curl -X POST 'https://vantage.open-atlas.com/protected-areas/checks' \
  -H "Authorization: Bearer $YOUR_BEARER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "plot_ids": [
      "ab5c45e9-2e18-416b-adb0-9c6cb1536594"
    ]
  }'

Use the API Reference for the complete protected area request and response schema.