openapi: 3.0.1
info:
  title: Vantage API
  description: >-
    REST API for queuing and running geospatial analyses on user plots. Create
    jobs, validate and queue plots, and retrieve per-plot analysis results
    (e.g., EUDR, deforestation, protected areas).
  contact:
    name: Ahmed Elfouly
    url: https://open-atlas.com/contact
    email: info@open-atlas.com
  license:
    name: OpenAtlas - User License Agreement
    url: https://open-atlas.com/license
  version: 3.0.1
paths:
  /login:
    post:
      summary: Login to receive a JWT
      description: >-
        Authenticates a user using Basic Auth credentials and returns a JWT
        token if successful.
      operationId: login
      parameters:
        - name: Authorization
          in: header
          description: >-
            Authorization header with Basic Auth format 'Basic
            base64(username:password)'
          required: true
          schema:
            type: string
          example: Basic bXJmb3VseTptcnBhc3N3b3Jk
      requestBody:
        description: Basic Authorization header with encoded username and password
        content:
          application/json: {}
        required: true
      responses:
        '200':
          description: User authenticated successfully. JWT token returned in the response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AuthToken'
        '400':
          description: Bad Request - missing or invalid Authorization header format
        '401':
          description: Unauthorized - invalid username or password
        '500':
          description: Internal server error
      security:
        - BasicAuth: []
  /plots/make_plot:
    post:
      summary: Create a new plot
      description: Creates a new plot based on the given geojson and metadata
      operationId: createPlot
      parameters:
        - name: Authorization
          in: header
          description: >-
            Authorization header with a Bearer token, formatted as 'Bearer
            [JWT]' where [JWT] is the JSON Web Token used for user
            authentication and authorization.
          schema:
            type: string
          example: >-
            Bearer
            eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.your-payload-here.signature
      requestBody:
        description: Details of the plot to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PlotInput'
        required: true
      responses:
        '200':
          description: Plot created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plot'
        '400':
          description: Invalid input data
          content:
            application/json:
              examples:
                The plot's coordinates are not in land:
                  description: >-
                    The plot created is not fully on land and part of it could
                    be covering water like the ocean
                  value:
                    code: '400'
                    message: The plot's coordinates are not in land
                Polygon size exceeds the maximum limit of 10,000 hectares.:
                  description: >-
                    The polygon of the geojson provided represents a landscape
                    of over 10,000 which is the maximum size
                  value:
                    code: '400'
                    message: Polygon size exceeds the maximum limit of 10,000 hectares.
                GeoJson Feature must have a Polygon or Point geometry.:
                  description: >-
                    The 'type' field in 'geometry' in the 'geoJson' Feature must
                    be either 'Polygon' or 'Point'.
                  value:
                    code: '400'
                    message: GeoJson Feature must have a Polygon or Point geometry.
                Each coordinate must have exactly two elements (longitude and latitude).:
                  description: Each coordinate must have only 2 elements, not more nor less
                  value:
                    code: '400'
                    message: >-
                      Each coordinate must have exactly two elements (longitude
                      and latitude).
                Polygon's first and last coordinates must be the same to close the shape.:
                  description: >-
                    For a geojson of type Polygon the last coordinate needs to
                    be the same as the first to close the shape
                  value:
                    code: '400'
                    message: >-
                      Polygon's first and last coordinates must be the same to
                      close the shape.
                GeoJson FeatureCollection must contain exactly one Feature.:
                  description: >-
                    We only accept 1 geojson feature per FeatureCollection to
                    register 1 polygon per plot
                  value:
                    code: '400'
                    message: >-
                      GeoJson FeatureCollection must contain exactly one
                      Feature.
                ' Invalid geometry.':
                  description: Only valid geometry is accepted
                  value:
                    code: '400'
                    message: >-
                      Invalid geometry: Contains self-intersections or invalid
                      point ordering
        '500':
          description: Internal server error
      security:
        - BearerAuth: []
  /plots/plot/{plot_id}:
    get:
      summary: Retrieve plot details
      description: Fetches details of a specific plot by its unique plot_id
      operationId: getPlot
      parameters:
        - name: Authorization
          in: header
          description: >-
            Authorization header with a Bearer token, formatted as 'Bearer
            [JWT]' where [JWT] is the JSON Web Token used for user
            authentication and authorization.
          schema:
            type: string
          example: >-
            Bearer
            eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.your-payload-here.signature
        - name: plot_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Plots details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Plot'
        '403':
          description: >-
            Forbidden: The user retrieving the plot does not have permission to
            access it
          content:
            application/json:
              examples:
                Unauthorized access to entity retrieved:
                  description: >-
                    Forbidden: The user retrieving the plot does not have
                    permission to access it
                  value:
                    code: '403'
                    message: Unauthorized access to entity retrieved
        '404':
          description: PlotID requested does not exist
          content:
            application/json:
              examples:
                PlotID not found:
                  description: PlotID requested does not exist
                  value:
                    code: '404'
                    message: PlotID not found
        '500':
          description: Internal server error
      security:
        - BearerAuth: []
  /plots:
    get:
      summary: List user's plots
      description: >-
        Returns the authenticated user's plots with keyset pagination (newest
        first).
      operationId: listUserPlots
      parameters:
        - name: Authorization
          in: header
          description: >-
            Authorization header with a Bearer token, formatted as 'Bearer
            [JWT]' where [JWT] is the JSON Web Token used for user
            authentication and authorization.
          schema:
            type: string
          example: >-
            Bearer
            eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.your-payload-here.signature
        - name: limit
          in: query
          description: Maximum number of items to return (default 100, max 1000)
          schema:
            type: integer
            format: int32
            default: 100
        - name: cursor
          in: query
          description: Opaque cursor for the next page
          schema:
            type: string
        - name: created_at_from
          in: query
          description: 'Filter: inclusive lower bound for created_at (ISO-8601)'
          schema:
            type: string
        - name: created_at_until
          in: query
          description: 'Filter: inclusive upper bound for created_at (ISO-8601)'
          schema:
            type: string
        - name: lite
          in: query
          description: >-
            When true, returns lightweight summaries with pagination meta; when
            false, returns full PlotDTOv2 list
          schema:
            type: boolean
            default: false
      responses:
        '200':
          description: List of Plot details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlotsListResponse'
        '400':
          description: Invalid parameters
      security:
        - BearerAuth: []
  /analysis-runs:
    get:
      summary: List analysis runs for a plot
      description: >-
        Returns all analysis runs associated with the provided plot_id. Each
        item summarizes the run, including status, timing, tokens cost, and
        links to artifacts.
      operationId: listRunsForPlot
      parameters:
        - name: plot_id
          in: query
          description: Plot ID to list runs for
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            Authorization header with a Bearer token, formatted as 'Bearer
            [JWT]' where [JWT] is the JSON Web Token used for user
            authentication and authorization.
          schema:
            type: string
          example: >-
            Bearer
            eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.your-payload-here.signature
        - name: plot_id
          in: query
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/PlotAnalysisRunDTO'
        '400':
          description: Invalid or missing parameters
          content:
            application/json:
              examples:
                Missing plot_id:
                  description: The required plot_id query parameter was not provided
                  value:
                    error: plot_id is required
        '403':
          description: >-
            Forbidden: The authenticated user does not have permission to access
            the specified plot
          content:
            application/json:
              examples:
                Unauthorized access to plot:
                  description: The user does not own the plot or lacks required permissions
                  value:
                    code: '403'
                    message: Unauthorized access to entity retrieved
        '404':
          description: Plot not found
          content:
            application/json:
              examples:
                Plot not found:
                  description: >-
                    Generic not-found message thrown by internal lookup when
                    plot_id does not exist
                  value:
                    error: Plot not found
                PlotID not found:
                  description: The provided plot_id does not exist
                  value:
                    code: '404'
                    message: PlotID not found
        '500':
          description: Internal server error
      security:
        - BearerAuth: []
  /analysis-runs/{run_id}:
    get:
      summary: Retrieve analysis run details
      description: >-
        Returns the full analysis run details for the provided run_id, including
        analysis output, status, configuration used, and artifact links.
      operationId: getAnalysisByRunId
      parameters:
        - name: Authorization
          in: header
          description: >-
            Authorization header with a Bearer token, formatted as 'Bearer
            [JWT]' where [JWT] is the JSON Web Token used for user
            authentication and authorization.
          schema:
            type: string
          example: >-
            Bearer
            eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.your-payload-here.signature
        - name: run_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlotAnalysisRunDTO'
        '403':
          description: >-
            Forbidden: The authenticated user does not have permission to access
            the run
          content:
            application/json:
              examples:
                Unauthorized access to run:
                  description: The user does not own the plot associated with the run
                  value:
                    code: '403'
                    message: Unauthorized access to entity retrieved
        '404':
          description: Run not found or analysis missing
          content:
            application/json:
              examples:
                Run not found:
                  description: The provided run_id does not exist
                  value:
                    error: Run not found
        '500':
          description: Internal server error
      security:
        - BearerAuth: []
  /jobs/make_job:
    post:
      summary: Create a new job
      description: >-
        Creates a new job based on the given list of plot_ids. **Warning:** This
        operation will consume user tokens
      operationId: createJob
      parameters:
        - name: Authorization
          in: header
          description: >-
            Authorization header with a Bearer token, formatted as 'Bearer
            [JWT]' where [JWT] is the JSON Web Token used for user
            authentication and authorization.
          schema:
            type: string
          example: >-
            Bearer
            eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.your-payload-here.signature
        - name: X-Dry-Run
          in: header
          description: >-
            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.
          schema:
            type: boolean
          example: true
      requestBody:
        description: Details of the job to create
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/JobInput'
        required: true
      responses:
        '200':
          description: Job created successfully and plots to be analyzed
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '400':
          description: Invalid input data
        '500':
          description: Internal server error
      security:
        - BearerAuth: []
  /jobs/job/{job_id}:
    get:
      summary: Retrieve job details
      description: Fetches details of a specific job by its unique job_id
      operationId: getJob
      parameters:
        - name: Authorization
          in: header
          description: >-
            Authorization header with a Bearer token, formatted as 'Bearer
            [JWT]' where [JWT] is the JSON Web Token used for user
            authentication and authorization.
          schema:
            type: string
          example: >-
            Bearer
            eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.your-payload-here.signature
        - name: job_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Job details retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Job'
        '403':
          description: >-
            Forbidden: The user retrieving the job does not have permission to
            access it
        '404':
          description: Job not found
        '500':
          description: Internal server error
      security:
        - BearerAuth: []
  /jobs:
    get:
      summary: List user's jobs
      description: >-
        Returns the authenticated user's jobs with keyset pagination (newest
        first). Each job includes plot_ids and job_visualization_url (no
        embedded plot objects). The response includes a meta object with
        pagination info.
      operationId: listUserJobs
      parameters:
        - name: Authorization
          in: header
          description: >-
            Authorization header with a Bearer token, formatted as 'Bearer
            [JWT]' where [JWT] is the JSON Web Token used for user
            authentication and authorization.
          schema:
            type: string
          example: >-
            Bearer
            eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.your-payload-here.signature
        - name: limit
          in: query
          description: Maximum number of items to return (default 100, max 1000)
          schema:
            type: integer
            format: int32
            default: 100
        - name: cursor
          in: query
          description: Opaque cursor for the next page
          schema:
            type: string
        - name: created_at_from
          in: query
          description: 'Filter: inclusive lower bound for created_at (ISO-8601)'
          schema:
            type: string
        - name: created_at_until
          in: query
          description: 'Filter: inclusive upper bound for created_at (ISO-8601)'
          schema:
            type: string
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/JobsListResponse'
        '400':
          description: Invalid parameters
      security:
        - BearerAuth: []
  /protected-areas/checks:
    post:
      tags:
        - Protected Areas
      summary: Check protected-areas overlap
      description: >-
        Accepts a JSON object with 'plot_ids' (array of strings) and/or
        'geojson' (At least one of the two fields must be provided). Returns a
        single GeoJSON FeatureCollection with all results.
      operationId: runProtectedAreasAnalysis
      parameters:
        - name: Authorization
          in: header
          description: >-
            Authorization header with a Bearer token, formatted as 'Bearer
            [JWT]' where [JWT] is the JSON Web Token used for user
            authentication and authorization.
          schema:
            type: string
          example: >-
            Bearer
            eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.your-payload-here.signature
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProtectedAreasAnalysisRequest'
            examples:
              Plot IDs and GeoJSON FeatureCollection:
                description: Plot IDs and GeoJSON FeatureCollection
                value:
                  plot_ids:
                    - b7e1c2d3-4f5a-6789-0abc-def123456789
                  geojson:
                    type: FeatureCollection
                    features:
                      - type: Feature
                        properties: {}
                        geometry:
                          coordinates:
                            - - - 10.12345
                                - 20.54321
                              - - 10.54321
                                - 20.12345
                              - - 10.6789
                                - 20.6789
                              - - 10.12345
                                - 20.54321
                          type: Polygon
                      - type: Feature
                        properties: {}
                        geometry:
                          coordinates:
                            - - - 11.11111
                                - 21.22222
                              - - 11.33333
                                - 21.44444
                              - - 11.55555
                                - 21.66666
                              - - 11.11111
                                - 21.22222
                          type: Polygon
                      - type: Feature
                        properties: {}
                        geometry:
                          coordinates:
                            - - - 12.00001
                                - 22.00002
                              - - 12.00003
                                - 22.00004
                              - - 12.00005
                                - 22.00006
                              - - 12.00001
                                - 22.00002
                          type: Polygon
        required: true
      responses:
        '200':
          description: GeoJSON FeatureCollection with protected area analysis results
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeoJson'
              examples:
                Protected Areas Analysis Result:
                  description: Protected Areas Analysis Result
                  value:
                    type: FeatureCollection
                    features:
                      - geometry:
                          type: Polygon
                          coordinates:
                            - - - -71.67370201
                                - -46.78932844
                              - - -71.1882715
                                - -46.80453387
                              - - -71.29871365
                                - -46.6639686
                              - - -71.67370201
                                - -46.78932844
                        properties:
                          protected_areas:
                            protected_area_overlap_summary:
                              protected_area_overlap: true
                              total_overlap_percentage: 17.741321358361883
                              total_overlap_area_ha: 5023.546300126338
                            protected_area_details:
                              - area_id: '7'
                                area_name: PATAGONIA
                                iucn_category: II
                                overlap_area_ha: 5023.546300126338
                            sources:
                              - source_name: >-
                                  Administración de Parques Nacionales. Sistema
                                  de Información de Biodiversidad. sib.gob.ar
                                data_version: '2024'
                          plot_id: cfa1df5b-d70b-4826-81dd-48658f1894d5
                        type: Feature
                      - geometry:
                          type: Polygon
                          coordinates:
                            - - - -71.60721003
                                - -46.66219205
                              - - -71.66565717
                                - -47.11845441
                              - - -71.06092377
                                - -47.12288502
                              - - -71.05828569
                                - -46.64869787
                              - - -71.60721003
                                - -46.66219205
                        properties:
                          protected_areas:
                            protected_area_overlap_summary:
                              protected_area_overlap: true
                              total_overlap_percentage: 25.622002684582775
                              total_overlap_area_ha: 58309.13124547163
                            protected_area_details:
                              - area_id: '7'
                                area_name: PATAGONIA
                                iucn_category: II
                                overlap_area_ha: 58309.13124547163
                            sources:
                              - source_name: >-
                                  Administración de Parques Nacionales. Sistema
                                  de Información de Biodiversidad. sib.gob.ar
                                data_version: '2024'
                          plot_id: 56e66664-20c9-4e06-a711-431db3d5ae91
                        type: Feature
                      - geometry:
                          type: Polygon
                          coordinates:
                            - - - -71.39181567
                                - -46.83188252
                              - - -71.39180924
                                - -46.87021335
                              - - -71.30040289
                                - -46.86616663
                              - - -71.30039428
                                - -46.82376187
                              - - -71.39181567
                                - -46.83188252
                        properties:
                          protected_areas:
                            protected_area_overlap_summary:
                              protected_area_overlap: false
                              total_overlap_percentage: 0
                              total_overlap_area_ha: 0
                            protected_area_details: []
                            sources: []
                          plot_id: cc7fc139-90c6-408c-acb3-bc2209b94669
                        type: Feature
        '400':
          description: No valid plot_ids or geojson features provided
          content:
            application/json:
              schema:
                type: string
                example:
                  error: No valid plot_ids or geojson features provided
        '500':
          description: >-
            Failed to update and return plots with analysis results or analyse
            supplied GeoJSON
          content:
            application/json:
              schema:
                type: string
                example:
                  error: Failed to update plots with analysis results
      security:
        - BearerAuth: []
  /protected-areas/{area_id}:
    get:
      tags:
        - Protected Areas
      summary: Fetch protected area details
      description: >-
        Returns a GeoJSON FeatureCollection for the protected area with the
        given area_id.
      operationId: getProtectedAreaById
      parameters:
        - name: Authorization
          in: header
          description: >-
            Authorization header with a Bearer token, formatted as 'Bearer
            [JWT]' where [JWT] is the JSON Web Token used for user
            authentication and authorization.
          schema:
            type: string
          example: >-
            Bearer
            eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.your-payload-here.signature
        - name: area_id
          in: path
          required: true
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: GeoJSON Feature for the protected area
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GeoJsonFeature'
              examples:
                Protected Area Feature:
                  description: Protected Area Feature
                  value:
                    geometry:
                      type: MultiPolygon
                      coordinates:
                        - - - - -95.46394368
                              - 30.18561754
                            - - -95.46391804
                              - 30.18473713
                            - - -95.46612682
                              - 30.18474856
                            - - -95.46613386
                              - 30.1847486
                            - - -95.46613386
                              - 30.18560282
                            - - -95.46394384
                              - 30.18562288
                            - - -95.46394368
                              - 30.18561754
                    properties:
                      area_name: Shenandoah Park
                      iucn_category: Unknown
                      source: USGS
                      area_id: '311224'
                    type: Feature
        '404':
          description: Protected area not found for area_id
          content:
            application/json:
              schema:
                type: string
                example:
                  error: 'Protected area not found for area_id: 123'
      security:
        - BearerAuth: []
  /users/check_tokens:
    get:
      summary: Get token balance info
      description: >-
        Retrieves the total token balance, reserved tokens, and free tokens for
        the user associated with the provided Bearer token.
      operationId: checkTokens
      parameters:
        - name: Authorization
          in: header
          description: >-
            Authorization header with a Bearer token, formatted as 'Bearer
            [JWT]' where [JWT] is the JSON Web Token used for user
            authentication and authorization.
          schema:
            type: string
          example: >-
            Bearer
            eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.your-payload-here.signature
      responses:
        '200':
          description: Token balance details retrieved successfully
          content:
            application/json:
              schema:
                type: string
                example:
                  token_balance: 100
                  reserved_tokens: 22
                  free_tokens: 78
        '403':
          description: >-
            User is not authorized to access this resource. Ensure the Bearer
            token is valid and the user has the required role.
        '500':
          description: Internal server error. Please try again later.
      security:
        - BearerAuth: []
