Create a new job

Request

Creates a new job that runs one or more analysis checks over the given list of plot_ids. Use the checks array to select which analyses run; if it is omitted, a single eudr check is run by default. The available check types are listed in GET /v3/discovery/capabilities.

Warning: This operation will consume user tokens. Tokens are reserved when the job is created; tokens reserved for plots that fail to complete analysis are refunded when the job settles.

Atomicity. Job creation is all-or-nothing. The request is validated in full before anything is written: if any plot in plot_ids fails validation, the call returns 400, no job is created and no tokens are reserved. Correct the input and resubmit. Once a job has been created, each plot and each check is analysed independently, so a plot that cannot be processed does not stop the others. The job then finishes as done-with-errors, and tokens reserved for the plots that did not complete are refunded.

Security

BearerAuth

Authorizationstring

Authorization header with a Bearer token, formatted as 'Bearer [JWT]' where [JWT] is the JSON Web Token used for user authentication and authorization.

Example:Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.your-payload-here.signature

X-Dry-Runboolean

Optional boolean. When true, runs the job in dry-run mode: skips token consumption and heavy compute and returns a simulated analysis with dummy visualization. Use dry-run to preview the token cost of a job before committing tokens.

Example:true

Bodyapplication/jsonrequired

Details of the job to create

job_namestring, <= 255 characters

Name of the job. Free-text label of up to 255 characters. Digits, spaces, punctuation and non-Latin characters are permitted; control characters (line breaks, tabs and other non-printing characters) are rejected. Stored and returned exactly as sent

Example:"Planting season analysis for Q1"

plot_idsArray of stringsrequired

List of plot IDs that belong to the user to be analyzed in the job. Up to 10,000 plots per job; each plot ID can appear only once per job

Example:

[
  "ef6f5727-307f-4e9d-abcb-74a8b6af0366",
  "asd9632d-b589-4e05-9c8b-58fed1f9823a3"
]

notesstring

Additional notes about the job

Example:"Analysis for initial planting"

additional_infoobject

Additional information about the job as key-value pairs, where keys and values are both strings

Example:

{
  "soilQuality": "High",
  "irrigationType": "Drip"
}

checksArray of objects(JobCheckConfig)

Optional list of check definitions to run for this job. If omitted or empty, a single 'eudr' check is run by default. Each check names an analysis capability from GET /v3/discovery/capabilities and can carry its own configuration. Multiple checks can be combined in one job; each check produces its own analysis run per plot. Duplicate entries with the same type are collapsed — the first occurrence wins and the job is priced once per distinct check.

Example:

[
  {
    "type": "eudr",
    "config": { … },
    "per_plot": { … }
  },
  {
    "type": "soil_moisture"
  },
  {
    "type": "visual_verification",
    "config": { … }
  }
]

curl -i -X POST \
  https://api.open-atlas.com/_mock/openapi/jobs/make_job \
  -H 'Authorization: Bearer <YOUR_JWT or vantage_live_ API key_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'X-Dry-Run: true' \
  -d '{
    "job_name": "Planting season analysis for Q1",
    "plot_ids": [
      "ef6f5727-307f-4e9d-abcb-74a8b6af0366",
      "asd9632d-b589-4e05-9c8b-58fed1f9823a3"
    ],
    "notes": "Analysis for initial planting",
    "additional_info": {
      "soilQuality": "High",
      "irrigationType": "Drip"
    },
    "checks": [
      {
        "type": "eudr",
        "config": {
          "harvest_date": "2024-11-01",
          "commodity": "cocoa"
        },
        "per_plot": {
          "ef6f...0366": {
            "harvest_date": "2024-12-01"
          }
        }
      },
      {
        "type": "soil_moisture"
      },
      {
        "type": "visual_verification",
        "config": {
          "prompt": "Is there active construction inside the plot boundary?"
        }
      }
    ]
  }'

Responses

Job created successfully and plots to be analyzed

Bodyapplication/json

usernamestring

Name of the user account that created and owns the job

Example:"abc_pro"

notesstring

Additional notes related to the plot

Example:"This plot requires frequent irrigation."

job_idstring

Unique identifier for the job

Example:"a31da612-fefe-4da8-800d-0e7120f5617e"

job_namestring, <= 255 characters

Name of the job

Example:"August shipment 827128"

plot_idsArray of strings

A list of IDs of plots to be analyzed in the job

Example:

[
  "ef6f5727-307f-4e9d-abcb-74a8b6af0366",
  "asd9632d-b589-4e05-9c8b-58fed1f9823a3"
]

created_atstring, (date-time)

Timestamp of job creation

updated_atstring, (date-time)

Timestamp of job update, for example when the job's analysis is complete

additional_infoobject

Analysis data for the plot, represented as key-value pairs

Example:

{
  "job_urgency": "high",
  "reviewer": "employee A"
}

token_costinteger, (int32)

Amount of tokens the job costs based on the plots and the selected checks

Example:8

statusstring

Current status of the job

Enum:"creating""pending""incomplete""done-with-errors""done"

plotsArray of objects(Plot)

List of plots associated with the job

job_visualization_urlArray of strings

List of URLs for visualizations of analysis of plots associated with the job

Example:

[
  "https://example.com/ef6f5727-307f-4e9d-abcb-74a8b6af0366.png",
  "https://example.com/asd9632d-b589-4e05-9c8b-58fed1f9823a3.png"
]

harvest_datestringdeprecated

Response

{
  "username": "abc_pro",
  "notes": "This plot requires frequent irrigation.",
  "job_id": "a31da612-fefe-4da8-800d-0e7120f5617e",
  "job_name": "August shipment 827128",
  "plot_ids": [
    "ef6f5727-307f-4e9d-abcb-74a8b6af0366",
    "asd9632d-b589-4e05-9c8b-58fed1f9823a3"
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "additional_info": {
    "job_urgency": "high",
    "reviewer": "employee A"
  },
  "token_cost": 8,
  "harvest_date": "string",
  "status": "creating",
  "plots": [
    { … }
  ],
  "job_visualization_url": [
    "https://example.com/ef6f5727-307f-4e9d-abcb-74a8b6af0366.png",
    "https://example.com/asd9632d-b589-4e05-9c8b-58fed1f9823a3.png"
  ]
}

Create a new job

Request

Headers

Responses

Was this helpful?