components:
  schemas:
    Analysis:
      type: object
      properties:
        analysisEnd:
          type: string
          description: End date of the analysis
          example: '2024-02-29'
        analysis_end:
          type: string
          description: End date of the analysis
          example: '2024-02-29'
        risk_level:
          type: string
          description: Risk level assessment
          example: Low
        forest_percentage_2020:
          type: number
          description: Forest percentage in 2020
          format: double
          example: 93.07
        indigenous_land:
          $ref: '#/components/schemas/IndigenousLand'
        logging_area:
          type: number
          description: Logging area in hectares
          format: double
          example: 1.08
        forest_area_2020:
          type: number
          description: Forest area in 2020 in hectares
          format: double
          example: 145.31
        risk_reason:
          type: string
          description: Reason for risk assessment
          example: 'Low: Low deforestation detection'
        version:
          type: string
          description: Version of the analysis
          example: '2024-11-13'
        areaHa:
          type: number
          description: Total area in hectares
          format: double
          example: 156.13
        protected_areas:
          $ref: '#/components/schemas/ProtectedAreas'
        deforestation:
          $ref: '#/components/schemas/DeforestationData'
        deforestation_percentage:
          type: number
          description: Deforestation percentage
          format: double
          example: 0.044
        protectedAreas:
          type: array
          description: List of protected area names and their overlap areas in hectares
          example:
            - - Área De Proteção Ambiental
              - 0.24
            - - Rio Negro
              - 156.13
          deprecated: true
          items:
            type: array
            description: List of protected area names and their overlap areas in hectares
            example:
              - - Área De Proteção Ambiental
                - 0.24
              - - Rio Negro
                - 156.13
            deprecated: true
            items:
              type: object
              description: List of protected area names and their overlap areas in hectares
              example:
                - - Área De Proteção Ambiental
                  - 0.24
                - - Rio Negro
                  - 156.13
              deprecated: true
        indigenous_overlap:
          $ref: '#/components/schemas/IndigenousOverlap'
      description: Complete analysis data for a plot
    Coordinate:
      type: object
      properties:
        x:
          type: number
          format: double
        'y':
          type: number
          format: double
        z:
          type: number
          format: double
        m:
          type: number
          format: double
        valid:
          type: boolean
    DeforestationData:
      type: object
      properties:
        total_yearly:
          type: object
          additionalProperties:
            type: number
            description: Total yearly deforestation data
            format: double
          description: Total yearly deforestation data
        total_yearly_jrc:
          type: object
          additionalProperties:
            type: number
            description: Total yearly JRC deforestation data
            format: double
          description: Total yearly JRC deforestation data
        total:
          type: number
          description: Total deforestation
          format: double
          example: 0.069
        total_jrc:
          type: number
          description: Total JRC deforestation
          format: double
          example: 0.069
      description: Deforestation data for a plot
    GeoJsonFeature:
      required:
        - geometry
        - type
      type: object
      properties:
        geometry:
          $ref: '#/components/schemas/Geometry'
        properties:
          type: object
          description: >-
            Additional properties for the feature as key-value pairs. Optional
            properties include `point_ha` (float < 4.0)
          example:
            point_ha: 3.5
        type:
          type: string
          description: Type of the GeoJSON feature
          example: Feature
      description: Represents a GeoJSON feature with geometry and properties
    Geometry:
      description: >-
        Geometry object defining the spatial aspect of the feature, can be
        either Point or Polygon
      oneOf:
        - $ref: '#/components/schemas/Point'
        - $ref: '#/components/schemas/Polygon'
    IndigenousLand:
      type: object
      properties:
        indigenous_land_overlap_summary:
          $ref: '#/components/schemas/IndigenousLandOverlapSummary'
        indigenous_land_details:
          type: array
          description: Detailed information about each overlapping indigenous land
          items:
            $ref: '#/components/schemas/IndigenousLandDetail'
        sources:
          type: array
          description: Sources of indigenous land data
          items:
            $ref: '#/components/schemas/IndigenousLandSource'
      description: Analysis of indigenous lands overlapping with a plot
    IndigenousLandDetail:
      required:
        - id
      type: object
      properties:
        id:
          type: string
          description: Unique identifier of the indigenous land
          example: IL-202
        name:
          type: string
          description: Name of the indigenous land
          example: Yanomami Territory
        government_acknowledged:
          type: boolean
          description: Acknowledgment of government
          example: true
        overlap_area_ha:
          minimum: 0
          type: number
          description: Overlap area in hectares
          format: double
          example: 3.1
        land_status:
          type: string
          description: Status of the land, e.g. 'Community'
          example: Community
      description: Detailed information about an overlapping indigenous land area
    IndigenousLandOverlapSummary:
      required:
        - indigenous_land_overlap
      type: object
      properties:
        indigenous_land_overlap:
          type: boolean
          description: Indicates if the plot overlaps with any indigenous land
        total_overlap_percentage:
          maximum: 100
          minimum: 0
          type: number
          description: Percentage of plot area that overlaps with indigenous land
          format: double
          example: 25.3
        total_overlap_area_ha:
          type: number
          description: Plot area (in hectares) that overlaps with indigenous land
          format: double
          example: 155.3
      description: Summary of indigenous land overlap with plot
    IndigenousLandSource:
      required:
        - source_name
      type: object
      properties:
        source_name:
          type: string
          description: Name of the data source
          example: CNUC
        data_version:
          pattern: ^\d{4}-\d{2}-\d{2}$
          type: string
          description: Version or date of the data
          example: '2024-11-20'
      description: Source of indigenous people data
    IndigenousOverlap:
      type: object
      properties:
        total_overlap_area:
          type: number
          description: Total area of overlap with indigenous territories in hectares
          format: double
          example: 150.5
        overlapping_territories:
          type: array
          description: List of overlapping indigenous territories
          items:
            type: object
            description: List of overlapping indigenous territories
        overlap_percentage:
          maximum: 100
          minimum: 0
          type: number
          description: Percentage of overlap with indigenous territories
          format: double
          example: 25.5
      description: Indigenous territories overlap analysis
      deprecated: true
    Job:
      type: object
      properties:
        username:
          type: string
          description: Name of the user account that created and owns the job
          example: abc_pro
        notes:
          type: string
          description: Additional notes related to the plot
          example: This plot requires frequent irrigation.
        job_id:
          type: string
          description: Unique identifier for the job
          example: a31da612-fefe-4da8-800d-0e7120f5617e
        job_name:
          type: string
          description: Name of the job
          example: August shipment 827128
        plot_ids:
          type: array
          description: A list of IDs of plots to be analyzed in the job
          example:
            - ef6f5727-307f-4e9d-abcb-74a8b6af0366
            - asd9632d-b589-4e05-9c8b-58fed1f9823a3
          items:
            type: string
            description: A list of IDs of plots to be analyzed in the job
            example: >-
              ["ef6f5727-307f-4e9d-abcb-74a8b6af0366","asd9632d-b589-4e05-9c8b-58fed1f9823a3"]
        created_at:
          type: string
          description: Timestamp of job creation
          format: date-time
        updated_at:
          type: string
          description: >-
            Timestamp of job update, for example when the job's analysis is
            complete
          format: date-time
        additional_info:
          type: object
          description: Analysis data for the plot, represented as key-value pairs
          example:
            job_urgency: high
            reviewer: employee A
        token_cost:
          type: integer
          description: Amount of tokens the job costs based on the plots
          format: int32
          example: 8
        harvest_date:
          type: string
          deprecated: true
        status:
          type: string
          description: Current status of the job
          enum:
            - creating
            - pending
            - incomplete
            - done-with-errors
            - done
        plots:
          type: array
          description: List of plots associated with the job
          items:
            $ref: '#/components/schemas/Plot'
        job_visualization_url:
          type: array
          description: >-
            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
          items:
            type: string
            description: >-
              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"]
      description: Job object with metadata and plots with analysis if analyzed
    Plot:
      type: object
      properties:
        username:
          type: string
          description: Username of the account that created the plot, the plot owner
          example: jdoe
        country:
          type: string
          description: Country where the plot is located
          example: United States
        state:
          type: string
          description: State or region where the plot is located
          example: California
        notes:
          type: string
          description: Additional notes related to the plot
          example: This plot requires frequent irrigation.
        analysis:
          $ref: '#/components/schemas/Analysis'
        plot_id:
          type: string
          description: Unique identifier for the plot
          example: ef6f5727-377f-4e9d-abcb-74a8a6bf0366
        plot_name:
          type: string
          description: Name of the plot
          example: East Field
        geojson_features:
          type: array
          items:
            $ref: '#/components/schemas/GeoJsonFeature'
        harvest_dates:
          type: array
          items:
            type: string
            description: List of Harvest dates of the plot
            format: date
            example: '2024-11-01'
        commodity:
          type: string
          description: Type of commodity planted in the plot to do analysis on
          example: cocoa
          enum:
            - wood
            - soy
            - cocoa
            - coffee
            - palm_oil
            - beef
            - rubber
        lat:
          type: string
          description: Latitude of the plot's center
          example: '34.052235'
        lon:
          type: string
          description: Longitude of the plot's center
          example: '-118.243683'
        area_ha:
          type: number
          description: Area of the plot in hectares
          format: double
          example: 12.5
        tokens_cost:
          type: integer
          description: Cost of the analyzing the plot in tokens
          format: int32
          example: 150
        created_at:
          type: string
          description: Timestamp of plot creation
          format: date-time
        updated_at:
          type: string
          description: Timestamp of the last plot update
          format: date-time
        analysis_image:
          type: string
          description: URL for the visualization of the analysis of the plot
          example: https://example.com/images/plot-analysis.jpg
        additional_info:
          type: object
          description: Additional information about the plot as key-value pairs
          example:
            soil_quality: high
            access: restricted
      description: Plot object with metadata and analysis if a job ran analysis on it
    Point:
      required:
        - coordinates
      type: object
      properties:
        type:
          type: string
        coordinates:
          type: array
          description: An array of 2 coordinates [longitude, latitude]
          example:
            - 20.01750003723791
            - -0.03010959663886581
          items:
            type: number
            description: An array of 2 coordinates [longitude, latitude]
            format: double
    Polygon:
      required:
        - coordinates
      type: object
      properties:
        type:
          type: string
        coordinates:
          type: array
          description: >-
            An array of [longitude, latitude] pairs. For polygons, the first and
            last coordinates should be the same to close the shape
          example:
            - - - 20.01750003723791
                - -0.03010959663886581
              - - 20.01857837976968
                - -0.029779656058593673
              - - 20.01958831997618
                - -0.031143678695514154
              - - 20.018349030798674
                - -0.03160640023472183
              - - 20.017491989905864
                - -0.03011764397074046
          items:
            type: array
            description: >-
              An array of [longitude, latitude] pairs. For polygons, the first
              and last coordinates should be the same to close the shape
            example:
              - - - 20.01750003723791
                  - -0.03010959663886581
                - - 20.01857837976968
                  - -0.029779656058593673
                - - 20.01958831997618
                  - -0.031143678695514154
                - - 20.018349030798674
                  - -0.03160640023472183
                - - 20.017491989905864
                  - -0.03011764397074046
            items:
              type: array
              description: >-
                An array of [longitude, latitude] pairs. For polygons, the first
                and last coordinates should be the same to close the shape
              example:
                - - - 20.01750003723791
                    - -0.03010959663886581
                  - - 20.01857837976968
                    - -0.029779656058593673
                  - - 20.01958831997618
                    - -0.031143678695514154
                  - - 20.018349030798674
                    - -0.03160640023472183
                  - - 20.017491989905864
                    - -0.03011764397074046
              items:
                type: number
                description: >-
                  An array of [longitude, latitude] pairs. For polygons, the
                  first and last coordinates should be the same to close the
                  shape
                format: double
    ProtectedAreaDetail:
      required:
        - area_id
      type: object
      properties:
        area_id:
          type: string
          description: Unique identifier of the protected area
          example: '37514'
        area_name:
          type: string
          description: Name of the protected area
          example: Cordillera Beata
        local_name:
          type: string
          description: Local name of the protected area
          example: Cordillera Beata
        source_name:
          type: string
          description: Source/authority providing the protected area data
          example: Parques Nacionales Naturales de Colombia
        iucn_category:
          type: string
          description: IUCN protected area category
          example: V
          enum:
            - Ia
            - Ib
            - II
            - III
            - IV
            - V
            - VI
        overlap_area_ha:
          minimum: 0
          type: number
          description: Area of overlap in hectares
          format: double
          example: 2208.6384
        extractive_activity_legality:
          type: string
          description: Legality status of extractive activities within the protected area
          example: limited
        extractive_activity_conditions:
          type: string
          description: >-
            Conditions or notes describing what extractive activities are
            permitted
          example: 'Activities permitted: Research, education, and eco-tourism.'
        regulation_names:
          type: array
          description: Names/titles of applicable regulations
          items:
            type: string
          example:
            - DECRETO 622 DE MARZO 16 DE 1977
            - LEY 99 DE 1993
        regulation_urls:
          type: array
          description: URLs linking to applicable regulations
          items:
            type: string
            format: uri
          example:
            - >-
              https://old.parquesnacionales.gov.co/portal/wp-content/uploads/2018/07/Decreto_622_de_1977.pdf
            - >-
              https://www.minambiente.gov.co/wp-content/uploads/2021/08/ley-99-1993.pdf
            - https://www.funcionpublica.gov.co/eva/gestornormativo/norma.php
        type:
          type: string
          description: Type/classification of the protected area
          example: Reserva Natural
      description: Detailed information about an overlapping protected area
    ProtectedAreaOverlapSummary:
      required:
        - protected_area_overlap
      type: object
      properties:
        protected_area_overlap:
          type: boolean
          description: Indicates if the plot overlaps with any protected area
        total_overlap_percentage:
          maximum: 100
          minimum: 0
          type: number
          description: Percentage of plot area that overlaps with protected areas
          format: double
          example: 25.3
        total_overlap_area_ha:
          type: number
          description: Plot area (in hectares) that overlaps with protected areas
          format: double
          example: 155.3
        most_restrictive_extractive_activity_legality:
          type: string
          description: >-
            Legality status of the most restrictive extractive activities of all
            the extractive activities returned with the protected areas
          example: prohibited
      description: Summary of protected area overlap with plot
    ProtectedAreaSource:
      required:
        - source_name
      type: object
      properties:
        source_name:
          type: string
          description: Name of the data source
          example: CNUC
        data_version:
          pattern: ^\d{4}-\d{2}-\d{2}$
          type: string
          description: Version or date of the data
          example: '2024-11-20'
      description: Source of protected area data
    ProtectedAreas:
      type: object
      properties:
        protected_area_overlap_summary:
          $ref: '#/components/schemas/ProtectedAreaOverlapSummary'
        protected_area_details:
          type: array
          description: Detailed information about each overlapping protected area
          items:
            $ref: '#/components/schemas/ProtectedAreaDetail'
        sources:
          type: array
          description: Sources of protected area data
          items:
            $ref: '#/components/schemas/ProtectedAreaSource'
      description: Analysis of protected areas overlapping with a plot
    JobCheckConfig:
      type: object
      properties:
        type:
          type: string
          description: >-
            Check type to run. For now only 'eudr' check is supported. Use the
            string value 'eudr'.
          example: eudr
          enum:
            - eudr
            - protected-area
            - indigenous-land
        config:
          type: object
          additionalProperties:
            type: object
            description: >-
              Optional check-level configuration. Only needed when required
              fields are missing from plot registration.

              For EUDR, provide 'harvest_date' and/or 'commodity' if they were
              not set on the plot. If they were set they will be overriden by
              config here.
            example:
              harvest_date: '2024-11-01'
              commodity: cocoa
          description: >-
            Optional check-level configuration. Only needed when required fields
            are missing from plot registration.

            For EUDR, provide 'harvest_date' and/or 'commodity' if they were not
            set on the plot. If they were set they will be overriden by config
            here.
          example:
            harvest_date: '2024-11-01'
            commodity: cocoa
        per_plot:
          type: object
          additionalProperties:
            type: object
            additionalProperties:
              type: object
              description: >-
                Per-plot overrides keyed by plot_id. Values override entries
                from 'config' for that specific plot.

                Global 'config' applies to all plots unless a plot has an entry
                here, in which case the per_plot entry takes precedence.
              example:
                ef6f5727-377f-4e9d-abcb-74a8a6bf0366:
                  harvest_date: '2024-12-01'
            description: >-
              Per-plot overrides keyed by plot_id. Values override entries from
              'config' for that specific plot.

              Global 'config' applies to all plots unless a plot has an entry
              here, in which case the per_plot entry takes precedence.
            example:
              ef6f5727-377f-4e9d-abcb-74a8a6bf0366:
                harvest_date: '2024-12-01'
          description: >-
            Per-plot overrides keyed by plot_id. Values override entries from
            'config' for that specific plot.

            Global 'config' applies to all plots unless a plot has an entry
            here, in which case the per_plot entry takes precedence.
          example:
            ef6f5727-377f-4e9d-abcb-74a8a6bf0366:
              harvest_date: '2024-12-01'
      description: >-
        Optional list of check definitions to run for this job. If omitted or
        empty, a single 'eudr' check is run by default. Currently only 'eudr' is
        supported; additional check types will be added in the future. 
      example:
        - type: eudr
          config:
            harvest_date: '2024-11-01'
            commodity: cocoa
          per_plot:
            ef6f...0366:
              harvest_date: '2024-12-01'
    JobInput:
      required:
        - plot_ids
      type: object
      properties:
        job_name:
          type: string
          description: Name of the job
          example: Planting season analysis for Q1
        plot_ids:
          type: array
          description: List of plot IDs that belong to the user to be analyzed in the job
          example:
            - ef6f5727-307f-4e9d-abcb-74a8b6af0366
            - asd9632d-b589-4e05-9c8b-58fed1f9823a3
          items:
            type: string
            description: List of plot IDs that belong to the user to be analyzed in the job
            example: >-
              ["ef6f5727-307f-4e9d-abcb-74a8b6af0366","asd9632d-b589-4e05-9c8b-58fed1f9823a3"]
        notes:
          type: string
          description: Additional notes about the job
          example: Analysis for initial planting
        additional_info:
          type: object
          description: >-
            Additional information about the job as key-value pairs, where keys
            and values are both strings
          example:
            soilQuality: High
            irrigationType: Drip
        checks:
          type: array
          description: >-
            Optional list of check definitions to run for this job. If omitted
            or empty, a single 'eudr' check is run by default. Currently only
            'eudr' is supported; additional check types will be added in the
            future. 
          example:
            - type: eudr
              config:
                harvest_date: '2024-11-01'
                commodity: cocoa
              per_plot:
                ef6f...0366:
                  harvest_date: '2024-12-01'
          items:
            $ref: '#/components/schemas/JobCheckConfig'
      description: Input data required to create a new job
    AuthToken:
      type: object
      properties:
        token:
          type: string
          description: JSON Web Token (JWT)
          example: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.your-payload-here.signature
    PlotAnalysisRunDTO:
      type: object
      properties:
        run_id:
          type: string
        job_id:
          type: string
        plot_id:
          type: string
        check_type:
          type: string
        effective_config:
          type: object
          additionalProperties:
            type: object
        status:
          type: string
        error:
          type: string
        analysis_image:
          type: string
        tokens_cost:
          type: integer
          format: int32
        created_at:
          type: string
        updated_at:
          type: string
        analysis:
          $ref: '#/components/schemas/Analysis'
    GeoJson:
      required:
        - features
        - type
      type: object
      properties:
        type:
          type: string
        features:
          type: array
          description: A list of GeoJson Features that this FeatureCollection is made of
          items:
            $ref: '#/components/schemas/GeoJsonFeature'
      description: GeoJSON representation of the plot's geographical data
      example:
        type: FeatureCollection
        features:
          - type: Feature
            geometry:
              type: Polygon
              coordinates:
                - - - 20.01750003723791
                    - -0.03010959663886581
                  - - 20.01857837976968
                    - -0.029779656058593673
                  - - 20.01958831997618
                    - -0.031143678695514154
                  - - 20.018349030798674
                    - -0.03160640023472183
                  - - 20.017491989905864
                    - -0.03011764397074046
    ProtectedAreasAnalysisRequest:
      type: object
      properties:
        plot_ids:
          type: array
          items:
            type: string
        geojson:
          $ref: '#/components/schemas/GeoJson'
    PlotInput:
      required:
        - geojson
      type: object
      properties:
        geojson:
          $ref: '#/components/schemas/GeoJson'
        harvest_date:
          type: string
          description: >-
            The harvest date of the plot and the end date of analysis, in the
            format yyyy-MM-dd; if not provided here, it must be specified when
            executing the job
          format: date
          example: '2023-11-01'
        commodity:
          type: string
          description: >-
            The commodity type planted in the plot for analysis; if not provided
            here, it must be specified when executing the job
          example: wood
          enum:
            - wood
            - soy
            - cocoa
            - coffee
            - palm_oil
            - beef
            - rubber
        plot_name:
          type: string
          description: Name assigned to the plot
          example: My sustainable plot
        notes:
          type: string
          description: Additional notes related to the plot
          example: GeoJSON needs to be revised
        additional_info:
          type: object
          description: Additional information as key-value pairs
          example:
            previous_risk_assessment: high
            urgency: low
      description: Input model for creating a plot
    JobsListResponse:
      type: object
      properties:
        jobs:
          type: array
          description: List of jobs
          example:
            - job_id: a31da612-fefe-4da8-800d-0e7120f5617e
              job_name: August shipment 827128
              plot_ids:
                - ef6f5727-307f-4e9d-abcb-74a8b6af0366
                - asd9632d-b589-4e05-9c8b-58fed1f9823a3
              username: abc_pro
              created_at: '2024-09-04T18:18:01'
              updated_at: '2024-09-04T18:18:03'
              notes: Initial batch run
              additional_info:
                job_urgency: high
                reviewer: employee A
              token_cost: 8
              status: pending
              job_visualization_url:
                - https://jobviz.s3.eu-central-1.amazonaws.com/path/to/plot1.png
                - https://jobviz.s3.eu-central-1.amazonaws.com/path/to/plot2.png
          items:
            $ref: '#/components/schemas/Job'
        meta:
          type: object
          additionalProperties:
            type: object
            description: >-
              Pagination metadata containing has_more, next_cursor, limit, and
              count
            example:
              next_cursor: >-
                eyJsZWsiOiJZM0psWVhSbFpFRjBIbE02TWpBeU5TMHdOeTB6TVZReE56b3lNem8xTVI5d2JHOTBTV1FlVXpwak9EWTVaRFJsWlMwM09EZ3lMVFJoTjJFdFlqSmhaQzB4TWpkak1XRXlNemM0TjJNZmRYTmxjbTVoYldVZVV6cHZjR1Z1WVhSc1lYTmZiV0ZwYmciLCJ1Ijoib3BlbmF0bGFzX21haW4iLCJ2IjoxLCJleHAiOjE3NTYzMDc3OTY1MDgsImlhdCI6MTc1NjMwNTk5NjUwOH0.J1gFjyqEdHEmSYgaUVLH-YYePiBxNTc82LOXTowRjbA
              limit: 100
              count: 100
              has_more: true
          description: >-
            Pagination metadata containing has_more, next_cursor, limit, and
            count
          example:
            next_cursor: >-
              eyJsZWsiOiJZM0psWVhSbFpFRjBIbE02TWpBeU5TMHdOeTB6TVZReE56b3lNem8xTVI5d2JHOTBTV1FlVXpwak9EWTVaRFJsWlMwM09EZ3lMVFJoTjJFdFlqSmhaQzB4TWpkak1XRXlNemM0TjJNZmRYTmxjbTVoYldVZVV6cHZjR1Z1WVhSc1lYTmZiV0ZwYmciLCJ1Ijoib3BlbmF0bGFzX21haW4iLCJ2IjoxLCJleHAiOjE3NTYzMDc3OTY1MDgsImlhdCI6MTc1NjMwNTk5NjUwOH0.J1gFjyqEdHEmSYgaUVLH-YYePiBxNTc82LOXTowRjbA
            limit: 100
            count: 100
            has_more: true
      description: Response envelope for listing jobs including pagination metadata
    PlotsListResponse:
      type: object
      properties:
        plots:
          type: array
          description: List of plots
          items:
            $ref: '#/components/schemas/Plot'
        meta:
          type: object
          additionalProperties:
            type: object
            description: >-
              Pagination metadata containing has_more, next_cursor, limit, and
              count
            example:
              next_cursor: >-
                eyJsZWsiOiJZM0psWVhSbFpFRjBIbE02TWpBeU5TMHdOeTB6TVZReE56b3lNem8xTVI5d2JHOTBTV1FlVXpwak9EWTVaRFJsWlMwM09EZ3lMVFJoTjJFdFlqSmhaQzB4TWpkak1XRXlNemM0TjJNZmRYTmxjbTVoYldVZVV6cHZjR1Z1WVhSc1lYTmZiV0ZwYmciLCJ1Ijoib3BlbmF0bGFzX21haW4iLCJ2IjoxLCJleHAiOjE3NTYzMDc3OTY1MDgsImlhdCI6MTc1NjMwNTk5NjUwOH0.J1gFjyqEdHEmSYgaUVLH-YYePiBxNTc82LOXTowRjbA
              limit: 100
              count: 100
              has_more: true
          description: >-
            Pagination metadata containing has_more, next_cursor, limit, and
            count
          example:
            next_cursor: >-
              eyJsZWsiOiJZM0psWVhSbFpFRjBIbE02TWpBeU5TMHdOeTB6TVZReE56b3lNem8xTVI5d2JHOTBTV1FlVXpwak9EWTVaRFJsWlMwM09EZ3lMVFJoTjJFdFlqSmhaQzB4TWpkak1XRXlNemM0TjJNZmRYTmxjbTVoYldVZVV6cHZjR1Z1WVhSc1lYTmZiV0ZwYmciLCJ1Ijoib3BlbmF0bGFzX21haW4iLCJ2IjoxLCJleHAiOjE3NTYzMDc3OTY1MDgsImlhdCI6MTc1NjMwNTk5NjUwOH0.J1gFjyqEdHEmSYgaUVLH-YYePiBxNTc82LOXTowRjbA
            limit: 100
            count: 100
            has_more: true
      description: Response envelope for listing plots including pagination metadata
